Setting Up a Self-Hosted Git Server with Forgejo

When Setting up a home server on Mac Mini M1, one of the key decisions is choosing where to host your Git repositories. While private GitHub repositories offer a convenient cloud solution, self-hosting gives you complete control over your code and infrastructure. This guide explains how to set up Forgejo, a powerful self-hosted Git server, as an alternative to cloud-based solutions.

What is Forgejo?

Forgejo is a community-driven fork of Gitea, a lightweight self-hosted Git service. It provides all the essential features you’d expect from a modern Git platform, including repository management, issue tracking, and pull requests. The project forked from Gitea in early 2024 to ensure long-term community governance and maintain an open development model. I chose Forgejo for it’s clean dark theme, the open-source values and the popularity of Gitea.

Installation Using Docker Compose

Forgejo can be easily deployed using Docker Compose. Here’s a detailed configuration that sets up Forgejo with proper user permissions and networking:

services:
  forgejo:
    container_name: git
    image: codeberg.org/forgejo/forgejo:9
    environment:
      - USER_UID=1000
      - USER_GID=1000
    networks:
      - traefik
      - forgejo
    volumes:
      - ./config/app.ini:/data/gitea/conf/app.ini
      - data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
volumes:
  data:
networks:
  forgejo:
    external: true
  traefik:
    external: true

This configuration includes several important components:

• User permissions are set through USER_UID and USER_GID to ensure proper file ownership
• Persistent storage is configured using Docker volumes
• System time settings are shared with the container
• Two external networks are configured: one for Traefik (a reverse proxy) and another for potential CI runners

Setting Up the Network

Before starting Forgejo, you’ll need to create the external network for future CI runner integration:

docker network create forgejo

Setting up Treafik

I already have written about my Treafik setup in the article Traefik - Configuring a Secure Docker Proxy. All I had to do now was adding the following dynamic configuration:

http:
  services:
    git-service:
      loadBalancer:
        servers:
          - url: http://git:3000
 
  routers:
    git-http-router:
      rule: "Host(`git.zloutek1.com`) || Host(`git.epicartificials.com`)"
      service: git-service
      middlewares:
        - git-sablier@file
      entryPoints:
        - http
 
    git-https-router:
      rule: "Host(`git.zloutek1.com`) || Host(`git.epicartificials.com`)"
      service: git-service
      middlewares:
        - git-sablier@file
      entryPoints:
        - https
      tls:
        certResolver: cloudflare
 
  middlewares:
    git-sablier:
      plugin:
        sablier:
          sablierUrl: http://sablier:10000
          sessionDuration: 30m
          names: git
          dynamic:
            displayName: git
            refreshFrequency: 3s
            showDetails: true
            theme: ghost

Initial Configuration

After deploying the container for the first time, you’ll need to:

1. Access the Forgejo web interface (for me on https://git.zloutek1.com but you may want to expose ports in docker-compose)
2. Create an admin account
3. Configure basic server settings like:
   • Repository root path
   • SSH server domain
   • Gitea base URL
   • Other application settings through the web interface

The initial setup wizard will guide you through these essential configurations, ensuring your Git server is properly secured and ready for use.

Next Steps

With Forgejo running, you can start:

• Creating repositories
• Setting up user accounts
• Configuring SSH keys for secure access
• Planning your backup strategy for the data volume
• Setting up CI/CD pipelines using the built-in actions feature

Remember to regularly update your Forgejo instance to receive security patches and new features as they become available.

References

Forgejo - OS GIT