166 lines
4.9 KiB
Markdown
166 lines
4.9 KiB
Markdown
# 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`.
|
|
|
|
### 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.
|