How to Self-Host Forgejo with Docker: Git Repositories, Actions, and Backups
ForgejoGit HostingDockerCI/CDDeveloper Tools

How to Self-Host Forgejo with Docker: Git Repositories, Actions, and Backups

SSelfHosting.cloud Editorial Team
2026-11-10
6 min read

Deploy Forgejo with Docker using PostgreSQL, HTTPS, SSH, Actions runners, migrations, and tested backups.

Forgejo is a practical self-hosted Git server for private repositories, code review, issue tracking, and automation. This guide provides a reusable Docker deployment checklist covering PostgreSQL, persistent storage, SSH and HTTP access, reverse proxies, email, Forgejo Actions, migrations, and backup verification.

Overview

A reliable Forgejo installation is more than a container that starts successfully. You need a database that survives container replacement, storage that is included in backups, a stable public URL, correctly forwarded SSH traffic, and an update procedure that can be reversed if necessary. The examples below assume a Linux self-hosted server or VPS with Docker Engine and Docker Compose already installed.

Before deploying, choose a hostname such as git.example.com, decide whether SSH will use the standard port or an alternate public port, and create a dedicated directory such as /opt/forgejo. Keep application data, database data, secrets, and backup destinations clearly separated. For broader Docker planning, see the self-hosted app stack planning guide.

Use a pinned Forgejo image tag that you have tested rather than relying on an unreviewed floating tag. The exact supported tag, configuration paths, and Actions behavior should be checked against the Forgejo documentation for the release you select.

Checklist by scenario

1. Basic private Git server

  1. Install Docker and Docker Compose on a maintained Linux host.
  2. Create the deployment directory and restrict access to it: sudo mkdir -p /opt/forgejo/{forgejo,postgres,backups}.
  3. Create a compose.yml similar to this baseline, replacing the image tag and passwords with values appropriate for your installation:
services:
  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: forgejo
      POSTGRES_PASSWORD: change-this-long-password
      POSTGRES_DB: forgejo
    volumes:
      - ./postgres:/var/lib/postgresql/data

  forgejo:
    image: codeberg.org/forgejo/forgejo:REPLACE_WITH_TESTED_TAG
    restart: unless-stopped
    depends_on:
      - db
    environment:
      USER_UID: 1000
      USER_GID: 1000
      FORGEJO__database__DB_TYPE: postgres
      FORGEJO__database__HOST: db:5432
      FORGEJO__database__NAME: forgejo
      FORGEJO__database__USER: forgejo
      FORGEJO__database__PASSWD: change-this-long-password
    ports:
      - "3000:3000"
      - "2222:22"
    volumes:
      - ./forgejo:/var/lib/gitea

Run docker compose up -d, then open the web installer through the local port or your reverse proxy. Confirm that the database host, database credentials, server URL, and SSH server domain are correct before creating users. Set the public SSH port to match the port exposed by Docker and your firewall.

2. Public access through a reverse proxy

Place Forgejo behind one reverse proxy, such as Nginx Proxy Manager, Traefik, or Caddy, and publish only the web service through HTTPS. The proxy must preserve the original host and scheme and support WebSocket upgrades where required. Configure Forgejo's root URL as https://git.example.com/; otherwise clone links and webhook URLs may point to an internal address.

SSH is separate from HTTP. Forward the chosen public SSH port to the Forgejo container's port 22, or expose it through your proxy's TCP support. Test both clone forms independently: https://git.example.com/team/project.git and ssh://[email protected]:2222/team/project.git. A Cloudflare Tunnel can be useful for web access when opening inbound ports is undesirable, but verify how SSH access will be handled before choosing that design.

3. Teams, email, and automation

Create the initial administrator only after confirming that the installation URL is correct. Add ordinary users with the least privilege needed, use organizations for team repositories, and prefer deploy keys or access tokens with narrow scope for automation.

Configure SMTP if users need invitations, password resets, notifications, or repository activity mail. Treat SMTP credentials as secrets and test delivery from the Forgejo administration interface. For Forgejo Actions, install a compatible runner on a separate host or in a deliberately isolated container. Register it with a scoped token, apply labels that match your workflows, and avoid mounting the Docker socket into untrusted jobs unless you understand the resulting host-level risk.

4. Migrating repositories

  • Export or mirror the source repository, including branches and tags.
  • Decide whether issues, pull requests, releases, wiki content, and attachments also need migration.
  • Create the destination organization and repository with matching visibility.
  • Update developer remotes, deploy keys, CI secrets, webhooks, badges, and documentation links.
  • Run a fresh clone and push test before decommissioning the old service.

What to double-check

AreaVerify
ImageThe Forgejo and PostgreSQL tags are pinned, documented, and tested together.
StorageThe Forgejo volume contains repositories, configuration, attachments, and logs needed for recovery.
PermissionsThe container user can write to its bind-mounted directories without making the entire host writable.
URL and proxyHTTPS, forwarded headers, clone URLs, webhook callbacks, and OAuth redirects all use the public hostname.
SSHThe firewall, Docker mapping, advertised port, and client clone command agree.
BackupsDatabase dumps and Forgejo data are copied to a separate destination and periodically restored on a test host.
ActionsRunner labels, registration scope, secrets, and job isolation match the trust level of your repositories.

A backup is not verified until it has produced a usable restore. Stop or quiesce writes where appropriate, dump PostgreSQL with a supported tool, archive the Forgejo data volume, record the image and configuration versions, and restore into an isolated environment. Check that a repository can be cloned, an attachment can be downloaded, and an administrator can sign in.

Common mistakes

  • Using SQLite by default for a growing service: PostgreSQL is a clearer baseline when you expect multiple users, integrations, or automation.
  • Backing up only the database: repositories, uploaded files, configuration, and secrets may live outside the database.
  • Publishing the container directly: use HTTPS, firewall rules, and a reverse proxy rather than exposing an unprotected administration interface.
  • Changing the public URL after migration: this can break clone links, webhooks, runner callbacks, and email links.
  • Giving every automation job broad credentials: use separate tokens, deploy keys, protected secrets, and runner labels.
  • Updating without a rollback point: capture a tested backup and record the previous image tag before upgrading.

For SSH failures, test DNS, firewall reachability, the published port, and the client's verbose SSH output in that order. For webhook failures, inspect the Forgejo delivery log, reverse-proxy access log, TLS certificate, and target response. For runner failures, confirm registration, labels, online status, workflow syntax, and access to required services.

When to revisit

Return to this checklist before adding a new organization, exposing Forgejo publicly, registering a runner, rotating deploy keys, migrating repositories, or changing the reverse proxy. Recheck it before a planned update and after any important Forgejo, Docker, PostgreSQL, or runner security advisory. Image tags, configuration paths, Actions syntax, and proxy behavior can change between releases, so read the release documentation before copying an older deployment unchanged.

At each review, confirm that the server is patched, SSH access is protected, administrator accounts use strong authentication, backups complete, and a restore test still works. Record the selected image tags, public ports, backup location, SMTP settings, runner labels, and rollback procedure in your operations notes. That small inventory turns a one-time self-hosted Forgejo deployment into a maintainable private Git service.

For the surrounding infrastructure, compare reverse-proxy options in the Nginx Proxy Manager, Traefik, and Caddy guide, review the server hardening checklist, and use the self-hosted monitoring guide to watch availability and storage growth.

Related Topics

#Forgejo#Git Hosting#Docker#CI/CD#Developer Tools
S

SelfHosting.cloud Editorial Team

Technical Editors

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.