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
- Install Docker and Docker Compose on a maintained Linux host.
- Create the deployment directory and restrict access to it:
sudo mkdir -p /opt/forgejo/{forgejo,postgres,backups}. - Create a
compose.ymlsimilar 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
| Area | Verify |
|---|---|
| Image | The Forgejo and PostgreSQL tags are pinned, documented, and tested together. |
| Storage | The Forgejo volume contains repositories, configuration, attachments, and logs needed for recovery. |
| Permissions | The container user can write to its bind-mounted directories without making the entire host writable. |
| URL and proxy | HTTPS, forwarded headers, clone URLs, webhook callbacks, and OAuth redirects all use the public hostname. |
| SSH | The firewall, Docker mapping, advertised port, and client clone command agree. |
| Backups | Database dumps and Forgejo data are copied to a separate destination and periodically restored on a test host. |
| Actions | Runner 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.