[init]

README.md

@@ -0,0 +1,165 @@
+# Gitea on Dokploy
+
+Self-hosted Gitea deployment running on Dokploy with a local Postgres database.
+
+- **Domain**: `gitea.routinedevelopment.ca`
+- **SSH**: Port 2222 (built-in SSH server, HTTP git disabled)
+- **Database**: Local Postgres 16 (container `gitea-db`)
+- **Volumes**: `gitea-data` (repos, LFS, avatars, SSH keys), `db-data` (Postgres)
+
+## Setup (Fresh Install)
+
+1. Install Dokploy on a clean Ubuntu server:
+
+```bash
+curl -sSL https://dokploy.com/install.sh | sh
+```
+
+2. Create a new Project in Dokploy called "Gitea".
+
+3. Create a Docker Compose service inside the project. Paste the contents of `docker-compose.yml`.
+
+4. Add the environment variable in Dokploy's UI:
+
+```
+POSTGRES_PASSWORD=your_strong_password
+```
+
+5. Deploy. Let it complete the first boot.
+
+6. Point your DNS A record for `gitea.routinedevelopment.ca` to the server IP.
+
+7. In Dokploy's UI, go to the Gitea compose service → **Domains** tab. Add `gitea.routinedevelopment.ca` with container port `3000`, HTTPS enabled, and Let's Encrypt certificate. The docs say Traefik labels alone should work, but in practice you may need to also add the domain via the UI.
+
+8. Redeploy so Traefik picks up the domain and issues the Let's Encrypt certificate.
+
+### Domain Troubleshooting
+
+If the domain doesn't work after deploying:
+
+- **DNS must resolve first**: Let's Encrypt needs to reach the server. Make sure your DNS/reserved IP points to the server *before* adding the domain in Dokploy. If added too early, recreate the domain or restart Traefik.
+- **`dokploy-network` is required**: Traefik runs on `dokploy-network`. If your compose service isn't on that network, Traefik can't reach it even if the labels are correct. The compose file in this repo already handles this.
+- **Reserved IP mismatch**: If using a DigitalOcean reserved IP, Dokploy may complain that the domain resolves to the reserved IP instead of the droplet's direct IP. This is fine — traffic still reaches the server. Deploy anyway.
+- **Redeploy after any domain change**: Unlike Applications, Docker Compose services require a redeploy for domain changes to take effect.
+
+## Restore from Backup
+
+If restoring onto a fresh Dokploy instance after the initial deploy:
+
+1. SCP the backup files to the server:
+
+```bash
+scp gitea_db_backup.dump user@server:~/
+scp gitea_files_backup.tar.gz user@server:~/
+scp app.ini user@server:~/    # the REAL one with secrets, not the template
+```
+
+2. SSH into the server and run the restore script:
+
+```bash
+chmod +x restore.sh
+./restore.sh
+```
+
+3. Verify at `https://gitea.routinedevelopment.ca` — all repos, users, and orgs should be present.
+
+## Backup
+
+Run from the Dokploy server:
+
+```bash
+chmod +x backup.sh
+./backup.sh
+```
+
+Backups are saved to `~/gitea-backups/` with timestamps. Each backup creates three files:
+
+- `gitea_db_YYYYMMDD_HHMMSS.dump` — Postgres database dump
+- `gitea_files_YYYYMMDD_HHMMSS.tar.gz` — Repositories, LFS, avatars, attachments, SSH keys
+- `app_YYYYMMDD_HHMMSS.ini` — Current app.ini config (contains secrets)
+
+You can specify a custom backup directory:
+
+```bash
+./backup.sh /path/to/backups
+```
+
+**Recommended**: Push backups offsite (S3, DigitalOcean Spaces, etc.). Don't rely solely on the same disk.
+
+## Automated Backups (Optional)
+
+Add a cron job on the server to run backups daily:
+
+```bash
+crontab -e
+```
+
+```
+0 3 * * * /path/to/backup.sh /home/user/gitea-backups >> /var/log/gitea-backup.log 2>&1
+```
+
+## Secrets
+
+The `app.ini` in this repo has `<CHANGE_ME>` placeholders. The real values you need to set:
+
+| Key | Location | Description |
+|-----|----------|-------------|
+| `LFS_JWT_SECRET` | `[server]` | JWT secret for LFS |
+| `INTERNAL_TOKEN` | `[security]` | Internal API token |
+| `JWT_SECRET` | `[oauth2]` | OAuth2 JWT secret |
+| `PASSWD` | `[database]` | Must match `POSTGRES_PASSWORD` env var |
+
+Keep your real `app.ini` as `app.ini.local` (gitignored) or in a password manager.
+
+## SSH Remotes
+
+Since HTTP git is disabled, all clones use SSH on port 2222:
+
+```bash
+git clone ssh://git@gitea.routinedevelopment.ca:2222/org/repo.git
+```
+
+Note: The container user is `git`, not `gitea`. If migrating from baremetal, update your remotes:
+
+```bash
+git remote set-url origin ssh://git@gitea.routinedevelopment.ca:2222/YourOrg/your-repo.git
+```
+
+## GitHub Mirror
+
+To push-mirror a repo to GitHub:
+
+1. Ensure the container has an SSH key:
+
+```bash
+docker exec gitea ls /data/git/.ssh/id_ed25519.pub
+```
+
+If not, generate one:
+
+```bash
+docker exec gitea ssh-keygen -t ed25519 -f /data/git/.ssh/id_ed25519 -N ""
+docker exec gitea chown git:git /data/git/.ssh/id_ed25519
+```
+
+2. Add the public key as a deploy key (with write access) on your GitHub repo.
+
+3. Set up a post-receive hook or cron to push.
+
+The SSH key lives in the `gitea-data` volume and persists across redeploys.
+
+## Volume Info
+
+| Volume | Contents | Path in container |
+|--------|----------|-------------------|
+| `gitea-data` | Repos, LFS, avatars, config, SSH keys | `/data` |
+| `db-data` | Postgres data | `/var/lib/postgresql/data` |
+
+Volumes persist across redeploys. They are only destroyed by `docker compose down -v` or `docker volume rm`. **Never run `down -v` in production.**
+
+Inspect volumes:
+
+```bash
+docker volume ls | grep gitea
+docker volume inspect <volume_name>
+```