Skip to main content

​
Overview

Copr supports Docker Compose to spawn the complete development stack on your local machine, including all components: frontend, backend, builders, distgit, keygen, and supporting services.

​
Prerequisites

​
Required Software

  • Docker: Container runtime
  • Docker Compose: Multi-container orchestration
  • Git: Version control

​
Installation

Fedora/RHEL: 
sudo dnf install docker docker-compose git
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
Log out and back in for group membership to take effect. Ubuntu/Debian: 
sudo apt install docker.io docker-compose git
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
Note: For rootless Podman setup, see Docker on Fedora.

​
Quick Start

Get up and running in minutes:
1

Clone the repository

git clone https://github.com/fedora-copr/copr.git
cd copr
2

Start the Docker stack

docker-compose up -d
This command will take several minutes to complete on first run as it builds all container images and initializes services.
3

Initialize the database

docker exec -it copr_frontend_1 bash
[copr-fe@frontend /]$ init-database.sh
[copr-fe@frontend /]$ exit
4

Access the Frontend

Open your browser to: http://localhost:5000You should see the Copr web interface.

​
Container Architecture

The Docker Compose setup includes these services:

​
Core Services

ServiceContainer NameDescription
frontendcopr_frontend_1Web UI and API server
databasecopr_database_1PostgreSQL database
backend-buildcopr_backend-build_1Build task dispatcher
backend-actioncopr_backend-action_1Action task dispatcher
backend-logcopr_backend-log_1Logging service
backend_httpdcopr_backend_httpd_1Build results HTTP server
distgitcopr_distgit_1Source caching service
distgit-httpdcopr_distgit-httpd_1DistGit HTTP server
keygen-signdcopr_keygen-signd_1GPG signing daemon
keygen-httpdcopr_keygen-httpd_1Keygen HTTP server
buildercopr_builder_1Package builder
resalloccopr_resalloc_1Resource allocation manager
resalloc-webuicopr_resalloc-webui_1Resalloc web interface
rediscopr_redis_1Message queue and cache
pulp (optional)copr_pulp_1Content repository management

​
Port Mappings

Rootless podman-compose doesn’t allow multiple containers in one pod to listen on the same port, so services use different host ports.
Host PortContainer PortServiceURL
50005000Frontendhttp://localhost:5000
50015001DistGithttp://localhost:5001
50025002Backend Resultshttp://localhost:5002
50055000Resalloc WebUIhttp://localhost:5005
500680Pulphttp://localhost:5006
50095432PostgreSQLlocalhost:5009

​
Persistent Volumes

Docker Compose creates named volumes for persistent data:
  • results - Build results and RPM repositories
  • copr-keygen - GPG keys
  • dist-git - Cached source RPMs
  • database - PostgreSQL data
  • redis - Redis data
  • resalloc - Resalloc state
  • pulp-storage - Pulp content storage
  • pulp-database - Pulp database

​
Working with the Stack

​
Viewing Logs

All services: 
docker-compose logs -f
Specific service: 
docker-compose logs -f frontend
docker-compose logs -f backend-build
Inside containers: 
# Frontend logs
docker exec -it copr_frontend_1 bash
tail -f /var/log/httpd/error_log

# Backend logs
docker exec -it copr_backend-build_1 bash
tail -f /var/log/copr-backend/backend.log

​
Accessing Containers

Get a shell in any container: 
# Frontend
docker exec -it copr_frontend_1 bash

# Backend
docker exec -it copr_backend-build_1 bash

# DistGit
docker exec -it copr_distgit_1 bash

# Builder
docker exec -it copr_builder_1 bash

​
Restarting Services

After making code changes, restart the affected service: Restart specific service: 
docker-compose restart frontend
docker-compose restart backend-build
Rebuild and restart: 
docker-compose up -d --build frontend
Restart all services: 
docker-compose restart

​
Stopping the Stack

Stop all containers (preserves data): 
docker-compose stop
Stop and remove containers (preserves volumes): 
docker-compose down
Remove everything including volumes: 
docker-compose down -v
Using docker-compose down -v will delete all data including the database, build results, and GPG keys. Only use this when you want a completely fresh start.

​
Development Workflow

​
Making Code Changes

The source code is mounted into containers at /opt/copr, so changes to your local files are immediately visible inside containers.
1

Edit code in your local directory

