VPSFolio

2026-11-18 · gitea · docker · git · self-hosting

Self-Host Gitea with Docker Compose: Git Service Setup

Run Gitea with Docker Compose and PostgreSQL: persistent volumes, SSH clone port, reverse proxy with HTTPS, backups, and safe first-run admin setup.

Bench run · 2026-11-18 Verified
go-gitea/gitea
Total RAM
197.9 MB
Startup
193.9 s
Port
2222, 3000
HTTP
200
Per container server 173.7 MB · db 24.2 MB
gitea/gitea:1.22 · 2 containers · go-gitea/gitea

What Gitea does and what it needs

Gitea is a single-binary Git service written in Go. It bundles repository hosting, pull requests, issue tracking, wikis, a package registry, and a GitHub Actions-compatible CI runner into one process. The official image is gitea/gitea, and the container exposes two ports: 3000 for HTTP and 22 for SSH-based Git operations.

Gitea stores almost everything in two places: the SQL database (SQLite by default, or PostgreSQL/MySQL) and the GITEA_WORK_DIR directory, which holds repositories, attachments, LFS objects, and the app.ini config. For a production deployment you want PostgreSQL and a named volume for /data so a container restart never loses repos.

The upstream project does not publish a minimum memory figure. Practical sizing depends on workload: an idle instance with a handful of repos runs comfortably in a few hundred MB, while heavy Actions jobs, large LFS uploads, and many concurrent web sessions push memory and CPU up. Size for your expected CI concurrency, not for the idle baseline.

Prerequisites, ports, and volume constraints

  • A Linux VPS with Docker Engine 24+ and the Compose plugin (docker compose version).
  • A DNS A/AAAA record pointing your Git hostname (e.g. git.example.com) at the server.
  • Ports 80 and 443 free for the reverse proxy, plus a dedicated port for Git SSH (we use 2222 on the host, mapped to 22 in the container).
  • The web port is bound to 127.0.0.1:3000 so it is only reachable through the proxy.

Two volumes matter: gitea_data (mounted at /data) holds repositories, LFS, attachments, and app.ini; gitea_db (mounted at /var/lib/postgresql/data) holds the database. Back both up together — restoring one without the other leaves you with broken repo metadata.

Production Docker Compose setup

Create the project directory and the .env file first. Every secret is generated, never hardcoded.

mkdir -p ~/gitea && cd ~/gitea

cat <<'EOF' > .env
GITEA_DOMAIN=git.example.com
GITEA_SSH_PORT=2222
GITEA_HTTP_PORT=3000
DB_PASSWORD=REPLACE_DB_PASSWORD
GITEA_SECRET_KEY=REPLACE_SECRET_KEY
GITEA_INTERNAL_TOKEN=REPLACE_INTERNAL_TOKEN
GITEA_JWT_SECRET=REPLACE_JWT_SECRET
TZ=UTC
EOF

# Fill the placeholders with strong random values
sed -i "s|REPLACE_DB_PASSWORD|$(openssl rand -hex 24)|" .env
sed -i "s|REPLACE_SECRET_KEY|$(openssl rand -hex 32)|" .env
sed -i "s|REPLACE_INTERNAL_TOKEN|$(openssl rand -hex 32)|" .env
sed -i "s|REPLACE_JWT_SECRET|$(openssl rand -hex 32)|" .env
chmod 600 .env

Now write the Compose file. It runs Gitea plus PostgreSQL, wires the secrets from .env, and keeps the web port on localhost.

