Deploy Gitea with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it ideal for running Gitea as a lightweight, self-hosted Git service.

This guide walks you through deploying Gitea with a PostgreSQL database backend, persistent repository storage, SSH access for Git operations, and automatic HTTPS.

Prerequisites

• A VPS with at least 1 vCPU, 2 GB RAM, and 20 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., git.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  gitea:
    image: gitea/gitea:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
      - "2222:22"
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=gitea-db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=${GITEA_DB_PASSWORD}
      - GITEA__server__DOMAIN=${GITEA_DOMAIN}
      - GITEA__server__SSH_DOMAIN=${GITEA_DOMAIN}
      - GITEA__server__ROOT_URL=https://${GITEA_DOMAIN}/
      - GITEA__server__SSH_PORT=2222
      - GITEA__server__SSH_LISTEN_PORT=22
    volumes:
      - ../files/gitea-data:/data
    depends_on:
      gitea-db:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3000/api/v1/version || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

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

Note: Port 2222 is mapped for SSH Git operations (clone, push, pull via SSH). If your VPS firewall blocks this port, open it or adjust the mapping. The GITEA__ prefix with double underscores maps to Gitea's app.ini configuration sections.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
GITEA_DOMAIN	Your Gitea domain name	git.yourdomain.com
GITEA_DB_PASSWORD	PostgreSQL database password	a-strong-random-password

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you. Gitea uses double-underscore delimited environment variables to configure its app.ini sections (e.g., GITEA__server__DOMAIN maps to [server].DOMAIN).

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/gitea-data — Git repositories, LFS objects, avatars, attachments, and Gitea configuration
• ../files/gitea-db-data — PostgreSQL database files

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths (e.g., /opt/gitea) because Dokploy may clean them during redeployment.

If you need S3 backup support, consider using named Docker volumes instead. Named volumes can be backed up with Dokploy's built-in backup features.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., git.yourdomain.com)
3. Set the container port to 3000
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to your Gitea container. SSH Git access uses port 2222 directly, bypassing the reverse proxy.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — you should see both gitea and gitea-db containers start
3. Check the Logs tab for the gitea service. Look for: Starting new Web server
4. Open https://git.yourdomain.com in your browser — you should see the Gitea setup page on first run
5. Complete the initial configuration (admin account, settings) and create a test repository
6. Test SSH access: ssh -T git@git.yourdomain.com -p 2222

Troubleshooting

Gitea shows database connection errors on startup Ensure the PostgreSQL container is healthy before Gitea starts. The depends_on with condition: service_healthy handles this, but on first boot, database initialization may take longer. Check gitea-db logs for readiness.

SSH Git clone fails with "Connection refused" Verify that port 2222 is open on your VPS firewall. The SSH port maps host port 2222 to container port 22. Ensure your Git remote URL uses the correct port: ssh://git@git.yourdomain.com:2222/user/repo.git.

Avatars and attachments not persisting Ensure the ../files/gitea-data volume is correctly mapped to /data. Gitea stores all user content, configuration, and repository data under this directory.

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about Gitea in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running Gitea.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.