Forgejo with Kamal

A reference setup for self-hosting Forgejo using Docker and Kamal.

Deutsch

Overview

This repository demonstrates how to deploy a Forgejo instance with Kamal, including:

• Forgejo git server with PostgreSQL backend
• Kamal deployment with automatic SSL via kamal-proxy
• Docker Compose alternative for local development
• Secret management via Kamal's password manager adapter

Structure

├── Dockerfile              # Based on codeberg.org/forgejo/forgejo:14
├── config/
│   └── deploy.yml          # Kamal deployment configuration
├── docker-compose.yml      # Local development setup
└── .kamal/
    ├── hooks/              # Sample Kamal hooks
    └── secrets             # Secret adapter configuration

Prerequisites

• A Linux server (tested on ARM64/aarch64)
• Docker installed on the server
• Kamal installed locally
• A domain with DNS pointing to the server
• A password manager supported by Kamal (e.g. LastPass, 1Password, Bitwarden)

Deployment with Kamal

1. Clone this repository
2. Adjust config/deploy.yml:
   • Set your server IP under servers.web.hosts
   • Set your domain under proxy.host
   • Configure environment variables as needed
3. Set up .env with your password manager adapter and account
4. Store your secrets in the password manager
5. Deploy:

kamal setup    # First deployment (provisions server)
kamal deploy   # Subsequent deployments

Local Development

For local development without Kamal:

cp .env.example .env   # Configure database credentials
docker compose up -d

Forgejo will be available at http://localhost:3000.

Configuration

Forgejo is configured via environment variables using the FORGEJO__section__key pattern. Key settings in config/deploy.yml:

Variable	Purpose
FORGEJO__database__DB_TYPE	Database type (postgres)
FORGEJO__database__HOST	Database hostname
FORGEJO__repository__ENABLE_PUSH_CREATE_USER	Allow push-to-create repos
FORGEJO__security__GLOBAL_TWO_FACTOR_REQUIREMENT	Enforce 2FA for all users
FORGEJO__oauth2_client__ENABLE_AUTO_REGISTRATION	Auto-register OAuth2 users

See Forgejo Configuration Cheat Sheet for all options.

References

• Forgejo Documentation
• Kamal Documentation
• Forgejo Docker Images