danjac / jcasts

This is the source code for a simple, easy to use podcatcher web application. You are free to use this source to host the app yourself.

Running Radiofeed on your local machine

Radiofeed requires the following dependencies:

• Python 3.10+
• Node 16+
• Poetry

Additional requirements

For ease of local development a docker-compose.yml is provided which includes:

• PostgreSQL
• Redis
• Mailhog

Just run docker-compose:

docker-compose build && docker-compose up -d

You can use these images if you want, or use a local install of PostgreSQL or Redis.

Current tested versions are PostgresSQL 14+ and Redis 6.2+.

Django setup

Copy the file .env.example to .env and set the variables accordingly. These settings should work as-is with the Docker containers defined in docker-compose.yml.

To install dependencies:

poetry install

We'll assume all Python commands from this point are run in your Poetry environment.

Install the NLTK corpora:

xargs python -m nltk.downloader <./nltk.txt

Finally, run migrations:

python manage.py migrate

You can also install default iTunes categories and approx 1000+ sample podcasts from fixtures:

python manage.py loaddata podcasts \
    radiofeed/podcasts/fixtures/categories.json.gz \
    radiofeed/podcasts/fixtures/podcasts.json.gz

This should provide some useful data to get started with.

Frontend setup

To install frontend dependencies just run npm ci.

Running development environment

The easiest way to spin up your local development environment is using Honcho:

honcho -f Procfile.local start

This will start up:

• Django development server
• Background workers
• tailwindcss and webpack for building frontend assets on the fly

Honcho should be installed in your virtualenv.

Tests can be run with pytest:

python -m pytest

Use mypy for type-checking:

python -m mypy radiofeed

Deployment

The following environment variables should be set in your production installation. Some providers may set some of these automatically e.g. DATABASE_URL:

DJANGO_SETTINGS_MODULE='radiofeed.settings.production'
DATABASE_URL=''
REDIS_URL=''
ADMIN_URL='some-random-url/'
ADMINS='[email protected]'
ALLOWED_HOSTS='my-domain'
MAILGUN_API_KEY='<mailgun_api_key>'
MAILGUN_SENDER_DOMAIN='my-domain'
SECRET_KEY='<secret>'
SENTRY_URL='<sentry-url>'
CONTACT_EMAIL='[email protected]'

A Procfile is provided for Heroku-like deployments (including Dokku, Railway etc).

Crons

In production you should set up the following cron jobs to run these Django commands (with suggested schedules and arguments):

Parse podcast RSS feeds:

*/6 * * * * python manage.py feed_updates

Generate similar recommendations for each podcast:

15 6 * * * python manage.py recommendations

Send podcast recommendations to users:

15 9 * * 1 python manage.py recommendations --email

An app.json configuration with these cron schedules is included for Dokku deployment.

Updating dependencies

To upgrade Python dependencies just use Poetry:

poetry update

This will update poetry.lock which should be commmitted to the repo. Refer to Poetry docs for more details.

If you are using Heroku, Dokku or similar for deployment you should also re-generate the requirements.txt file, as Heroku will automatically detect and reinstall any changes:

poetry export --without-hashes -o requirements.txt

You can update frontend dependencies as usual with npm:

npm update

Again, the updated package-lock.json file should be committed to the repo.