Gitea Docker Setup (Traefik + Existing Postgres + Actions Runner)

This project deploys:

• gitea behind your existing Traefik reverse proxy
• gitea-runner for CI/CD (Gitea Actions)
• connection to your already running Postgres in the shared Docker network

What this is built for

• Existing stack already provides:
  • Traefik with Let's Encrypt
  • Postgres service named postgres
  • shared Docker network via ${SHARED_NETWORK_NAME}
• Gitea should be reachable at subdomain git (for example git.example.com)

Files

• docker-compose.yml: Gitea + Actions runner stack
• .env.example: required environment variables

1) Prepare environment

cp .env.example .env

Edit .env and set:

• SHARED_NETWORK_NAME to the same network name used by your main stack
• GITEA_DOMAIN to your git subdomain (for example git.example.com)
• GITEA_SSH_PORT to the host SSH port for Git over SSH (default in this setup: 2222)
• Postgres credentials for a dedicated Gitea database/user

2) Create Postgres DB/User (on your existing DB)

If not already present, create dedicated credentials for Gitea in your existing Postgres:

CREATE USER gitea WITH PASSWORD 'change-me';
CREATE DATABASE gitea OWNER gitea;
GRANT ALL PRIVILEGES ON DATABASE gitea TO gitea;

Use your own secure password and update .env.

3) DNS

Create an A/AAAA record for:

• git.<your-domain> -> your server IP

4) Start services

docker compose up -d

5) Create the first admin user

Run the CLI inside the container as the non-root git user:

docker exec -u git -it gitea gitea admin user create \
  --username youradmin \
  --password 'StrongPasswordHere' \
  --email you@example.com \
  --admin \
  --must-change-password=false

Public sign-up is disabled by default in this stack (GITEA__service__DISABLE_REGISTRATION=true).

6) Runner registration token

1. Open https://<your-gitea-domain>
2. Login as admin
3. Go to:
   • Site level: Administration -> Actions -> Runners
   • or Org/Repo level: Settings -> Actions -> Runners
4. Generate registration token
5. Put token into .env as GITEA_RUNNER_REGISTRATION_TOKEN
6. Restart runner:

docker compose up -d gitea-runner

7) Verify

docker compose ps
docker compose logs -f gitea
docker compose logs -f gitea-runner

8) Git over SSH

This stack exposes Gitea SSH as ${GITEA_SSH_PORT} on the host (default 2222).

Clone example:

git clone ssh://git@<your-gitea-domain>:2222/<owner>/<repo>.git

Important:

• Include <owner>/<repo>.git (for example alice/my-api.git).
• git@<domain>/<repo>.git is not valid for Gitea SSH clone URLs.
• If you use SCP-style syntax, include the owner and rely on ~/.ssh/config for port:
  • git@<your-gitea-domain>:<owner>/<repo>.git

If you want to keep using git@<your-gitea-domain>:<owner>/<repo>.git without specifying a port in each command, add this to your local ~/.ssh/config:

Host <your-gitea-domain>
  HostName <your-gitea-domain>
  User git
  Port 2222
  IdentitiesOnly yes

Notes

• This setup uses HTTPS via Traefik labels and Let's Encrypt from your existing stack.
• Git over SSH is enabled by direct Docker port mapping (${GITEA_SSH_PORT}:22) to avoid changing your Traefik base config.
• Port 22 on the host is often already used by the server's SSH daemon. Keep GITEA_SSH_PORT=2222 unless you intentionally move host SSH to another port.
• Gitea Actions is enabled (GITEA__actions__ENABLED=true).
• If you ever enabled Gitea's internal SSH server before, keep GITEA__server__START_SSH_SERVER=false to avoid restart loops from port conflicts.