How to install Castopod?

Castopod was thought-out to be easy to install. Whether using dedicated or shared hosting, you can install it on most PHP-MySQL compatible web servers.

Note

We've released official Docker images for Castopod!

If you prefer using Docker, you may skip this and go straight to the docker documentation for Castopod.

Requirements

  • PHP v8.1 or higher
  • MySQL version 5.7 or higher or MariaDB version 10.2 or higher
  • HTTPS support
  • An ntp-synced clock to validate federation's incoming requests

PHP v8.1 or higher

PHP version 8.1 or higher is required, with the following extensions installed:

Additionally, make sure that the following extensions are enabled in your PHP:

  • json (enabled by default - don't turn it off)
  • xml (enabled by default - don't turn it off)
  • mysqlnd

MySQL compatible database

We recommend using MariaDB.

Warning

Castopod only works with supported MySQL 5.7 or higher compatible databases. It will break with the previous MySQL v5.6 for example as its end of life was on February 5, 2021.

You will need the server hostname, database name, username and password to complete the installation process. If you do not have these, please contact your server administrator.

Privileges

User must have at least these privileges on the database for Castopod to work: CREATE, ALTER, DELETE, EXECUTE, INDEX, INSERT, SELECT, UPDATE, REFERENCES, CREATE VIEW.

(Optional) FFmpeg v4.1.8 or higher for Video Clips

FFmpeg version 4.1.8 or higher is required if you want to generate Video Clips. The following extensions must be installed:

  • FreeType 2 library for gd.

(Optional) Other recommendations

  • Redis for better cache performances.
  • CDN for static files caching and better performances.
  • e-mail gateway for lost passwords.

Install instructions

Pre-requisites

  1. Get a Web Server with requirements installed

  2. Create a MySQL database for Castopod with a user having access and modification privileges (for more info, see MySQL compatible database).

  3. Activate HTTPS on your domain with an SSL certificate.

  4. Download and unzip the latest Castopod Package onto the web server if you haven’t already.

    • ⚠️ Set the web server document root to the public/ sub-folder within the castopod folder.
  5. Add cron tasks on your web server for various background processes (replace the paths accordingly):

       * * * * * /path/to/php /path/to/castopod/spark tasks:run >> /dev/null 2>&1
    

    Note - If you do not add this cron task, the following Castopod features will not work:

    • Importing a podcast from an existing RSS feed
    • Broadcasting social activities to your followers in the fediverse
    • Broadcasting episodes to open hubs using WebSub
    • Generating video clips - requires FFmpeg
  1. Run the Castopod install script by going to the install wizard page (https://your_domain_name.com/cp-install) in your favorite web browser.
  2. Follow the instructions on your screen.
  3. Start podcasting!

Note

The install script writes a .env file in the package root. If you cannot go through the install wizard, you can create and edit the .env file manually based on the .env.example file.

Using CLI

  1. Create a .env file in the package root based on the .env.example file.

  2. Initialize the database using:

    php spark install:init-database
    
  3. Create the superadmin user using:

    php spark install:create-superadmin
    
  4. Head on to your admin gateway to start podcasting!

Email/SMTP setup

Email configuration is required for some features to work properly (eg. retrieving your forgotten password, sending instructions to premium subscribers, …)

You may add your email configuration in your instance's .env like so:

# […]

email.fromEmail="your_email_address"
email.SMTPHost="your_smtp_host"
email.SMTPUser="your_smtp_user"
email.SMTPPass="your_smtp_password"

Email config options

Variable nameTypeDefault
fromEmailstringundefined
fromNamestring"Castopod"
SMTPHoststringundefined
SMTPUserstringundefined
SMTPPassstringundefined
SMTPPortnumber25
SMTPCrypto["tls" or "ssl"]"tls"

Media storage

By default, files are saved to the public/media folder using the file system. If you need to relocate the media folder to a different location, you can specify it in your .env file as shown below:

# […]

media.root="media"
media.storage="/mnt/storage"

In this example, the files will be saved to the /mnt/storage/media folder. Make sure to also update your web server configuration to reflect this change.

S3

If you prefer storing your media files on an S3 compatible storage, you may specify it in your .env:

# […]

media.fileManager="s3"
media.s3.endpoint="your_s3_host"
media.s3.key="your_s3_key"
media.s3.secret="your_s3_secret"
media.s3.region="your_s3_region"

S3 config options

Variable nameTypeDefault
endpointstringundefined
keystringundefined
secretstringundefined
regionstringundefined
bucketstringcastopod
protocolnumberundefined
pathStyleEndpointbooleanfalse
keyPrefixstringundefined

Community packages

If you don't want to bother with installing Castopod manually, you may use one of the packages created and maintained by the open-source community.

Install with YunoHost

YunoHost is a distribution based on Debian GNU/Linux made up of free and open-source software packages. It manages the hardships of self-hosting for you.