# Example: Edit frontend code
vim frontend/coprs_frontend/views/misc.py
2

Restart the service

docker-compose restart frontend
3

Test your changes

Visit http://localhost:5000 or use the API/CLI to test.
4

Check logs for errors

docker-compose logs -f frontend

​
Testing Builds

Create a test project and build:
1

Access the frontend

Navigate to http://localhost:5000 and log in (create an account if needed).
2

Create a new project

Click “New Project” and configure:
  • Project name: test-project
  • Chroots: Select fedora-rawhide-x86_64
3

Submit a build

Use a simple test package:
  • Method: “Upload”
  • Upload a source RPM or provide a URL
Or use CLI:
copr-cli --config ~/.config/copr-local build test-project \
  https://download.copr.fedorainfracloud.org/results/
4

Monitor build progress

Watch logs to see the build flow through components:
# Frontend creates task
docker-compose logs -f frontend

# Backend picks up task
docker-compose logs -f backend-build

# Builder executes build
docker-compose logs -f builder

​
Database Access

Connect to PostgreSQL: 
# From host
psql -h localhost -p 5009 -U copr-fe -d coprdb
Password: coprpass

# From frontend container
docker exec -it copr_frontend_1 bash
psql -U copr-fe coprdb
Common queries: 
-- List all projects
SELECT id, name, ownername FROM copr;

-- List recent builds
SELECT id, project_id, state, submitted_on FROM build
ORDER BY submitted_on DESC LIMIT 10;

-- Check build tasks
SELECT * FROM action ORDER BY id DESC LIMIT 5;

​
Redis Access

Connect to Redis: 
docker exec -it copr_redis_1 bash
redis-cli
Monitor backend logs queue: 
> KEYS *
> LRANGE copr:backend:log 0 -1

​
Troubleshooting

​
Containers won’t start

Check container status: 
docker-compose ps
View container logs: 
docker-compose logs <service-name>
Common issues:
  • Port conflicts: Another service using ports 5000-5009
    • Solution: Stop conflicting services or modify docker-compose.yaml ports
  • Insufficient resources: Docker needs enough CPU/RAM
    • Solution: Allocate more resources in Docker settings
  • Permission errors: SELinux or file permissions
    • Solution: Check volume mount permissions, try :Z flag

​
Database initialization fails

Reset database: 
docker-compose down -v
docker-compose up -d database
# Wait for database to be ready
docker-compose up -d frontend
docker exec -it copr_frontend_1 init-database.sh

​
Build tasks not processing

Check backend dispatcher: 
docker-compose logs backend-build
docker-compose logs backend-action
Verify Resalloc is running: 
docker exec -it copr_resalloc_1 bash
resalloc-maint resource-list
Check builder availability: 
docker exec -it copr_builder_1 bash
# Verify builder is accessible

​
Frontend shows errors

Check Apache logs: 
docker exec -it copr_frontend_1 bash
tail -f /var/log/httpd/error_log
Verify database connection: 
docker exec -it copr_frontend_1 bash
psql -h database -U copr-fe coprdb -c "SELECT 1;"

​
Changes not taking effect

Full rebuild: 
docker-compose down
docker-compose build --no-cache frontend
docker-compose up -d
Clear Python cache: 
find . -type d -name __pycache__ -exec rm -rf {} +
find . -type f -name "*.pyc" -delete

​
Advanced Configuration

​
Custom Configuration Files

Configuration files are in the Docker context:
  • docker/frontend/files/ - Frontend configs
  • docker/backend/files/ - Backend configs
  • docker/distgit/files/ - DistGit configs
Modify and rebuild: 
vim docker/frontend/files/copr.conf
docker-compose build frontend
docker-compose up -d frontend

​
Environment Variables

Set in docker-compose.yaml under service environment: 
frontend:
  environment:
    - COPR_DEBUG=1
    - REDIS_HOST=redis

​
Running Without Privileged Mode

The builder container requires privileged: true for mock builds. For development without actual builds: 
builder:
  privileged: false  # Disable if not testing builds

​
Performance Tips

  • Use SSD storage for Docker volumes
  • Allocate sufficient RAM (minimum 8GB recommended)
  • Disable unnecessary services in docker-compose.yaml
  • Use BuildKit for faster image builds: 
    export DOCKER_BUILDKIT=1
docker-compose build

​
Next Steps

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us