How to Deploy Gitea with Docker Compose on Ubuntu 24.04

Serdar Tekin
Serdar Tekin
Co-Founder & CTO
IntermediateUpdated Nov 17, 202618 min read~45+ minutes total
GiteaDocker ComposeUbuntu 24.04Self-Hosted GitPostgreSQLNginxDevOps
Last reviewed:
Tutorial
How to Deploy Gitea with Docker Compose on Ubuntu 24.04
rafftechnologies.com/learn
On this page

Prerequisites

  • A Raff Linux VM running Ubuntu 24.04 with at least 2 GB RAM, Docker with Compose v2, Nginx, a domain pointed to the VM, SSH access, and a non-root user with sudo privileges

Host your team's Git repositories on your own Gitea server.

Tested on 2 vCPU and 4 GB RAM: $17.99 a month

  1. 1Pick a Linux imageUbuntu, Debian and more, with your SSH key added.
  2. 2Choose a sizeFrom $4.99 a month. Resize when your app grows.
  3. 3Connect over SSHYour server is up in about 55 seconds.

Ubuntu, Debian and other Linux distributions with full root and SSH access, up and running in about 55 seconds.

Gitea is a self-hosted Git server for teams that want repository hosting, pull requests, issues, releases, packages, webhooks, and other development workflows on infrastructure they control. In this tutorial, you will deploy Gitea on a Raff Linux VM with Docker Compose, PostgreSQL, Nginx, HTTPS, and SSH clone access. The web service stays bound to localhost behind Nginx, while Git-over-SSH uses a separate host port so it does not conflict with the VM's administrative SSH service.

This guide follows Gitea's current Docker deployment model and uses the official docker.gitea.com/gitea image. At the time of this update, Gitea's official installation documentation uses the 1.27.3 release in its stable Docker examples. The official docs also recommend choosing a database early rather than relying on SQLite when you expect the instance to grow; this tutorial uses PostgreSQL for a multi-user setup. See the Gitea Docker installation documentation and database preparation guidance for the upstream reference.

You need Ubuntu 24.04, Docker with Compose v2, Nginx, a domain such as git.example.com, SSH access with sudo privileges, and DNS pointing the domain to the VM.

Step 1 — Confirm Docker, DNS, and the Ubuntu Host

Check the Ubuntu release:

Bash
cat /etc/os-release

Confirm Docker and Compose are available:

Bash
docker --version docker compose version

Check that your Gitea hostname resolves to the VM:

Bash
dig +short A git.example.com

If Docker is not installed yet, follow How to Install Docker on Ubuntu 24.04. If Nginx is missing, install it before configuring the public reverse proxy.

Verify: Ubuntu should report 24.04, docker compose version should work, and the DNS A record should return the VM's public IPv4 address.

Step 2 — Create the Gitea Project and Protect Database Secrets

Create a dedicated project directory:

Bash
mkdir -p ~/gitea cd ~/gitea

Generate a strong PostgreSQL password:

Bash
openssl rand -hex 32

Create an environment file:

Bash
nano .env

Add the generated password:

Dotenv
POSTGRES_PASSWORD=replace_with_your_generated_password

Restrict the file so other local users cannot read it:

Bash
chmod 600 .env

Do not commit this .env file to a Git repository.

Verify: Run stat -c '%a %n' .env. It should show permission mode 600 for .env.

Step 3 — Create the Docker Compose Stack

Create the Compose file:

Bash
nano compose.yaml

Add:

Yaml
services: gitea: image: docker.gitea.com/gitea:1.27.3 container_name: gitea restart: unless-stopped environment: USER_UID: "1000" USER_GID: "1000" GITEA__database__DB_TYPE: postgres GITEA__database__HOST: db:5432 GITEA__database__NAME: gitea GITEA__database__USER: gitea GITEA__database__PASSWD: ${POSTGRES_PASSWORD} GITEA__server__DOMAIN: git.example.com GITEA__server__ROOT_URL: https://git.example.com/ GITEA__server__SSH_DOMAIN: git.example.com GITEA__server__SSH_PORT: "2222" volumes: - gitea_data:/data - /etc/timezone:/etc/timezone:ro - /etc/localtime:/etc/localtime:ro ports: - "127.0.0.1:3000:3000" - "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: ${POSTGRES_PASSWORD} POSTGRES_DB: gitea volumes: - postgres_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U gitea -d gitea"] interval: 10s timeout: 5s retries: 5 volumes: gitea_data: postgres_data:

Replace every git.example.com value with your real hostname. Gitea supports PostgreSQL 12 and newer, so PostgreSQL 16 is within the supported range. The web port is published only on 127.0.0.1; Nginx will be the public HTTP entry point. Host port 2222 carries Git-over-SSH and stays separate from the VM's normal SSH port 22.

