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