Update README

software-development/gitea/README.md

@@ -1,63 +1,67 @@
 # Gitea
-Self hosted Git  
-Followed instructions on Gitea page: https://docs.gitea.com/next/installation/install-with-docker
 
-### Steps
-1. Create a new user to own the gitea folder.
+Self-hosted git server backed by PostgreSQL, proxied through Traefik.
+
+## Services
+
+| Service | Image | Purpose |
+|---------|-------|---------|
+| `server` | `gitea/gitea:latest` | Gitea web/git server |
+| `database` | `postgres:14` | PostgreSQL database |
+
+Data is persisted to `/pwspool/software/gitea/` on the host.
+
+## Setup
+
+### 1. Configure environment
+
+Copy the example env files and fill in values:
+
 ```
-sudo groupadd gitea && sudo useradd giteauser && sudo usermod -a -G gitea giteauser && chown -r gitea:giteauser .
-```
-2. Configure Environment
-Create `gitea.env` and `database.env` from the examples, replacing with relevant env values.
-
-See [Gitea Documentation](https://docs.gitea.com/administration/config-cheat-sheet) for examples/types.
-
-2. Run via Docker Compose
+cp gitea.env.example gitea.env
+cp database.env.example database.env
 ```
 
-docker-compose up -d
+- `gitea.env` — Gitea app config (domain, SSH settings, DB credentials, etc.)
+- `database.env` — PostgreSQL credentials
+
+See the [Gitea config cheat sheet](https://docs.gitea.com/administration/config-cheat-sheet) for all available options.
+
+### 2. Start the stack
+
 ```
-3. Test postgresql
-```
-docker exec -it gitea_db bash
-psql -h 127.0.0.1 -p 5432 -U olomana_readwrite -d gitea
+docker compose up -d
 ```
 
-4. Go to xxx.xxx.xx.xxx:3000 and fill out initial config. Everything should match up to default value.
-Some things that were weird:
-- could not use any port that wasnt default postgresql (5432)
-- had to make sure to specify database container by the right name. Removed custom name and used just "database".
-Note that the first admin is set via env vars, by generating the password hash. Alternatively create your users by setting the env var that controls signups.
+### 3. Complete initial setup
 
-5. Provision new users
-You can do that from the "Site Administration" view from the first admin user.
+Navigate to `https://git.whitney.rip` and complete the web installer. Values should match what's in `gitea.env`. A few known quirks:
+- PostgreSQL must use the default port (5432); other ports may fail.
+- Use `database` as the database hostname (matches the service name in `docker-compose.yml`).
+- The first admin account can be created during initial setup or by enabling registrations temporarily via `GITEA__service__DISABLE_REGISTRATION=false`.
 
-6. Configure SSH
+### 4. Provision users
 
-**Note: This is probably not worth pursuing and I've given up on it. The following has only sort of worked for me.**
+From the admin account: **Site Administration > User Accounts > Create User Account**.
 
-Via Traefik:
-- Add another entrypoint in `traefik.toml`:
+### 5. Configure SSH
+
+SSH is exposed via Traefik TCP passthrough on port 2222:
+- The `gitea` entrypoint on `:2222` is defined in `traefik.toml`.
+- TCP router labels in `docker-compose.yml` forward `2222` → container port `2222`.
+- `SSH_DOMAIN` and `SSH_PORT=2222` in `gitea.env` tell Gitea what to advertise in clone URLs.
+
+Test SSH:
 ```
-entryPoints:
-  gitea:
-    address: ":2222"
+ssh -T -p 2222 git@git.whitney.rip
 ```
-- Configure similar traefik labels to what we normally do for containers:
-```
-- traefik.tcp.routers.gitea_ssh.rule=HostSNI(`*`)
-- traefik.tcp.routers.gitea_ssh.entrypoints=ssh
-- traefik.tcp.routers.gitea_ssh.service=gitea_ssh
-- traefik.tcp.services.gitea_ssh.loadbalancer.server.port=22
-```
-7. Handle user authentication like you'd do on Github by generating new ssh keys and adding them to the SSH Keys section.
-Settings > SSH/GPG Keys > Manage SSH Keys  
-Now should also be able to clone with SSH.
 
-### Running
+### 6. Add SSH keys for users
+
+**Settings > SSH/GPG Keys > Manage SSH Keys** — same flow as GitHub.
+
+## Running
+
 ```
 docker compose down && docker compose build && docker compose up -d && docker logs -f gitea
 ```
-
-### References
-`https://docs.gitea.com/next/administration/config-cheat-sheet`

software-development/gitea/docker-compose.yml

@@ -25,6 +25,10 @@ services:
       - traefik.http.routers.gitea.tls=true
       - traefik.http.routers.gitea.tls.certresolver=lets-encrypt
       - traefik.http.services.gitea.loadbalancer.server.port=3000
+      - traefik.tcp.routers.gitea-ssh.rule=HostSNI(`*`)
+      - traefik.tcp.routers.gitea-ssh.entrypoints=gitea
+      - traefik.tcp.routers.gitea-ssh.service=gitea-ssh-svc
+      - traefik.tcp.services.gitea-ssh-svc.loadbalancer.server.port=2222
 
   database:
     image: postgres:14

software-development/gitea/gitea.env.example

@@ -2,6 +2,10 @@ USER_UID=1005
 USER_GID=1007
 GITEA__server__PROTOCOL=http
 GITEA__server__ROOT_URL=https://git.example.com
+GITEA__server__SSH_DOMAIN=git.example.com
+GITEA__server__START_SSH_SERVER=true
+GITEA__server__SSH_LISTEN_PORT=2222
+GITEA__server__SSH_PORT=2222
 GITEA__database__DB_TYPE=postgres
 GITEA__database__HOST=database:5432
 GITEA__database__NAME=gitea