# Atay Makhzan Runbook

## Deployment shape

Atay Makhzan currently runs as a Docker Compose stack on a VPS:

- Stack directory: `/opt/gitea`
- Gitea container: `gitea`
- PostgreSQL container: `gitea-db`
- Public HTTPS: `https://ataymakhzan.com`
- Local Gitea HTTP: `http://127.0.0.1:3001`
- Git SSH: `ssh://git@ataymakhzan.com:2222/<owner>/<repo>.git`

## Normal health check

From the VPS:

```bash
cd /opt/gitea
docker compose ps
curl -fsS http://127.0.0.1:3001/api/v1/version
docker exec -u git gitea gitea doctor check -c /data/gitea/conf/app.ini -w /data/gitea
```

From outside:

```bash
curl -fsS https://ataymakhzan.com/api/v1/version
ssh -p 2222 -o BatchMode=yes -T git@ataymakhzan.com
git ls-remote --heads ssh://git@ataymakhzan.com:2222/ibnezzoubayr/Empire-OS.git
```

## Backup before maintenance

```bash
sudo STACK_DIR=/opt/gitea ./scripts/backup-gitea.sh
```

A proper backup should include:

- Gitea built-in dump
- PostgreSQL `pg_dump -Fc`
- `docker-compose.yml`
- `app.ini`
- metadata and checksums

## Upgrade policy

1. Inspect current state.
2. Create backup.
3. Pull target image.
4. Pin explicit Gitea version in Compose.
5. Recreate only the Gitea service.
6. Verify web, API, SSH, `git ls-remote`, and doctor check.

Do not run production on `gitea/gitea:latest`.

## Rollback policy

Rollback can involve code image rollback, config rollback, or database restore.

- Re-tagged Docker images are low-risk.
- Restoring database dumps is destructive and requires explicit owner approval.
- Never delete volumes during an emergency unless a verified backup exists.

## Routine cleanup candidates

- Remove obsolete Compose `version:` key from the live stack.
- Move deprecated Gitea `[picture]` options out of `app.ini` if still present.
- Add backup retention and offsite backup storage.
- Add uptime/health monitoring.