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. A Dockerfile is provided for production deployments.

Development

Listenwave requires the following basic dependencies to get started:

• Python 3.14
• uv

Note: if you don't have the right version of Python you can use uv python install 3.14.x.

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

• PostgreSQL
• Redis
• Mailpit (for local email testing)

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

Current tested versions are PostgreSQL 18 and Redis 8.

The justfile has some convenient shortcuts for local development, including:

• just install: download and install local dependencies
• just update: update dependencies to latest available versions
• just serve: run the development server and Tailwind JIT compiler
• just dj [command]: run Django management commands
• just test: run unit tests
• just check: run code linters and formatters, type checkers, and unit tests
• just start and just stop: start/stop Docker dev containers

Run just to see all available commands.

NOTE: Default settings provided should be suitable for local development, but if you are not using the Docker images you may need to adjust database connection and other settings by creating a .env file in the project root.

Stack

The Listenwave stack includes:

• Django
• HTMX
• AlpineJS
• Tailwind
• PostgreSQL

Deployment

The following environment variables should be set in your production installation (changing listenwave.app for your domain).

ALLOWED_HOSTS=listenwave.app
DATABASE_URL=<database-url>
REDIS_URL=<redis-url>
ADMIN_URL=<admin-url>
ADMINS=me@listenwave.app
EMAIL_HOST=mg.listenwave.app
MAILGUN_API_KEY=<mailgun_api_key>
SECRET_KEY=<secret>
SENTRY_URL=<sentry-url>

Some settings such as DATABASE_URL may be set automatically by certain PAAS providers such as Heroku. Consult your provider documentation as required.

EMAIL_HOST should be set to your Mailgun sender domain along with MAILGUN_API_KEY if you are using Mailgun.

You should ensure the SECRET_KEY is sufficiently random: run the generate_secret_key custom Django command to create a suitable random string.

In some server configurations your load balancer (e.g. Nginx) may set the strict-transport-security headers by default. If not, you can set the environment variable USE_HSTS=true.

In production it's also a good idea to set ADMIN_URL to something other than the default admin/. Make sure it ends in a forward slash, e.g. some-random-path/.

A Dockerfile is provided for standard container deployments which should also work on Heroku or another PAAS.

Once you have access to the Django Admin, you should configure the default Site instance with the correct production name and domain.

The ansible directory contains full Playbooks for a multi-server K3s deployment to a shared hosting provider such as Hetzner or Digital Ocean, this can be copied and modified for your particular use-case.