From d3d928683749829d7e30acd4080321f56ccaaa5b Mon Sep 17 00:00:00 2001
From: Christopher Berger <chris@wittenberger.us>
Date: Fri, 29 May 2026 01:38:35 +0000
Subject: [PATCH] Add README.md

---
 README.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 158 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e437970
--- /dev/null
+++ b/README.md
@@ -0,0 +1,158 @@
+# Uzik's Gitea Server
+
+Self-hosted Git service running [Gitea](https://gitea.com/) via Docker Compose with a PostgreSQL backend.
+
+---
+
+## Repository Contents
+
+| File | Description |
+|------|-------------|
+| `docker-compose.yml` | Defines the `gitea` and `db` (PostgreSQL 14) services |
+| `app.ini` | Gitea application configuration (production mode) |
+
+---
+
+## Stack
+
+- **Gitea** - latest image from `docker.gitea.com/gitea`
+- **PostgreSQL 14** - database backend
+- **LFS** - Git Large File Storage enabled
+- **Mailer** - SMTP integration enabled
+- **SSH** - External port `222` forwarded to internal port `22`
+
+---
+
+## Prerequisites
+
+- Docker + Docker Compose installed on the host
+- A domain name or static IP for `DOMAIN` / `ROOT_URL`
+- An SMTP server for mailer/registration email support
+- A reverse proxy (e.g. Nginx Proxy Manager, Caddy, Traefik) terminating HTTPS in front of port `3000`
+
+---
+
+## Setup
+
+### 1. Clone / copy this repo onto your server
+
+```bash
+git clone <this-repo-url> gitea
+cd gitea
+```
+
+### 2. Set passwords in `docker-compose.yml`
+
+Replace both placeholder values with the same strong password:
+
+```yaml
+- GITEA__database__PASSWD=<set_a_password>   # in the gitea service
+- POSTGRES_PASSWORD=<password_from_above>    # in the db service
+```
+
+### 3. Configure `app.ini`
+
+Fill in every `<placeholder>` before first run:
+
+| Placeholder | Where | Description |
+|-------------|-------|-------------|
+| `<your_fqdn_or_IP>` | `[server]` | Public domain or IP (used in 3 fields) |
+| `<smtp_mail_server_IP_or_FQDN>` | `[mailer]` | Your SMTP server address |
+| `<from mailer address>` | `[mailer]` | Display address for outgoing mail |
+| `<sending mailer address>` | `[mailer]` | Auth username for SMTP |
+| `<'*' for all or IP of your reverse proxy>` | `[security]` | Trusted proxy IP(s) |
+
+> Secrets (`LFS_JWT_SECRET`, `INTERNAL_TOKEN`, `PASSWD`, `JWT_SECRET`, `SECRET_KEY`) are already populated in the running instance and shown as `<redacted>` in this file. **Do not commit real secrets to version control.**
+
+### 4. Start the stack
+
+```bash
+docker compose up -d
+```
+
+Gitea will be available at `http://<host>:3000` (or via your reverse proxy at the configured `ROOT_URL`).
+
+---
+
+## Ports
+
+| Port (Host) | Port (Container) | Protocol | Service |
+|-------------|------------------|----------|---------|
+| `3000` | `3000` | HTTP | Gitea web UI |
+| `222` | `22` | SSH | Git over SSH |
+
+> SSH clone URLs will use port 222: `ssh://git@<domain>:222/<user>/<repo>.git`
+
+---
+
+## Persistent Data
+
+| Host Path | Container Path | Contents |
+|-----------|----------------|----------|
+| `./gitea` | `/data` | Gitea repos, config, avatars, LFS, logs |
+| `./postgres` | `/var/lib/postgresql/data` | PostgreSQL data directory |
+
+Both directories are created automatically on first run.
+
+---
+
+## Notable Configuration
+
+- **Registration** - disabled by default (`DISABLE_REGISTRATION = true`). Set to `false` to allow public sign-ups.
+- **Email confirmation** - required for new accounts (`REGISTER_EMAIL_CONFIRM = true`).
+- **Email privacy** - user email addresses hidden by default (`DEFAULT_KEEP_EMAIL_PRIVATE = true`).
+- **OpenID / OAuth external login** - disabled.
+- **CAPTCHA** - enabled on registration.
+- **Secure cookies** - `COOKIE_SECURE` and `COOKIE_HTTPONLY` both enabled; requires HTTPS.
+- **Reverse proxy** - `REVERSE_PROXY_LIMIT = 2`; set `REVERSE_PROXY_TRUSTED_PROXIES` to your proxy's IP.
+- **Landing page** - redirects unauthenticated visitors to the login page.
+
+---
+
+## Updating Gitea
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+PostgreSQL data and Gitea data persist in the local bind-mount directories.
+
+---
+
+## Backups
+
+Recommended backup targets:
+
+```
+./gitea/       # all repos, LFS objects, attachments, avatars
+./postgres/    # database files (or use pg_dump for a portable SQL backup)
+```
+
+For a consistent database dump:
+
+```bash
+docker exec gitea-db pg_dump -U gitea gitea > gitea_backup_$(date +%F).sql
+```
+
+---
+
+## Troubleshooting
+
+**Container won't start / DB connection refused**
+Make sure both `GITEA__database__PASSWD` and `POSTGRES_PASSWORD` are set to the same value before first run.
+
+**SSH not working**
+Ensure port `222` is open in your firewall. Clone with `ssh://git@<domain>:222/...` or configure `~/.ssh/config`:
+```
+Host <domain>
+    Port 222
+```
+
+**Emails not sending**
+Check `[mailer]` values in `app.ini` and confirm your SMTP server allows connections from this host on port `587`.
+
+**Logs**
+```bash
+docker logs gitea -f
+```
\ No newline at end of file