# Gitea Server — Context Briefing

Use this file at the start of any AI session that involves managing this
Gitea server. Paste its contents to give the AI full context.

---

## Server Identity

| Item | Value |
|------|-------|
| Hostname | GITREPO |
| IP | 192.168.0.126 |
| OS | Debian GNU/Linux 12 (bookworm) |
| Role | Self-hosted Gitea git server |
| Public domain | g.pozi.co.za |
| Platform | Proxmox LXC container |
| Disk | 500GB ZFS volume |

---

## Gitea Installation

| Item | Value |
|------|-------|
| Version | 1.25.4 |
| Binary | /usr/local/bin/gitea |
| Config | /etc/gitea/app.ini |
| Repo storage | /srv/git |
| Data/logs | /var/lib/gitea |
| Service | systemd — gitea.service |
| Run as user | git (uid 999) |
| Web port | localhost:3000 (internal only) |

---

## Network / TLS Architecture

```
Internet
  └── OPNsense router (public IP)
        ├── Port 80/443 → Nginx SNI proxy (another LAN server)
        │     └── g.pozi.co.za (SNI) → 192.168.0.126:443
        └── Port 2222 → 192.168.0.126:22  (SSH git access, external)

192.168.0.126
  ├── Nginx :80   — ACME challenge + redirect to HTTPS
  ├── Nginx :443  — TLS termination (Let's Encrypt cert) + proxy → :3000
  └── Gitea :3000 — internal only
```

- TLS cert: Let's Encrypt via Certbot, auto-renews
- Cert path: /etc/letsencrypt/live/g.pozi.co.za/
- Nginx config: /etc/nginx/sites-available/g.pozi.co.za

---

## Access Methods

### Web UI
```
https://g.pozi.co.za
```

### API
```
Base URL:  https://g.pozi.co.za/api/v1
LAN URL:   http://192.168.0.126:3000/api/v1
Token:     (request from owner — stored securely, not in this file)
Docs:      https://g.pozi.co.za/api/swagger
```

### SSH (git operations)
```
LAN:  git@192.168.0.126:gadmin/REPO.git          (port 22)
WAN:  git@g.pozi.co.za:gadmin/REPO.git           (port 2222)

~/.ssh/config entry for external access:
  Host g.pozi.co.za
      Port 2222
      User git
      IdentityFile ~/.ssh/id_gitea
```

---

## Admin Account

| Item | Value |
|------|-------|
| Username | gadmin |
| Email | richard@teacup.co.za |
| Name | Richard Brandon |
| Role | Admin |

---

## Existing Repositories

| Repo | Visibility | Purpose |
|------|------------|---------|
| gadmin/multiplan | Private | Multiplan PHP ERP deployment pipeline |
| gadmin/ai-prompts | Public | AI prompt and rules files (this repo) |

---

## Key File Locations

```
/etc/gitea/app.ini                          Gitea config
/etc/nginx/sites-available/g.pozi.co.za    Nginx vhost
/etc/systemd/system/gitea.service          Systemd service
/etc/letsencrypt/live/g.pozi.co.za/        TLS certificates
/srv/git/                                   Bare git repositories
/var/lib/gitea/                             Gitea data, logs, sessions
/home/git/.ssh/authorized_keys             SSH keys (managed by Gitea)
```

---

## Maintenance Commands

```bash
# Service control
systemctl status gitea
systemctl restart gitea
systemctl status nginx

# Check logs
journalctl -u gitea -n 50
tail -f /var/lib/gitea/log/gitea.log

# Certbot renewal (auto via timer, manual test)
certbot renew --dry-run

# Disk space
df -h

# Gitea version
gitea --version
```

---

## Backup Checklist

Items to back up periodically:
- `/etc/gitea/app.ini` — config (contains secrets)
- `/srv/git/` — all bare repo data
- `/var/lib/gitea/data/gitea.db` — SQLite database (users, keys, settings)
- `/etc/letsencrypt/` — TLS certs and account

---

## What This Server Does NOT Do

- It does not run application code
- It does not have a CI/CD runner
- It does not send email (mailer disabled)
- It is passive — receives pushes, serves pulls