podcastrr/README_DOCKER.md

# Docker Setup for Podcastrr

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

## Prerequisites

- [Docker](https://docs.docker.com/get-docker/)
- [Docker Compose](https://docs.docker.com/compose/install/)

## 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:

```yaml
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.