podcastrr/README_FORGEJO.md

Podcastrr - Forgejo Integration Guide

This guide explains how to set up and use Podcastrr with Forgejo for CI/CD and container registry integration.

Prerequisites

• A Forgejo instance with:
  • Forgejo Actions enabled (preferred) or CI/CD capabilities (Drone integration)
  • Container registry enabled
• Docker and Docker Compose installed on your local machine
• Git installed on your local machine

Setup

1. Repository Setup

1. Create a new repository in your Forgejo instance
2. Push this codebase to your new repository:

   git init
   git add .
   git commit -m "Initial commit"
   git remote add origin https://your-forgejo-instance.com/username/podcastrr.git
   git push -u origin main
   

2. Secrets Configuration

In your Forgejo repository settings, add the following secrets:

For Forgejo Actions (Recommended)

Navigate to your repository settings, then Actions, then Secrets:

• FORGEJO_REGISTRY: Your Forgejo container registry URL (e.g., registry.your-forgejo-instance.com)
• FORGEJO_USERNAME: Your Forgejo username
• FORGEJO_PASSWORD: Your Forgejo password

For Drone CI (Legacy)

Navigate to your repository settings, then Secrets:

• docker_username: Your Forgejo username or container registry username
• docker_password: Your Forgejo password or container registry password
• webhook_url (optional): URL for build notifications

3. Environment Variables

For Drone CI (Legacy)

Configure the following environment variables in your Forgejo CI/CD settings:

• DRONE_REGISTRY: Your Forgejo container registry URL (e.g., registry.your-forgejo-instance.com)

CI/CD Pipeline

Forgejo Actions (Recommended)

The project includes Forgejo Actions workflows in the .forgejo/workflows/ directory:

1. Demo Workflow (.forgejo/workflows/demo.yaml): A simple example workflow that runs on every push.

2. Build and Publish Workflow (.forgejo/workflows/build.yml): A comprehensive CI/CD pipeline that:

   • Runs tests on every push and pull request
   • Builds and pushes a Docker image to your container registry on pushes to the main branch or tags
   • Provides build status notifications

To use Forgejo Actions:

1. Ensure "Enable Repository Actions" is checked in your repository settings
2. The workflows will automatically run when you push to the repository
3. View results in the Actions tab of your repository

Drone CI (Legacy)

The included .drone.yml file defines a legacy CI/CD pipeline that:

1. Runs tests on every push and pull request
2. Builds and pushes a Docker image to your container registry on pushes to the main branch
3. Sends notifications about build status (if configured)

Using the Docker Image

Pulling from Forgejo Container Registry

docker pull registry.your-forgejo-instance.com/username/podcastrr:latest

Running with Docker Compose

1. Create a .env file with your configuration (see .env.example)
2. Update the docker-compose.yml file to use your image:

version: '3.8'

services:
  app:
    image: registry.your-forgejo-instance.com/username/podcastrr:latest
    ports:
      - "5000:5000"
    volumes:
      - ./downloads:/app/downloads
      - ./instance:/app/instance
    environment:
      - FLASK_ENV=production
      - SECRET_KEY=change_this_to_a_secure_random_string
      - DATABASE_URI=sqlite:///instance/podcastrr.db
      - DOWNLOAD_PATH=/app/downloads
      - LOG_LEVEL=INFO
    restart: unless-stopped

3. Run the application:

docker-compose up -d

Building Locally

If you want to build the Docker image locally:

docker build -t podcastrr:local .

Troubleshooting

• CI/CD Pipeline Failures: Check the build logs in Forgejo for detailed error messages
• Container Registry Issues: Ensure your Forgejo instance has the container registry enabled and you have proper permissions
• Docker Image Not Found: Verify the image name and tag in your docker-compose.yml file

Additional Resources

• Forgejo Documentation
• Drone CI Documentation
• Docker Documentation