This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.
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/AAAArecord pointing your Git hostname (e.g.git.example.com) at the server. - Ports
80and443free for the reverse proxy, plus a dedicated port for Git SSH (we use2222on the host, mapped to22in the container). - The web port is bound to
127.0.0.1:3000so 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:
- 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). -
DISABLE_REGISTRATIONis alreadytruein the Compose file — new users must be invited from the admin panel. - Verify
ROOT_URLmatches your public HTTPS URL. If clone URLs showhttp://or the container hostname, fixGITEA__server__ROOT_URLand restart. - Confirm SSH clone works:
ssh -T -p 2222 git@git.example.comshould greet you with the Gitea SSH banner. If you front SSH with the proxy, keep port2222open in the firewall instead. - 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_URLafter a domain change. Gitea bakes the URL into clone links, webhooks, and OAuth callbacks. Changing the domain in.envwithout updatingGITEA__server__ROOT_URL(and restarting) leaves stale links everywhere. - SSH port mismatch. The container listens on
22internally; if you map it to2222on the host,GITEA__server__SSH_PORTmust be2222too, 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.
Originally published with full interactive benchmark metrics and server sizing notes at https://vpsfolio.pages.dev/self-host-gitea-docker-compose/.


