Forgejo Git Forge

intermediate

Community-driven Git forge with Actions support and federation.

Overview

Forgejo is a community-driven, self-hosted Git forge that emerged as a hard fork of Gitea in 2022, emphasizing democratic governance and ActivityPub federation capabilities. Unlike centralized platforms like GitHub or GitLab, Forgejo enables organizations to maintain complete control over their source code while providing modern features like CI/CD Actions, issue tracking, pull requests, and project management. This deployment combines Forgejo with PostgreSQL for robust data storage, Redis for high-performance caching and session management, and the official Forgejo runner for executing CI/CD workflows directly within your infrastructure. This four-component stack creates a production-grade Git hosting platform that can handle everything from small team projects to enterprise-scale development workflows. PostgreSQL ensures ACID-compliant data integrity for repositories, user accounts, and issue tracking, while Redis accelerates page loads and API responses through intelligent caching. The Forgejo runner connects directly to your Docker daemon, enabling containerized CI/CD pipelines that can build, test, and deploy applications without relying on external services. This configuration is ideal for organizations seeking GitHub-like functionality with complete data sovereignty, development teams requiring custom CI/CD workflows, and forward-thinking projects interested in federated development through ActivityPub. The combination provides enterprise-level reliability while maintaining the flexibility to customize every aspect of your development workflow, from repository management to automated deployment pipelines.

Key Features

ActivityPub federation enabling cross-instance collaboration and repository discovery
Forgejo Actions with containerized CI/CD pipelines using Docker-in-Docker execution
PostgreSQL backend with JSONB support for flexible metadata and advanced query capabilities
Redis-powered session management and repository caching for sub-second page loads
Git over SSH on port 2222 with full protocol support including Git LFS
Multi-architecture container support with ARM64 and AMD64 compatibility
Advanced PostgreSQL features like full-text search for code and issues
Runner auto-scaling capabilities through Docker socket integration

Common Use Cases

1Enterprise source code hosting with air-gapped or on-premises requirements
2Open source projects seeking federated collaboration across multiple Forgejo instances
3Development teams building custom CI/CD pipelines with Docker-based workflows
4Organizations migrating from Gitea while maintaining full compatibility
5Educational institutions requiring self-hosted Git services with user management
6Startups needing GitHub-like features without vendor lock-in or usage limits
7DevOps teams implementing GitOps workflows with integrated Actions runners

Prerequisites

Docker Engine 20.10+ with Docker Compose V2 support
Minimum 2GB RAM for PostgreSQL database operations and Git repository caching
Available ports 3000 (web UI), 2222 (SSH), with firewall rules configured appropriately
Docker socket access for Forgejo runner container execution permissions
Basic understanding of Git workflows and CI/CD pipeline concepts
SSL certificate and reverse proxy setup for production HTTPS deployment

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

docker-compose.yml

1services: 
2  postgres: 
3    image: postgres:15-alpine
4    environment: 
5      - POSTGRES_USER=forgejo
6      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
7      - POSTGRES_DB=forgejo
8    volumes: 
9      - postgres_data:/var/lib/postgresql/data
10    networks: 
11      - forgejo_net
12
13  redis: 
14    image: redis:7-alpine
15    volumes: 
16      - redis_data:/data
17    networks: 
18      - forgejo_net
19
20  forgejo: 
21    image: codeberg.org/forgejo/forgejo:latest
22    ports: 
23      - "3000:3000"
24      - "2222:22"
25    environment: 
26      - USER_UID=1000
27      - USER_GID=1000
28      - FORGEJO__database__DB_TYPE=postgres
29      - FORGEJO__database__HOST=postgres:5432
30      - FORGEJO__database__NAME=forgejo
31      - FORGEJO__database__USER=forgejo
32      - FORGEJO__database__PASSWD=${POSTGRES_PASSWORD}
33      - FORGEJO__cache__ADAPTER=redis
34      - FORGEJO__cache__HOST=redis://redis:6379/0
35      - FORGEJO__actions__ENABLED=true
36    volumes: 
37      - forgejo_data:/data
38    depends_on: 
39      - postgres
40      - redis
41    networks: 
42      - forgejo_net
43
44  forgejo-runner: 
45    image: code.forgejo.org/forgejo/runner:latest
46    environment: 
47      - FORGEJO_INSTANCE_URL=http://forgejo:3000
48      - FORGEJO_RUNNER_REGISTRATION_TOKEN=${RUNNER_TOKEN}
49    volumes: 
50      - /var/run/docker.sock:/var/run/docker.sock
51      - runner_data:/data
52    depends_on: 
53      - forgejo
54    networks: 
55      - forgejo_net
56
57volumes: 
58  postgres_data: 
59  redis_data: 
60  forgejo_data: 
61  runner_data: 
62
63networks: 
64  forgejo_net:

.env Template

.env

1# Forgejo
2POSTGRES_PASSWORD=secure_postgres_password
3RUNNER_TOKEN=your_runner_registration_token
4
5# Forgejo at http://localhost:3000
6# Community-driven Gitea fork

