docker.recipes

Forgejo Git Forge

intermediate

Forgejo community-driven Git forge with PostgreSQL.

Overview

Forgejo is a community-driven, self-hosted Git forge that emerged as a hard fork of Gitea in 2022, maintained by Codeberg e.V. As a lightweight yet feature-rich platform, Forgejo provides Git hosting capabilities with integrated issue tracking, pull requests, wikis, and CI/CD functionality through Forgejo Actions. It emphasizes community governance, user freedom, and privacy-first design while maintaining compatibility with Git workflows and offering a familiar web interface for repository management. This deployment creates a production-ready three-tier architecture with separate services: the main Forgejo application server, a PostgreSQL 15 database for reliable data persistence, and Redis for high-performance caching and session management. The Forgejo service exposes both HTTP (port 3000) and SSH (port 2222) interfaces, with database connections and cache integration handled through internal Docker networking. Configuration is streamlined through environment variables that automatically configure database connectivity and Redis caching. This stack is ideal for development teams, open source projects, and organizations seeking a GitHub/GitLab alternative with full control over their code hosting infrastructure. The combination of Forgejo's comprehensive Git forge features with PostgreSQL's robust data integrity and Redis's sub-millisecond caching creates a responsive, scalable platform suitable for teams ranging from small startups to larger development organizations requiring reliable, self-hosted version control.

Key Features

  • Complete Git forge functionality with web-based repository management, issue tracking, and pull request workflows
  • Forgejo Actions for integrated CI/CD pipelines with GitHub Actions compatibility
  • PostgreSQL backend providing ACID compliance and advanced querying for repository metadata and user data
  • Redis-powered caching layer delivering sub-millisecond response times for web interface and API calls
  • Dual-protocol access supporting both SSH Git operations and HTTP/HTTPS web interface on configurable ports
  • Built-in wiki system, project boards, and milestone tracking for comprehensive project management
  • Organization and team management with granular permission controls and repository access policies
  • Package registry support for Docker, npm, Maven, and other popular package formats

Common Use Cases

  • 1Self-hosted Git repository management for development teams seeking alternatives to GitHub or GitLab
  • 2Open source project hosting with community collaboration features and public repository access
  • 3Enterprise source code management with private repositories and advanced user permission controls
  • 4Educational institutions providing students with hands-on Git forge experience and project collaboration
  • 5DevOps teams implementing integrated CI/CD workflows through Forgejo Actions for automated testing and deployment
  • 6Organizations requiring data sovereignty and complete control over their code hosting infrastructure
  • 7Development agencies managing multiple client projects with separate organizations and team access controls

Prerequisites

  • Docker and Docker Compose installed with support for multi-container orchestration
  • Minimum 2GB RAM recommended (Forgejo: 512MB, PostgreSQL: 1GB, Redis: 512MB) for responsive performance
  • Available ports 3000 (HTTP) and 2222 (SSH) or alternative ports configured via environment variables
  • Basic understanding of Git workflows, repository management, and SSH key configuration
  • Environment variables configured: DB_USER and DB_PASSWORD for PostgreSQL authentication
  • Sufficient disk storage for Git repositories, database, and container images (minimum 10GB recommended)

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

docker-compose.yml
1services: 
2  forgejo: 
3    image: codeberg.org/forgejo/forgejo:latest
4    container_name: forgejo
5    restart: unless-stopped
6    ports: 
7      - "${FORGEJO_HTTP_PORT:-3000}:3000"
8      - "${FORGEJO_SSH_PORT:-2222}:22"
9    environment: 
10      - USER_UID=1000
11      - USER_GID=1000
12      - FORGEJO__database__DB_TYPE=postgres
13      - FORGEJO__database__HOST=forgejo-db:5432
14      - FORGEJO__database__NAME=forgejo
15      - FORGEJO__database__USER=${DB_USER}
16      - FORGEJO__database__PASSWD=${DB_PASSWORD}
17      - FORGEJO__cache__ADAPTER=redis
18      - FORGEJO__cache__HOST=redis://forgejo-redis:6379/0
19    volumes: 
20      - forgejo_data:/data
21    depends_on: 
22      - forgejo-db
23      - forgejo-redis
24
25  forgejo-db: 
26    image: postgres:15-alpine
27    container_name: forgejo-db
28    restart: unless-stopped
29    environment: 
30      - POSTGRES_USER=${DB_USER}
31      - POSTGRES_PASSWORD=${DB_PASSWORD}
32      - POSTGRES_DB=forgejo
33    volumes: 
34      - forgejo_db_data:/var/lib/postgresql/data
35
36  forgejo-redis: 
37    image: redis:7-alpine
38    container_name: forgejo-redis
39    restart: unless-stopped
40
41volumes: 
42  forgejo_data: 
43  forgejo_db_data:

.env Template