cat <<'EOF' > compose.yml
services:
  server:
    image: gitea/gitea:1.22
    container_name: gitea
    restart: unless-stopped
    environment:
      USER_UID: "1000"
      USER_GID: "1000"
      TZ: ${TZ:-UTC}
      GITEA__database__DB_TYPE: postgres
      GITEA__database__HOST: db:5432
      GITEA__database__NAME: gitea
      GITEA__database__USER: gitea
      GITEA__database__PASSWD: ${DB_PASSWORD}
      GITEA__server__DOMAIN: ${GITEA_DOMAIN}
      GITEA__server__ROOT_URL: https://${GITEA_DOMAIN}/
      GITEA__server__SSH_DOMAIN: ${GITEA_DOMAIN}
      GITEA__server__SSH_PORT: ${GITEA_SSH_PORT:-2222}
      GITEA__server__HTTP_PORT: ${GITEA_HTTP_PORT:-3000}
      GITEA__server__PROTOCOL: http
      GITEA__security__SECRET_KEY: ${GITEA_SECRET_KEY}
      GITEA__security__INTERNAL_TOKEN: ${GITEA_INTERNAL_TOKEN}
      GITEA__oauth2__JWT_SECRET: ${GITEA_JWT_SECRET}
      GITEA__service__DISABLE_REGISTRATION: "true"
    volumes:
      - gitea_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:${GITEA_HTTP_PORT:-3000}:3000"
      - "${GITEA_SSH_PORT:-2222}:22"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    container_name: gitea-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: gitea
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: gitea
      TZ: ${TZ:-UTC}
    volumes:
      - gitea_db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gitea -d gitea"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  gitea_data:
  gitea_db:
EOF

docker compose up -d
docker compose logs -f server

Wait for Listen: http://0.0.0.0:3000 in the logs, then confirm the container is healthy with docker compose ps. The first account you register becomes the administrator — do that before exposing the hostname publicly.

Reverse proxy, HTTPS, and first-run hardening

Gitea needs the proxy to forward the original scheme so generated clone URLs use https://. With Caddy, a minimal site block is enough:

git.example.com {
    encode gzip
    reverse_proxy 127.0.0.1:3000
}

If you use Nginx instead, set client_max_body_size 512m; (Gitea accepts large pushes and LFS uploads), forward X-Forwarded-Proto and X-Forwarded-For, and pass Host $host. Gitea does not require WebSocket upgrade headers for normal use, but the Actions log viewer and notification streams benefit from proxy_set_header Upgrade $http_upgrade; and proxy_set_header Connection "upgrade";.

First-run hardening checklist:

  1. Register the admin account immediately after the container is up, while the site is still only reachable on 127.0.0.1:3000 (use an SSH tunnel: ssh -L 3000:127.0.0.1:3000 user@server).
  2. DISABLE_REGISTRATION is already true in the Compose file — new users must be invited from the admin panel.
  3. Verify ROOT_URL matches your public HTTPS URL. If clone URLs show http:// or the container hostname, fix GITEA__server__ROOT_URL and restart.
  4. Confirm SSH clone works: ssh -T -p 2222 git@git.example.com should greet you with the Gitea SSH banner. If you front SSH with the proxy, keep port 2222 open in the firewall instead.
  5. Enable 2FA for the admin account under Settings → Security.

Updating, backups, and common pitfalls

Update by bumping the image tag in compose.yml (or pinning a new digest), then:

docker compose pull
docker compose up -d
docker compose logs -f server

Gitea runs its own database migrations on startup; watch the logs for migration errors before declaring the update done. Never skip major versions — step through intermediate releases.

Back up both volumes together. The simplest reliable method is a database dump plus a tar of the data volume:

docker compose exec -T db pg_dump -U gitea gitea > gitea-db-$(date +%F).sql
docker run --rm -v gitea_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/gitea-data-$(date +%F).tar.gz -C /data .

Store both files off-server. Restoring means stopping the stack, extracting the tar into gitea_data, and piping the SQL dump back into a fresh database.

Two pitfalls worth knowing:

  • Wrong ROOT_URL after a domain change. Gitea bakes the URL into clone links, webhooks, and OAuth callbacks. Changing the domain in .env without updating GITEA__server__ROOT_URL (and restarting) leaves stale links everywhere.
  • SSH port mismatch. The container listens on 22 internally; if you map it to 2222 on the host, GITEA__server__SSH_PORT must be 2222 too, or the clone URLs Gitea prints will point at a closed port.

Measured in our sandbox run: total memory 197.9 MB (sum of per-container peaks over a 30s idle window after startup) across 2 containers; largest container 173.7 MB; published port(s) 2222, 3000; HTTP probe returned 200. The run took 193.9s including the image download. Required secret(s) DB_PASSWORD, GITEA_DOMAIN, GITEA_INTERNAL_TOKEN, GITEA_JWT_SECRET, GITEA_SECRET_KEY were generated for the test run, as the tutorial instructs. Container breakdown: server 173.7 MB, db 24.2 MB.


Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.