Usage Notes

1Forgejo at http://localhost:3000
2Community-driven Gitea fork
3ActivityPub federation support
4Fully compatible with Gitea
5Get runner token from admin panel

Individual Services(4 services)

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

postgres

postgres:
  image: postgres:15-alpine
  environment:
    - POSTGRES_USER=forgejo
    - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    - POSTGRES_DB=forgejo
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - forgejo_net

redis

redis:
  image: redis:7-alpine
  volumes:
    - redis_data:/data
  networks:
    - forgejo_net

forgejo

forgejo:
  image: codeberg.org/forgejo/forgejo:latest
  ports:
    - "3000:3000"
    - "2222:22"
  environment:
    - USER_UID=1000
    - USER_GID=1000
    - FORGEJO__database__DB_TYPE=postgres
    - FORGEJO__database__HOST=postgres:5432
    - FORGEJO__database__NAME=forgejo
    - FORGEJO__database__USER=forgejo
    - FORGEJO__database__PASSWD=${POSTGRES_PASSWORD}
    - FORGEJO__cache__ADAPTER=redis
    - FORGEJO__cache__HOST=redis://redis:6379/0
    - FORGEJO__actions__ENABLED=true
  volumes:
    - forgejo_data:/data
  depends_on:
    - postgres
    - redis
  networks:
    - forgejo_net

forgejo-runner

forgejo-runner:
  image: code.forgejo.org/forgejo/runner:latest
  environment:
    - FORGEJO_INSTANCE_URL=http://forgejo:3000
    - FORGEJO_RUNNER_REGISTRATION_TOKEN=${RUNNER_TOKEN}
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
    - runner_data:/data
  depends_on:
    - forgejo
  networks:
    - forgejo_net

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  postgres:
5    image: postgres:15-alpine
6    environment:
7      - POSTGRES_USER=forgejo
8      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
9      - POSTGRES_DB=forgejo
10    volumes:
11      - postgres_data:/var/lib/postgresql/data
12    networks:
13      - forgejo_net
14
15  redis:
16    image: redis:7-alpine
17    volumes:
18      - redis_data:/data
19    networks:
20      - forgejo_net
21
22  forgejo:
23    image: codeberg.org/forgejo/forgejo:latest
24    ports:
25      - "3000:3000"
26      - "2222:22"
27    environment:
28      - USER_UID=1000
29      - USER_GID=1000
30      - FORGEJO__database__DB_TYPE=postgres
31      - FORGEJO__database__HOST=postgres:5432
32      - FORGEJO__database__NAME=forgejo
33      - FORGEJO__database__USER=forgejo
34      - FORGEJO__database__PASSWD=${POSTGRES_PASSWORD}
35      - FORGEJO__cache__ADAPTER=redis
36      - FORGEJO__cache__HOST=redis://redis:6379/0
37      - FORGEJO__actions__ENABLED=true
38    volumes:
39      - forgejo_data:/data
40    depends_on:
41      - postgres
42      - redis
43    networks:
44      - forgejo_net
45
46  forgejo-runner:
47    image: code.forgejo.org/forgejo/runner:latest
48    environment:
49      - FORGEJO_INSTANCE_URL=http://forgejo:3000
50      - FORGEJO_RUNNER_REGISTRATION_TOKEN=${RUNNER_TOKEN}
51    volumes:
52      - /var/run/docker.sock:/var/run/docker.sock
53      - runner_data:/data
54    depends_on:
55      - forgejo
56    networks:
57      - forgejo_net
58
59volumes:
60  postgres_data:
61  redis_data:
62  forgejo_data:
63  runner_data:
64
65networks:
66  forgejo_net:
67EOF
68
69# 2. Create the .env file
70cat > .env << 'EOF'
71# Forgejo
72POSTGRES_PASSWORD=secure_postgres_password
73RUNNER_TOKEN=your_runner_registration_token
74
75# Forgejo at http://localhost:3000
76# Community-driven Gitea fork
77EOF
78
79# 3. Start the services
80docker compose up -d
81
82# 4. View logs
83docker 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-complete/run | bash

Troubleshooting

Forgejo runner shows 'connection refused' errors: Verify FORGEJO_INSTANCE_URL uses internal Docker network name 'forgejo' not 'localhost'
PostgreSQL connection failures on startup: Check POSTGRES_PASSWORD environment variable matches between postgres and forgejo services
Actions fail with permission denied: Ensure forgejo-runner container has proper Docker socket permissions with correct user mapping
Redis connection timeouts during high load: Increase Redis memory limits and configure maxmemory-policy to allkeys-lru
SSH clone operations fail on port 2222: Verify host firewall allows inbound connections and Docker port mapping is active
Database migration errors after updates: Stop all services, backup postgres_data volume, then restart with latest Forgejo image

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

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

Components

forgejoforgejo-runnerpostgresqlredis

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download