# Forgejo Git Forge

> Community-driven Git forge with Actions support and federation.

- Category: DevOps & CI/CD
- Difficulty: intermediate
- Components: forgejo, forgejo-runner, postgresql, redis
- Tags: forgejo, git, forge, federation, community
- Source: https://docker.recipes/devops/forgejo-complete

## 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.

## 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

## Use cases

- Enterprise source code hosting with air-gapped or on-premises requirements
- Open source projects seeking federated collaboration across multiple Forgejo instances
- Development teams building custom CI/CD pipelines with Docker-based workflows
- Organizations migrating from Gitea while maintaining full compatibility
- Educational institutions requiring self-hosted Git services with user management
- Startups needing GitHub-like features without vendor lock-in or usage limits
- DevOps 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

## docker-compose.yml

```yaml
services:
  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:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - forgejo_net

  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:
    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

volumes:
  postgres_data:
  redis_data:
  forgejo_data:
  runner_data:

networks:
  forgejo_net:
```

## .env

```bash
# Forgejo
POSTGRES_PASSWORD=secure_postgres_password
RUNNER_TOKEN=your_runner_registration_token

# Forgejo at http://localhost:3000
# Community-driven Gitea fork
```

## Usage notes

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

## 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

