How to Deploy Forgejo – Lightweight Git Server

Forgejo (a fork of Gitea) is a community-managed, lightweight code hosting solution focused on speed, simplicity, and community ownership. It provides Git repository hosting, code review, issue tracking, and CI/CD features in a self-hosted environment. Forgejo is efficient, easy to deploy, and runs on a wide range of hardware, from Raspberry Pis to powerful servers.

This article demonstrates how to deploy Forgejo on Ubuntu 24.04 using Docker Compose and secure it with HTTPS via a Traefik reverse proxy.

Prerequisites

Before you begin:

• Have access to an Ubuntu 24.04 server as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Configure a domain name, such as forgejo.example.com, to point to your server’s public IP address.

Set Up the Directory Structure and Environment Variables

Set up the project directory to store persistent Forgejo, MariaDB, and Let's Encrypt files.

1. Create folders to store Forgejo data, database files, and Let's Encrypt certificates.

   CONSOLE

   Copy

   $ mkdir -p ~/forgejo/{data,db,letsencrypt}

   Explain Code

   Powered by Vultr AgentBeta
   • data - Forgejo repositories, configs, SSH keys.
   • db - MariaDB database files.
   • letsencrypt - Traefik ACME certificates.

2. Navigate to the root Forgejo directory.

   CONSOLE

   Copy

   $ cd ~/forgejo

   Explain Code

   Powered by Vultr AgentBeta

3. Create a .env file to store environment variables.

   CONSOLE

   Copy

   $ nano .env

   Explain Code

   Powered by Vultr AgentBeta

4. Add the following content:

   INI

   Copy

   FORGEJO_DB_USER=forgejo
   FORGEJO_DB_PASS=STRONG_APP_PASSWORD
   MYSQL_ROOT_PASS=STRONG_MYSQL_ROOT_PASSWORD
   FORGEJO_DB_NAME=forgejodb
   FORGEJO_DOMAIN=forgejo.example.com
   LETSENCRYPT_EMAIL=admin@example.com

   Explain Code

   Powered by Vultr AgentBeta

   In the above file, replace:

   • STRONG_APP_PASSWORD with a secure password for the Forgejo DB user.
   • STRONG_MYSQL_ROOT_PASSWORD with a secure password for the MySQL root user.
   • forgejo.example.com with your domain.
   • admin@example.com with your email.

   Save and close the file.

Deploy with Docker Compose

Deploy Forgejo with Docker Compose, Traefik as reverse proxy, and MariaDB for storage.

1. Add your user account to the docker user group.

   CONSOLE

   Copy

   $ sudo usermod -aG docker $USER

   Explain Code

   Powered by Vultr AgentBeta

2. Apply new group membership.

   CONSOLE

   Copy

   $ newgrp docker

   Explain Code

   Powered by Vultr AgentBeta

3. Create and edit a Docker Compose manifest file.

   CONSOLE

   Copy

   $ nano docker-compose.yml

   Explain Code

   Powered by Vultr AgentBeta

4. Add the following contents:

   YAML

   Copy

   services:
     traefik:
       image: traefik:latest
       container_name: traefik
       restart: unless-stopped
       environment:
         DOCKER_API_VERSION: "1.44"
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
         - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
         - "--certificatesresolvers.le.acme.httpchallenge=true"
         - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
         - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
         - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock:ro
         - ./letsencrypt:/letsencrypt
   
     db:
       image: mariadb:10.11
       container_name: forgejo-db
       restart: unless-stopped
       environment:
         - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASS}
         - MYSQL_DATABASE=${FORGEJO_DB_NAME}
         - MYSQL_USER=${FORGEJO_DB_USER}
         - MYSQL_PASSWORD=${FORGEJO_DB_PASS}
       volumes:
         - ./db:/var/lib/mysql
   
     forgejo:
       image: codeberg.org/forgejo/forgejo:13
       container_name: forgejo
       restart: unless-stopped
       depends_on:
         - db
       environment:
         - USER_UID=1000
         - USER_GID=1000
         - DB_TYPE=mysql
         - DB_HOST=db:3306
         - DB_NAME=${FORGEJO_DB_NAME}
         - DB_USER=${FORGEJO_DB_USER}
         - DB_PASSWD=${FORGEJO_DB_PASS}
         - ROOT_URL=https://${FORGEJO_DOMAIN}
       volumes:
         - ./data:/data
         - /etc/timezone:/etc/timezone:ro
         - /etc/localtime:/etc/localtime:ro
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.forgejo.rule=Host(`${FORGEJO_DOMAIN}`)"
         - "traefik.http.routers.forgejo.entrypoints=websecure"
         - "traefik.http.routers.forgejo.tls=true"
         - "traefik.http.routers.forgejo.tls.certresolver=le"
         - "traefik.http.services.forgejo.loadbalancer.server.port=3000"

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

   This Docker Compose file deploys Forgejo behind Traefik, enabling secure HTTPS access using Let’s Encrypt. Each service has a specific purpose:

   • forgejo service

     • Runs the Forgejo application container (hosted on Codeberg), providing the Git hosting interface.
     • Stores repositories, SSH keys, and config in the ./data directory.
     • Connects to MariaDB using database credentials from your .env file.
     • Advertises itself to Traefik using labels so Traefik can route traffic for your domain to the Forgejo web interface over HTTPS.
     • Exposes its internal port 3000 for the web UI.

   • db service (MariaDB)

     • Stores all Forgejo metadata such as users, repositories, issues, and pull requests.
     • Uses the ./db directory for persistent data.
     • Initializes the database using values provided in the .env file.

   • traefik service

     • Listens on ports 80 and 443 and handles all incoming traffic.
     • Automatically provisions and renews SSL certificates via Let’s Encrypt using the ACME HTTP-01 challenge.
     • Reads labels from the Forgejo container to route traffic to it securely.
     • Stores certificate data in the ./letsencrypt directory.

5. Start all services in detached mode.

   CONSOLE

   Copy

   $ docker compose up -d

   Explain Code

   Powered by Vultr AgentBeta

6. Check container status.

   CONSOLE

   Copy

   $ docker compose ps

   Explain Code

   Powered by Vultr AgentBeta

   You should see forgejo, forgejo-db, and traefik listed as "Up".

   Note

   For more information on managing a Docker Compose stack, see the How To Use Docker Compose article.

Access and Configure Forgejo

1. Open your browser and visit your Forgejo domain https://forgejo.example.com.

   You should see the Initial Configuration page. The database settings are automatically populated from the environment variables.

2. Scroll down to the Administrator Account Settings section. Expand it.

3. Fill in the values to create an Administrator user.

4. Click the Install Forgejo button to finish the installation process. After a few moments, you will be redirected to the dashboard.

   

Conclusion

By following this article, you successfully deployed Forgejo on Ubuntu 24.04 using Docker Compose and secured it with Traefik. Your Git service now supports all Forgejo's built-in features. For more details, visit the Forgejo documentation.