Initial commit

docs/OCI_ARCHITECTURE.md

@@ -0,0 +1,107 @@
+# OCI Deployment Architecture & Sizing
+
+## Architecture Diagram (Small)
+
+```
+                       ┌─────────────────────────────┐
+                       │           VM #1             │
+                       │    Coolify + Gitea          │
+                       └──────────────┬──────────────┘
+                                      │
+                                      │ Deploys/Manages
+                                      ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                             VM #2                               │
+│  ┌─────────────────────┐   ┌───────────────────────────────┐    │
+│  │   Next.js App #1     │   │  Next.js App #2 / #3 (future) │    │
+│  └──────────┬──────────┘   └───────────────┬───────────────┘    │
+│             │                              │                    │
+│             └──────────────┬───────────────┘                    │
+│                            ▼                                    │
+│                    ┌──────────────┐                             │
+│                    │  PgBouncer   │  (transaction pooling)      │
+│                    └──────┬───────┘                             │
+│                           │                                     │
+│           ┌───────────────┼───────────────┐                     │
+│           ▼                               ▼                     │
+│     ┌─────────────┐                 ┌─────────────┐             │
+│     │ PostgreSQL  │                 │    Redis    │             │
+│     └─────────────┘                 └─────────────┘             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Workload Assumptions
+- Daily users: ~200
+- Peak concurrent users: 20–30
+- Peak connections: <= 100 (spiky)
+- Future: +2 Next.js apps sharing the same Postgres/Redis/PgBouncer
+
+## OCI VM Specs (Current)
+- 2 OCPU
+- 12 GB RAM
+- 100 GB SSD
+- Oracle Linux
+- 4 GB bandwidth
+
+This is sufficient for the current app and two additional small Next.js apps.
+
+## System Requirements (Recommended for Shared Services)
+
+### Single VM (App + PgBouncer + Redis + Postgres)
+- CPU: 2 OCPU (OK) or 4 OCPU (better headroom)
+- RAM: 8–12 GB (you have 12 GB, good)
+- Disk: 80–120 GB SSD (you have 100 GB, good)
+
+### Split VMs (Optional for more stability)
+- VM A: Coolify + Gitea (2 OCPU / 8 GB RAM)
+- VM B: App server (2 OCPU / 4–8 GB RAM)
+- VM C: Database + PgBouncer + Redis (2 OCPU / 8–12 GB RAM)
+
+## PgBouncer Configuration (Applied)
+
+Location: docker/pgbouncer.ini
+
+- pool_mode = transaction
+- max_client_conn = 500
+- default_pool_size = 40
+- min_pool_size = 10
+- reserve_pool_size = 20
+- reserve_pool_timeout = 3
+- max_db_connections = 120
+- max_user_connections = 60
+- server_idle_timeout = 120
+- server_lifetime = 3600
+- server_reset_query = DISCARD ALL
+- auth_type = md5
+- listen_port = 6432
+
+These values are tuned for:
+- 20–30 concurrent users now
+- Up to 3 Next.js apps sharing the pool later
+- Protecting Postgres from connection spikes
+
+## PostgreSQL Recommendations (Optional)
+If you want to pin exact server settings, use:
+
+- max_connections: 150–200
+- shared_buffers: 2GB
+- work_mem: 16MB
+- maintenance_work_mem: 256MB
+- effective_cache_size: 6GB
+
+Let me know if you want a mounted postgres.conf for these.
+
+## Redis Recommendations
+- Memory: 256–512 MB is enough for sessions and cache at this scale
+- Persistence: AOF enabled (already)
+
+## Notes
+- PgBouncer sits between apps and Postgres to prevent overload.
+- Redis offloads session and cache reads, reducing DB pressure.
+- With 12 GB RAM, you have plenty of headroom for 3 apps.
+
+## Next Step (Optional)
+If you want, I can:
+- Add a postgres.conf and mount it in docker-compose
+- Add PgBouncer metrics and health checks
+- Provide a production hardening checklist