Check the rendered Compose configuration without printing secret values into a public log:

Bash
docker compose config --services

Verify: The command should list exactly gitea and db, and docker compose config -q should exit without a validation error.

Step 4 — Start Gitea and PostgreSQL

Start the stack:

Bash
docker compose up -d

Check container state:

Bash
docker compose ps

Review recent logs:

Bash
docker compose logs --tail=50 gitea docker compose logs --tail=50 db

Test the local Gitea HTTP endpoint:

Bash
curl -I http://127.0.0.1:3000

The first startup may take longer while the database initializes and Gitea prepares its data directory.

Verify: docker compose ps should show the database healthy and Gitea running, while curl -I http://127.0.0.1:3000 should return an HTTP response.

Step 5 — Configure Nginx as the Public Reverse Proxy

Create an Nginx server block:

Bash
sudo nano /etc/nginx/sites-available/git.example.com

Add:

Nginx
server { listen 80; listen [::]:80; server_name git.example.com; location / { client_max_body_size 512M; proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Connection $http_connection; proxy_set_header Upgrade $http_upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

Gitea's reverse-proxy guidance requires the public ROOT_URL to match the external URL and expects the proxy to preserve the host and forwarded protocol. The upload-size limit prevents Nginx from rejecting larger web uploads with 413 Request Entity Too Large. See the official Gitea reverse proxy documentation.

Enable the site:

Bash
sudo ln -s /etc/nginx/sites-available/git.example.com \ /etc/nginx/sites-enabled/git.example.com

Test and reload Nginx:

Bash
sudo nginx -t sudo systemctl reload nginx

Verify: sudo nginx -t should report successful syntax, and curl -I http://git.example.com should reach the Gitea site through Nginx.

Step 6 — Enable HTTPS and Open Only the Required Public Ports

If UFW is active, first confirm administrative SSH is allowed:

Bash
sudo ufw status sudo ufw allow OpenSSH

Allow HTTP/HTTPS and the Gitea SSH clone port:

Bash
sudo ufw allow 'Nginx Full' sudo ufw allow 2222/tcp

Install Certbot and request a certificate:

Bash
sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx --redirect -d git.example.com

Test renewal:

Bash
sudo certbot renew --dry-run

Do not expose container port 3000 publicly; it should remain bound to localhost.

Verify: curl -I https://git.example.com should complete over HTTPS, HTTP should redirect to HTTPS, and sudo ss -ltnp should show Gitea's web port bound to 127.0.0.1:3000 rather than 0.0.0.0:3000.

Step 7 — Complete the Gitea Installation and Create the First Administrator

Open:

Text
https://git.example.com

The Docker environment variables already provide the PostgreSQL connection values and public server URL. Confirm the database host is db:5432, database name is gitea, and the public site URL matches your HTTPS hostname.

Create the initial administrator account with a strong unique password. After the installation finishes, sign in and review the site administration settings.

For a private team instance, disable open registration after creating the accounts you need. Edit compose.yaml and add this environment variable to the gitea service:

Yaml
GITEA__service__DISABLE_REGISTRATION: "true"

Apply the change:

Bash
cd ~/gitea docker compose up -d gitea

Then open the sign-up page in a private browser session and confirm public registration is no longer available. Also require multi-factor authentication for administrator accounts and keep a separate day-to-day user account instead of using the administrator identity for normal Git work.

Verify: You should be able to sign in as the administrator over HTTPS, reach the Site Administration area without a certificate warning, and confirm that open self-registration is disabled for a private team deployment.

Step 8 — Configure and Test Git-over-SSH

In Gitea, add your public SSH key under your user settings. From your workstation, test the dedicated Git SSH port:

Bash
ssh -T -p 2222 [email protected]

The connection may report that interactive shell access is disabled; that is expected for a Git service. The important result is that the connection reaches Gitea rather than the VM's normal SSH daemon.

If port 2222 is not reachable, check:

Bash
sudo ufw status docker compose ps sudo ss -ltnp | grep 2222

Verify: ssh -T -p 2222 [email protected] should reach the Gitea SSH service associated with your account.

Step 9 — Create a Repository and Push the First Commit

Create a repository in the Gitea web interface, for example demo-repo. Then clone it from your workstation using the SSH URL shown by Gitea:

Bash
git clone ssh://[email protected]:2222/your_username/demo-repo.git cd demo-repo

Create a file and push a commit:

Bash
printf '# Gitea test repository\n' > README.md git add README.md git commit -m "Add README" git push origin main

If the repository was created with a different default branch, use the branch name shown by Gitea instead of assuming main.

Verify: Refresh the repository in the browser. The new commit and README should appear, proving that SSH authentication, repository storage, Git receive hooks, and the database are working together.

::cta Deploy Your Server Deploy a Raff Linux VM and use this tutorial to run a self-hosted Gitea Git server with Docker Compose, PostgreSQL, Nginx, and HTTPS. :::

Step 10 — Add a Consistent Backup Workflow

Gitea contains repositories, configuration, application data, and database state. Gitea's official backup guidance recommends stopping the Gitea application while taking a consistency-sensitive backup so the database and repository state cannot change independently during the operation. See Gitea Backup and Restore.

Create a backup directory:

Bash
mkdir -p ~/gitea-backups BACKUP_DIR="$HOME/gitea-backups/$(date +%F-%H%M%S)" mkdir -p "$BACKUP_DIR"

Stop the application container but keep PostgreSQL available for the database dump:

Bash
cd ~/gitea docker compose stop gitea

Dump PostgreSQL:

Bash
docker compose exec -T db \ pg_dump -U gitea -d gitea > "$BACKUP_DIR/gitea-db.sql"

Back up the Gitea data volume:

Bash
docker run --rm \ -v gitea_gitea_data:/data:ro \ -v "$BACKUP_DIR":/backup \ alpine \ tar -czf /backup/gitea-data.tar.gz -C /data .

Copy the non-secret deployment configuration:

Bash
cp compose.yaml "$BACKUP_DIR/"

Do not copy a plaintext .env containing the PostgreSQL password into an off-server backup archive. If you need the secret file for disaster recovery, encrypt it before it leaves the VM:

Bash
openssl enc -aes-256-cbc -salt -pbkdf2 \ -in .env \ -out "$BACKUP_DIR/gitea-env.enc" chmod 600 "$BACKUP_DIR/gitea-env.enc"

Use a strong encryption passphrase and store that passphrase separately from the backup. During recovery, decrypt the file only on the recovery host:

Bash
openssl enc -d -aes-256-cbc -pbkdf2 \ -in gitea-env.enc \ -out .env chmod 600 .env

Start Gitea again:

Bash
docker compose start gitea

The named volume is normally gitea_gitea_data when the Compose project directory is ~/gitea. Confirm the real name with docker volume ls before using the backup command if you changed the project name.

Store at least one backup away from the VM. Raff Data Protection can protect the server layer, and Object Storage can be used as an off-server destination for backup archives when your workflow supports S3-compatible storage.

Verify: Confirm gitea-db.sql, gitea-data.tar.gz, compose.yaml, and gitea-env.enc exist in the timestamped backup directory and are non-empty. A backup is not proven until you can restore it, so schedule a recovery rehearsal on an isolated host. For the broader workflow, see Docker Compose Backup and Restore Strategy.

Step 11 — Upgrade Gitea Safely

Before an upgrade, read the Gitea changelog and create a backup. Gitea explicitly recommends having a backup even for production patch upgrades because startup can perform database migrations and an older binary may not be able to use a migrated database.

Check the current version:

Bash
docker exec gitea gitea --version

After reviewing the target release, edit compose.yaml and change the pinned image tag to the version you intend to run. Then pull the image:

Bash
docker compose pull gitea

After your backup is complete, recreate the Gitea container:

Bash
docker compose up -d gitea

Review startup logs and the reported version:

Bash
docker compose logs --tail=100 gitea docker exec gitea gitea --version

Do not upgrade PostgreSQL to a new major version merely by changing postgres:16-alpine to another major tag. PostgreSQL major-version upgrades require a proper pg_upgrade or dump-and-restore workflow.

Verify: The Gitea container should start without repeating migration errors, the expected version should be reported, and an existing repository should still open and accept a test fetch.

Step 12 — Troubleshoot the Most Common Gitea Deployment Failures

If Gitea cannot connect to PostgreSQL, inspect both services:

Bash
docker compose logs --tail=100 gitea docker compose logs --tail=100 db

Confirm both services receive the same POSTGRES_PASSWORD through the Compose configuration and that the Gitea database host is db:5432, not localhost:5432.

If generated links or clone URLs use the wrong scheme or hostname, verify:

  • GITEA__server__ROOT_URL=https://git.example.com/
  • the Nginx Host header
  • the Nginx X-Forwarded-Proto header

If large uploads fail with HTTP 413, increase client_max_body_size deliberately based on your repository and package-upload policy rather than removing the limit entirely.

If SSH clone URLs show the wrong port, confirm GITEA__server__SSH_PORT matches the public host port in Compose.

Verify: After each fix, run docker compose ps, curl -I https://git.example.com, and ssh -T -p 2222 [email protected] to confirm the affected path is healthy.

Step 13 — Run the Final End-to-End Verification

Check containers:

Bash
docker compose ps

Check the public HTTPS endpoint:

Bash
curl -I https://git.example.com

Check the localhost-only backend:

Bash
curl -I http://127.0.0.1:3000

Check Git SSH access:

Bash
ssh -T -p 2222 [email protected]

From a cloned test repository, verify a fetch:

Bash
git fetch origin

Review recent errors:

Bash
docker compose logs --tail=100 gitea docker compose logs --tail=100 db sudo tail -n 50 /var/log/nginx/error.log

Verify: The database should be healthy, Gitea should be running, HTTPS should load through Nginx, port 3000 should remain localhost-only, SSH authentication should reach Gitea, and an existing repository should fetch successfully.

Step 14 — Clean Up or Roll Back the Test Deployment

If you are keeping Gitea, remove only temporary test repositories or local clones you no longer need.

To stop the deployment without deleting data:

Bash
cd ~/gitea docker compose down

Named volumes remain after a normal docker compose down.

To remove the Nginx site:

Bash
sudo rm -f /etc/nginx/sites-enabled/git.example.com sudo rm -f /etc/nginx/sites-available/git.example.com sudo nginx -t sudo systemctl reload nginx

If this was only a disposable test and you intentionally want to destroy Gitea and PostgreSQL data, first verify your backups. Then run:

Bash
cd ~/gitea docker compose down -v

The -v flag deletes the named volumes and therefore removes repositories, Gitea application data, and the PostgreSQL database for this Compose project.

If you issued a Let's Encrypt certificate only for this retired hostname, inspect certificates first:

Bash
sudo certbot certificates

Then delete only the relevant certificate:

Bash
sudo certbot delete --cert-name git.example.com

Verify: For a non-destructive stop, docker volume ls should still show the data volumes. After an intentional destructive cleanup with down -v, the project containers and volumes should be gone.

Conclusion

You now have a self-hosted Gitea Git server on Ubuntu 24.04 with Docker Compose, PostgreSQL, Nginx, HTTPS, and Git-over-SSH. The deployment keeps the web backend off the public interface, separates Git SSH from administrative SSH, uses a dedicated database service, and includes backup, upgrade, troubleshooting, verification, and rollback procedures.

For a small Gitea team, size the VM for repository activity, package storage, search/indexing, and concurrent users rather than assuming a fixed plan fits all deployments. Keep resource-intensive CI runners separate so builds do not compete with Gitea and PostgreSQL for CPU, memory, and disk I/O. For the broader operating model, read Self-Hosting Apps on Raff and compare Linux VM configurations through the product link in the introduction.

Deploy a Raff Ubuntu Linux VM for your self-hosted Gitea Git server with PostgreSQL, private web access behind Nginx, HTTPS, and separate backup storage.

Tested on 2 vCPU and 4 GB RAM: $17.99 a month · 14-day money-back guarantee

Deploy Your Server
Was this article helpful?
Serdar Tekin
Serdar Tekin
Co-Founder & CTO

Co-Founder & CTO at Raff, focused on cloud infrastructure, systems architecture, security, reliability, and production operations.

Host your team's Git repositories on your own Gitea server.

Tested on 2 vCPU and 4 GB RAM: $17.99 a month

Ubuntu, Debian and other Linux distributions with full root and SSH access, up and running in about 55 seconds.

14-day money-back guarantee

Frequently asked questions

What is Gitea?
Gitea is an open-source Git hosting service you can run on your own infrastructure. It provides repositories, issues, pull requests, releases, packages, webhooks, access controls, and other collaborative development features.
Is Gitea a good self-hosted Git server for a small team?
Yes. Gitea is designed to provide collaborative Git hosting without requiring a large application stack. A small team can run it on one Linux VM and scale CPU, memory, storage, or CI capacity as repository activity grows.
Should I use SQLite or PostgreSQL for Gitea?
SQLite is convenient for small or evaluation deployments, but Gitea recommends choosing another supported database when you expect the instance to grow. This tutorial uses PostgreSQL for a multi-user deployment.
Why is Gitea port 3000 bound only to localhost?
Nginx is the intended public web entry point. Binding port 3000 to 127.0.0.1 prevents direct public access to the Gitea backend while Nginx handles the external hostname and HTTPS connection.
Why does Gitea SSH use port 2222?
The VM normally uses port 22 for administrative SSH. Mapping Gitea's SSH service to host port 2222 avoids conflicting with the server's own SSH daemon while still allowing Git clone and push over SSH.
How should I back up Gitea?
Protect the PostgreSQL database, Gitea data and repositories, and the deployment configuration together. For consistency-sensitive backups, stop the Gitea application during the backup so repository and database state cannot change independently.
How much does it cost to run Gitea on Raff?
Raff VM pricing can change, so check the Raff pricing page for current Linux VM sizes and billing terms. Choose capacity based on repository activity, concurrent users, storage growth, indexing, package usage, and whether CI runners share the same server.