# Forgejo Git Forge

> Forgejo community-driven Git forge with PostgreSQL.

- Category: DevOps & CI/CD
- Difficulty: intermediate
- Components: forgejo, postgresql, redis
- Tags: forgejo, git, forge, self-hosted
- Source: https://docker.recipes/devops/forgejo-stack

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

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

## Use cases

- Self-hosted Git repository management for development teams seeking alternatives to GitHub or GitLab
- Open source project hosting with community collaboration features and public repository access
- Enterprise source code management with private repositories and advanced user permission controls
- Educational institutions providing students with hands-on Git forge experience and project collaboration
- DevOps teams implementing integrated CI/CD workflows through Forgejo Actions for automated testing and deployment
- Organizations requiring data sovereignty and complete control over their code hosting infrastructure
- Development 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)

## docker-compose.yml

```yaml
services:
  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:
    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:
    image: redis:7-alpine
    container_name: forgejo-redis
    restart: unless-stopped

volumes:
  forgejo_data:
  forgejo_db_data:
```

## .env

```bash
# Forgejo
FORGEJO_HTTP_PORT=3000
FORGEJO_SSH_PORT=2222
DB_USER=forgejo
DB_PASSWORD=forgejo_password
```

## Usage notes

- Forgejo at http://localhost:3000
- Complete initial setup
- Community fork of Gitea
- Full Git hosting solution

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

