chore: bootstrap Atay Makhzan ops repo
This commit is contained in:
@@ -0,0 +1,49 @@
|
||||
# ADR-0001: Current Gitea Docker Compose Architecture
|
||||
|
||||
## Status
|
||||
|
||||
Accepted.
|
||||
|
||||
## Context
|
||||
|
||||
Atay Makhzan needs a sovereign Git forge controlled by Saad ibn Zoubayr. The current operational need is reliability, simple maintenance, backups, and controlled upgrades.
|
||||
|
||||
## Decision
|
||||
|
||||
Run official Gitea in Docker Compose with PostgreSQL, reverse-proxied by Nginx with Certbot TLS.
|
||||
|
||||
Current production shape:
|
||||
|
||||
- Gitea image pinned to `gitea/gitea:1.26.2`
|
||||
- PostgreSQL image `postgres:16-alpine`
|
||||
- Gitea HTTP served locally on port `3001`
|
||||
- Public HTTPS via Nginx on `ataymakhzan.com`
|
||||
- Git SSH exposed on port `2222`
|
||||
- Persistent data mounted under `/opt/gitea`
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- Simple architecture
|
||||
- Easy backups
|
||||
- Easy rollback through Docker image pinning and database dumps
|
||||
- Low operational burden
|
||||
- Enough for current private forge needs
|
||||
|
||||
### Negative
|
||||
|
||||
- Single VPS is a single point of failure
|
||||
- Scaling and HA are manual future work
|
||||
- Public customization is limited unless we theme, extend, or fork
|
||||
- Production safety depends on disciplined backups and upgrade procedure
|
||||
|
||||
## Future trigger for revisiting
|
||||
|
||||
Revisit this decision if Atay Makhzan needs:
|
||||
|
||||
- Multi-node availability
|
||||
- Custom product features inside the forge
|
||||
- Organization-wide policy automation not available in Gitea
|
||||
- Deep UI/UX changes that themes cannot support
|
||||
- Integrated CI/package registry workflows beyond Gitea's native capabilities
|
||||
@@ -0,0 +1,60 @@
|
||||
# Future Gitea Fork Strategy
|
||||
|
||||
Saad's long-term intent is valid: Atay Makhzan may eventually differ enough from upstream Gitea that we maintain our own source code separately.
|
||||
|
||||
But the sequencing matters.
|
||||
|
||||
## CTO verdict
|
||||
|
||||
Do not fork Gitea just because we can.
|
||||
|
||||
Fork only when one of these is true:
|
||||
|
||||
1. The required feature cannot be achieved with configuration.
|
||||
2. It cannot be achieved cleanly with Gitea Actions, webhooks, external automation, or themes.
|
||||
3. The feature is core to Atay Makhzan's identity as a product.
|
||||
4. Maintaining the patch is cheaper than working around upstream.
|
||||
5. We have time to track upstream security releases and merge conflicts.
|
||||
|
||||
## Recommended stages
|
||||
|
||||
### Stage 1 — Ops sovereignty
|
||||
|
||||
This repository.
|
||||
|
||||
Goal: make deployment reproducible, documented, backed up, and safe to upgrade.
|
||||
|
||||
### Stage 2 — External extensions
|
||||
|
||||
Use webhooks, scripts, bots, custom templates, and integrations around Gitea without touching upstream source.
|
||||
|
||||
### Stage 3 — Theming and UX identity
|
||||
|
||||
Customize branding, templates, and public surfaces while remaining close to upstream.
|
||||
|
||||
### Stage 4 — Source fork
|
||||
|
||||
Create a dedicated source repository only when Atay Makhzan needs product behavior that upstream Gitea will not support.
|
||||
|
||||
Suggested future repo name:
|
||||
|
||||
```text
|
||||
ibnezzoubayr/Atay-Makhzan
|
||||
```
|
||||
|
||||
This ops repo should remain separate:
|
||||
|
||||
```text
|
||||
ibnezzoubayr/Atay-Makhzan-Ops
|
||||
```
|
||||
|
||||
## Fork discipline
|
||||
|
||||
If we fork:
|
||||
|
||||
- Track upstream Gitea releases.
|
||||
- Keep a changelog of every divergence.
|
||||
- Keep custom patches small and isolated.
|
||||
- Add tests for every custom behavior.
|
||||
- Maintain an upstream merge schedule.
|
||||
- Never delay critical upstream security patches for cosmetic customization.
|
||||
@@ -0,0 +1,32 @@
|
||||
# Restore Notes
|
||||
|
||||
Restoring Atay Makhzan can destroy or overwrite live data. Do not run restore actions without explicit owner approval.
|
||||
|
||||
## Backup artifacts expected
|
||||
|
||||
A complete backup directory should contain:
|
||||
|
||||
- `gitea-dump-<timestamp>.zip`
|
||||
- `gitea-postgres-<timestamp>.dump`
|
||||
- `docker-compose.yml`
|
||||
- `app.ini`
|
||||
- `metadata.txt`
|
||||
- `SHA256SUMS`
|
||||
|
||||
## Safer restore principle
|
||||
|
||||
Prefer restoring to a fresh VPS or staging directory first, then verifying repository data before touching production.
|
||||
|
||||
## High-level restore sequence
|
||||
|
||||
1. Provision VPS and install Docker/Nginx.
|
||||
2. Restore sanitized Compose configuration.
|
||||
3. Restore PostgreSQL dump into a fresh database.
|
||||
4. Restore Gitea data from Gitea dump according to the Gitea version documentation.
|
||||
5. Start containers.
|
||||
6. Verify API, web, SSH auth, and `git ls-remote` on known repositories.
|
||||
7. Switch DNS/proxy only after verification.
|
||||
|
||||
## Production warning
|
||||
|
||||
Do not remove `/opt/gitea/gitea-data` or `/opt/gitea/postgres-data` unless a verified backup exists and Saad explicitly approved the restore.
|
||||
@@ -0,0 +1,71 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user