.env
1# Forgejo
2FORGEJO_HTTP_PORT=3000
3FORGEJO_SSH_PORT=2222
4DB_USER=forgejo
5DB_PASSWORD=forgejo_password

Usage Notes

  1. 1Forgejo at http://localhost:3000
  2. 2Complete initial setup
  3. 3Community fork of Gitea
  4. 4Full Git hosting solution

Individual Services(3 services)

Copy individual services to mix and match with your existing compose files.

forgejo
forgejo:
  image: codeberg.org/forgejo/forgejo:latest
  container_name: forgejo
  restart: unless-stopped
  ports:
    - ${FORGEJO_HTTP_PORT:-3000}:3000
    - ${FORGEJO_SSH_PORT:-2222}:22
  environment:
    - USER_UID=1000
    - USER_GID=1000
    - FORGEJO__database__DB_TYPE=postgres
    - FORGEJO__database__HOST=forgejo-db:5432
    - FORGEJO__database__NAME=forgejo
    - FORGEJO__database__USER=${DB_USER}
    - FORGEJO__database__PASSWD=${DB_PASSWORD}
    - FORGEJO__cache__ADAPTER=redis
    - FORGEJO__cache__HOST=redis://forgejo-redis:6379/0
  volumes:
    - forgejo_data:/data
  depends_on:
    - forgejo-db
    - forgejo-redis
forgejo-db
forgejo-db:
  image: postgres:15-alpine
  container_name: forgejo-db
  restart: unless-stopped
  environment:
    - POSTGRES_USER=${DB_USER}
    - POSTGRES_PASSWORD=${DB_PASSWORD}
    - POSTGRES_DB=forgejo
  volumes:
    - forgejo_db_data:/var/lib/postgresql/data
forgejo-redis
forgejo-redis:
  image: redis:7-alpine
  container_name: forgejo-redis
  restart: unless-stopped

Quick Start

terminal
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  forgejo:
5    image: codeberg.org/forgejo/forgejo:latest
6    container_name: forgejo
7    restart: unless-stopped
8    ports:
9      - "${FORGEJO_HTTP_PORT:-3000}:3000"
10      - "${FORGEJO_SSH_PORT:-2222}:22"
11    environment:
12      - USER_UID=1000
13      - USER_GID=1000
14      - FORGEJO__database__DB_TYPE=postgres
15      - FORGEJO__database__HOST=forgejo-db:5432
16      - FORGEJO__database__NAME=forgejo
17      - FORGEJO__database__USER=${DB_USER}
18      - FORGEJO__database__PASSWD=${DB_PASSWORD}
19      - FORGEJO__cache__ADAPTER=redis
20      - FORGEJO__cache__HOST=redis://forgejo-redis:6379/0
21    volumes:
22      - forgejo_data:/data
23    depends_on:
24      - forgejo-db
25      - forgejo-redis
26
27  forgejo-db:
28    image: postgres:15-alpine
29    container_name: forgejo-db
30    restart: unless-stopped
31    environment:
32      - POSTGRES_USER=${DB_USER}
33      - POSTGRES_PASSWORD=${DB_PASSWORD}
34      - POSTGRES_DB=forgejo
35    volumes:
36      - forgejo_db_data:/var/lib/postgresql/data
37
38  forgejo-redis:
39    image: redis:7-alpine
40    container_name: forgejo-redis
41    restart: unless-stopped
42
43volumes:
44  forgejo_data:
45  forgejo_db_data:
46EOF
47
48# 2. Create the .env file
49cat > .env << 'EOF'
50# Forgejo
51FORGEJO_HTTP_PORT=3000
52FORGEJO_SSH_PORT=2222
53DB_USER=forgejo
54DB_PASSWORD=forgejo_password
55EOF
56
57# 3. Start the services
58docker compose up -d
59
60# 4. View logs
61docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal
1curl -fsSL https://docker.recipes/api/recipes/forgejo-stack/run | bash

Troubleshooting

  • Database connection failed errors: Verify DB_USER and DB_PASSWORD environment variables match between forgejo and forgejo-db services
  • Forgejo web interface shows 500 errors: Check that forgejo-db container is healthy and PostgreSQL database 'forgejo' was created successfully
  • SSH Git operations failing on port 2222: Ensure FORGEJO_SSH_PORT environment variable is set correctly and host firewall allows the configured port
  • Slow web interface performance: Verify forgejo-redis container is running and accessible, check Redis connection in Forgejo admin settings
  • Container startup dependency issues: Confirm forgejo service waits for both forgejo-db and forgejo-redis using depends_on configuration
  • Permission denied errors in forgejo container: Verify USER_UID and USER_GID environment variables match the Docker host user permissions for volume mounts

Community Notes

Loading...
Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

forgejopostgresqlredis

Tags

#forgejo#git#forge#self-hosted

Category

DevOps & CI/CD

Related Recipes

Ad Space