# 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

```bash
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:

```sql
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

```bash
docker compose up -d
```

## 5) Create the first admin user

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

```bash
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:

```bash
docker compose up -d gitea-runner
```

## 7) Verify

```bash
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:

```bash
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`:

```sshconfig
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.