podcastrr/README_DOCKER.md

Docker Setup for Podcastrr

This document explains how to run Podcastrr using Docker and Docker Compose.

Prerequisites

• Docker
• Docker Compose

Quick Start

Option 1: Using the published Docker image from Forgejo registry (recommended for production)

1. Clone the repository:

   git clone https://github.com/yourusername/podcastrr.git
   cd podcastrr
   

2. Create a .env file with the following variables:

   FORGEJO_REGISTRY=your-forgejo-registry-url
   FORGEJO_USERNAME=your-username
   PORT=5000
   FLASK_ENV=production
   SECRET_KEY=your_secret_key
   DATABASE_URI=sqlite:///instance/podcastrr.db
   DOWNLOAD_PATH=/app/downloads
   

3. Start the application using Docker Compose:

   docker-compose up -d
   

4. Access the application at http://localhost:5000 (or the port you specified in the .env file)

Option 2: Building from local Dockerfile (for development)

1. Clone the repository:

   git clone https://github.com/yourusername/podcastrr.git
   cd podcastrr
   

2. Modify the docker-compose.yml file to use the local build instead of the published image:

   • Comment out the image: line
   • Uncomment the build: section

3. Start the application using Docker Compose:

   docker-compose up -d
   

4. Access the application at http://localhost:5000

Configuration

The application is configured using environment variables in the .env file or directly in the docker-compose.yml file. You can modify these variables to customize the application:

Forgejo Registry Variables (for using the published Docker image)

• FORGEJO_REGISTRY: The URL of your Forgejo registry (e.g., registry.forgejo.example.com)
• FORGEJO_USERNAME: Your Forgejo username

Application Variables

• PORT: The port on which the application will be accessible (default: 5000)
• FLASK_ENV: Set to development for development mode or production for production mode
• SECRET_KEY: A secret key for securing the Flask application (change this to a secure random string)
• DATABASE_URI: The URI for the SQLite database
• DOWNLOAD_PATH: The path where podcast episodes will be downloaded
• LOG_LEVEL: The logging level (INFO, DEBUG, WARNING, ERROR, CRITICAL)

Persistent Data

The Docker Compose configuration creates two volumes for persistent data:

1. ./downloads:/app/downloads: Stores downloaded podcast episodes
2. ./instance:/app/instance: Stores the SQLite database

These directories will be created in your project folder and will persist data between container restarts.

Building the Docker Image

If you've made changes to the application code and want to rebuild the Docker image:

docker-compose build

Stopping the Application

To stop the application:

docker-compose down

Viewing Logs

To view the application logs:

docker-compose logs -f

Troubleshooting

Database Issues

If you encounter database issues, you can try:

1. Stopping the application:

   docker-compose down
   

2. Removing the instance directory:

   rm -rf instance
   

3. Starting the application again:

   docker-compose up -d
   

This will recreate the database from scratch.

Permission Issues

If you encounter permission issues with the downloads or instance directories, ensure that they are writable by the Docker container:

chmod -R 777 downloads instance

Note: This is not recommended for production environments. Instead, configure proper user permissions.

CI/CD Pipeline

This project includes a CI/CD pipeline configured in .forgejo/workflows/build.yml that automatically builds and publishes a Docker image to the Forgejo Container Registry when changes are pushed to the main branch or when a new tag is created.

How it works

1. When code is pushed to the main branch or a new tag is created, the CI/CD pipeline is triggered.
2. The pipeline first runs tests to ensure the code is working correctly.
3. If the tests pass, the pipeline builds a Docker image using the Dockerfile in the repository.
4. The Docker image is tagged with:
   • The branch name (for pushes to branches)
   • The PR number (for pull requests)
   • The semantic version (for tags in the format v*)
   • The short SHA of the commit
   • latest (for the most recent build)
5. The Docker image is pushed to the Forgejo Container Registry at ${FORGEJO_REGISTRY}/${FORGEJO_USERNAME}/podcastrr.

Docker-in-Docker for CI/CD

The CI/CD pipeline uses Docker-in-Docker (DinD) provided by the Forgejo runner to build and push Docker images. This approach has several advantages:

1. Isolation: The Docker daemon runs in its own container, providing better isolation.
2. Security: Reduces the attack surface by not requiring privileged access to the host.
3. Consistency: Ensures a consistent Docker environment for all builds.

The CI/CD workflow connects to the Docker-in-Docker service using the DOCKER_HOST environment variable:

env:
  DOCKER_HOST: tcp://docker-in-docker:2375

Note: The Docker-in-Docker service is provided by the Forgejo runner infrastructure and does not need to be configured in your docker-compose.yml file.

Using the published Docker image

To use the published Docker image in your deployment:

1. Set the FORGEJO_REGISTRY and FORGEJO_USERNAME environment variables in your .env file.
2. Use the docker-compose.yml file as configured (with the image: line uncommented).
3. Run docker-compose up -d to start the application using the published Docker image.

This allows you to deploy the application without having to build the Docker image locally, making deployments faster and more consistent.