Deploy on Vexlo Cloud in 60s (₹149/mo UPI) — India's First & Only Developer PaaS. Instant INR UPI & 17 global currencies ($5/mo).
Deploy Now
Bucket 3: Self-Hosted Open-Source Docker Templates6 min readVerified

Self-Hosting Gitea Behind Traefik v3 with PostgreSQL and Git-Over-SSH Passthrough

Deploy Gitea with Docker Compose, PostgreSQL 16, and Traefik v3 TLS. Configure Git-over-SSH on port 2222 (SSH_PORT vs SSH_LISTEN_PORT) or host SSH shim passthrough without breaking Ubuntu OpenSSH on port 22.

TL;DR — Immediate Production Fix

When self-hosting Gitea (`gitea/gitea:1.22`) in Docker Compose on a Linux VPS, host port `22` is already occupied by the Ubuntu OpenSSH daemon (`sshd`). Trying to map `"22:22"` in `docker-compose.yml` fails immediately with `address already in use`. The cleanest production architecture is mapping host port `2222` to container port `22` (`"2222:22"`) while setting TWO distinct environment variables in Gitea: `GITEA__server__SSH_PORT=2222` (the public port displayed in `ssh://[email protected]:2222/org/repo.git` clone URLs) AND `GITEA__server__SSH_LISTEN_PORT=22` (the internal container port where Gitea's SSH server actually binds).

Verified Root Causes in Production Environments

  • Host Port 22 Conflict With Ubuntu OpenSSH (`sshd`): The host Linux server requires port 22 for system administration, preventing Docker from binding `0.0.0.0:22` unless host `sshd` is moved or SSH is shimmed.
  • Setting SSH_PORT=2222 Without Keeping SSH_LISTEN_PORT=22: If you set `GITEA__server__SSH_PORT=2222` without explicitly setting `GITEA__server__SSH_LISTEN_PORT=22`, Gitea changes its internal listener to `2222`, breaking a `2222:22` port mapping.
  • Attempting to Route Raw SSH Over a Traefik HTTP Router: SSH is a raw TCP protocol, not HTTP/TLS with SNI. Routing SSH through Traefik requires a dedicated `tcp` entrypoint (`traefik.tcp.routers`) or direct Docker port publishing.

1. Production Gitea + PostgreSQL 16 Docker Compose With Port 2222 Git-Over-SSH

Gitea consumes less than 120 MB of RAM (compared to 4 GB+ for self-hosted GitLab CE), making it ideal for hosting private repositories and CI/CD pipelines (Gitea Actions) on Vexlo Cloud or a compact Ubuntu VPS.

In the `docker-compose.yml` below, Traefik handles HTTPS web traffic (`git.vexlo.cloud` -> internal port `3000`), while Docker publishes TCP port `2222` on the host directly to internal port `22` inside the Gitea container. Setting both `GITEA__server__SSH_PORT=2222` and `GITEA__server__SSH_LISTEN_PORT=22` ensures the Gitea UI renders accurate `ssh://[email protected]:2222/...` clone URLs while listening on port `22` inside the container.

docker-compose.yml
yaml
services:
  gitea-db:
    image: postgres:16-alpine
    container_name: vexlo-gitea-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: gitea
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: gitea
    volumes:
      - gitea_pg_data:/var/lib/postgresql/data
    networks:
      - internal
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gitea -d gitea"]
      interval: 10s
      timeout: 5s
      retries: 5

  gitea:
    image: gitea/gitea:1.22
    container_name: vexlo-gitea
    restart: unless-stopped
    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: ${POSTGRES_PASSWORD}
      GITEA__server__DOMAIN: git.vexlo.cloud
      GITEA__server__SSH_DOMAIN: git.vexlo.cloud
      GITEA__server__ROOT_URL: https://git.vexlo.cloud/
      GITEA__server__HTTP_PORT: 3000
      # External port shown in UI clone URLs (2222) vs Internal container listen port (22)
      GITEA__server__SSH_PORT: 2222
      GITEA__server__SSH_LISTEN_PORT: 22
      GITEA__server__DISABLE_SSH: "false"
    ports:
      # Publish host TCP 2222 -> container TCP 22 for Git-over-SSH
      - "2222:22"
    volumes:
      - gitea_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    networks:
      - internal
      - proxy
    depends_on:
      gitea-db:
        condition: service_healthy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.gitea.rule=Host(`git.vexlo.cloud`)"
      - "traefik.http.routers.gitea.entrypoints=websecure"
      - "traefik.http.routers.gitea.tls.certresolver=letsencrypt"
      - "traefik.http.services.gitea.loadbalancer.server.port=3000"

volumes:
  gitea_pg_data:
  gitea_data:

networks:
  internal:
    driver: bridge
  proxy:
    external: true

2. Seamless Local ~/.ssh/config Alias So You Don't Have to Type :2222

By adding a 4-line entry to your local workstation's `~/.ssh/config` file (`Port 2222`), you can use clean `git clone [email protected]:org/repo.git` syntax without typing `ssh://` or `:2222`.

~/.ssh/config
ini
Host git.vexlo.cloud
  HostName git.vexlo.cloud
  User git
  Port 2222
  IdentityFile ~/.ssh/id_ed25519

3. Alternative: Routing SSH Through a Traefik TCP Entrypoint (`entrypoints.gitssh`)

If your infrastructure routes all inbound traffic through a centralized Traefik container, define `--entrypoints.gitssh.address=:2222` in your static Traefik configuration and add `traefik.tcp.routers.gitea-ssh.rule=HostSNI(`*`)` labels to Gitea. Because standard SSH does not support TLS SNI headers (`HostSNI`), only one non-TLS TCP service can share port 2222 via `HostSNI(`*`)`.

To enable built-in GitHub Actions-compatible CI/CD pipelines inside your self-hosted Gitea instance, Gitea 1.19+ ships with native Gitea Actions enabled by default. Simply navigate to Site Administration -> Actions -> Runners, copy the registration token, and spin up a gitea/act_runner:latest container on your Docker host so every git push over port 2222 triggers automated Docker builds and deployments.

traefik-tcp-ssh-labels.yml
yaml
    # Optional: If routing port 2222 through Traefik TCP entrypoint instead of direct host port
    labels:
      - "traefik.tcp.routers.gitea-ssh.rule=HostSNI(`*`)"
      - "traefik.tcp.routers.gitea-ssh.entrypoints=gitssh"
      - "traefik.tcp.routers.gitea-ssh.service=gitea-ssh-svc"
      - "traefik.tcp.services.gitea-ssh-svc.loadbalancer.server.port=22"

Pre-Deployment Verification Checklist

  • Set both `GITEA__server__SSH_PORT=2222` (external) and `GITEA__server__SSH_LISTEN_PORT=22` (internal).
  • Map `ports: - "2222:22"` in `docker-compose.yml` and allow TCP port `2222` in `ufw allow 2222/tcp`.
  • Point Traefik's HTTP service (`loadbalancer.server.port=3000`) explicitly to port `3000` so Traefik does not accidentally pick port `22`.
  • Test SSH connectivity via `ssh -T -p 2222 [email protected]`.
India's First & Only Developer PaaS

Deploy on Vexlo Cloud in 60s (₹149/mo UPI)

Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.

Frequently Asked Questions

Why does git clone over SSH fail with Connection Refused on port 2222 in Gitea?

If you set `GITEA__server__SSH_PORT=2222` without also setting `GITEA__server__SSH_LISTEN_PORT=22`, Gitea listens on internal port `2222` while your Docker port mapping (`2222:22`) forwards traffic to internal port `22`. Either set `SSH_LISTEN_PORT=22` or map `2222:2222`.

Can I use HostSNI(`git.example.com`) on a Traefik TCP router for Gitea SSH?

No. The SSH protocol does not use TLS or send TLS Server Name Indication (SNI) headers during handshake. Any Traefik TCP router handling raw SSH must use `HostSNI(\`*\`)` on a dedicated TCP entrypoint port.

How do I test if my Gitea SSH key is working properly on port 2222?

Run `ssh -T -p 2222 [email protected]`. Gitea's SSH server will respond with: `Hi there, <username>! You've successfully authenticated with the key named ...`.

Primary Upstream References & Specifications

Keep Debugging

Related Guides

Browse all 30 guides →