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.
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.
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: true2. 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`.
Host git.vexlo.cloud
HostName git.vexlo.cloud
User git
Port 2222
IdentityFile ~/.ssh/id_ed255193. 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.
# 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]`.
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 ...`.