diff --git a/apps/docs/content/guides/choose-cache.mdx b/apps/docs/content/guides/choose-cache.mdx index 446954fc..edb353ff 100644 --- a/apps/docs/content/guides/choose-cache.mdx +++ b/apps/docs/content/guides/choose-cache.mdx @@ -14,5 +14,6 @@ description: "**Use Valkey.** KeyDB development has stalled and is effectively d ## Valkey (Default Choice) - Redis-compatible drop-in replacement -- Version: use `valkey@7.2` — the platform rejects `valkey@8` at import (`serviceStackTypeNotFound`) +- Type: `valkey:single@7.2` (single) or `valkey:ha@7.2` (HA) — only v7.2 is supported (the platform rejects `valkey@8` at import, `serviceStackTypeNotFound`) +- Profile (scaling tier): `hobby` for dev (lowest cost), `staging` (default), or `production` - Connection: `redis://${hostname}:6379` — Valkey runs **unauthenticated** on Zerops; there are NO `user`/`password` env vars. Do **not** template `${cache_user}`/`${cache_password}` — they don't exist and produce a broken DSN diff --git a/apps/docs/content/guides/choose-database.mdx b/apps/docs/content/guides/choose-database.mdx index 2c415ce5..7df597e2 100644 --- a/apps/docs/content/guides/choose-database.mdx +++ b/apps/docs/content/guides/choose-database.mdx @@ -3,7 +3,7 @@ title: "Choosing a Database on Zerops" description: "**Use PostgreSQL** for everything unless you have a specific reason not to. It's the best-supported database on Zerops with full HA, read replicas, and pgBouncer." --- -**Use PostgreSQL** for everything unless you have a specific reason not to — the best-supported database on Zerops, with optional HA, read replicas, and pgBouncer. Default mode is **NON_HA** (single node); HA is opt-in and immutable after creation. +**Use PostgreSQL** for everything unless you have a specific reason not to — the best-supported database on Zerops, with optional HA, read replicas, and pgBouncer. HA vs single node is set in the type (`postgresql:single@` / `postgresql:ha@`) and is immutable; legacy `mode: NON_HA`/`HA` is deprecated (`NON_HA` ≡ `:single`, `HA` ≡ `:ha`). ## Decision Matrix @@ -15,6 +15,7 @@ description: "**Use PostgreSQL** for everything unless you have a specific reaso ## PostgreSQL (Default Choice) +- Type + scaling: `postgresql:single@` (single node, dev) or `postgresql:ha@` (HA cluster). Add a `profile` (scaling tier): `oltp-hobby` for dev — lowest cost — up to `oltp-production` / `oltp-enterprise` for production. Omitting it applies the default (single → `oltp-staging`, HA → `oltp-production`). See [PostgreSQL scaling](/postgresql/how-to/scale) - Connection: the generated `${connectionString}` is `postgresql://${user}:${password}@${hostname}:5432` (no database path). Append `/${dbName}` yourself if your driver needs one — the db-name var is `dbName` (default `db`) ## MariaDB diff --git a/apps/docs/content/guides/production-checklist.mdx b/apps/docs/content/guides/production-checklist.mdx index 95c141a7..db5ad198 100644 --- a/apps/docs/content/guides/production-checklist.mdx +++ b/apps/docs/content/guides/production-checklist.mdx @@ -9,11 +9,11 @@ Before going to production: (1) databases to HA mode, (2) minContainers: 2 on ap | Item | Dev | Production | |------|-----|------------| -| Mode | `NON_HA` | `HA` (must recreate) | +| Deployment variant | `:single` | `:ha` (must recreate) | | Backups | Optional | Enabled | | Connection | Single primary | Primary + read replicas | -**HA is immutable** — cannot switch after creation. Delete and recreate with `mode: HA`. +**The deployment variant is immutable** — cannot switch after creation. Delete and recreate with the `:ha` type variant (e.g. `postgresql:ha@16`). ## Application Services @@ -90,8 +90,7 @@ Remove entirely or disable `enableSubdomainAccess`. Use VPN + pgAdmin/DBeaver lo ```yaml - hostname: cache - type: valkey@7.2 - mode: NON_HA # HA for production + type: valkey:single@7.2 # use valkey:ha@7.2 for production ``` ## Framework-Specific Production Settings @@ -136,7 +135,7 @@ Remove entirely or disable `enableSubdomainAccess`. Use VPN + pgAdmin/DBeaver lo | CPU mode | `cpuMode: DEDICATED` for consistent performance under load | | Environment separation | Separate projects for dev/staging/prod | | Stateless design | Sessions in Valkey, uploads in Object Storage — no local state | -| Database mode | `mode: HA` for all managed services (immutable — plan before creation) | +| Database variant | `:ha@` for all managed services (immutable — plan before creation) | | Min containers | `minContainers: 2+` on app services for throughput + crash-tolerance (rolling deploys are already zero-downtime at any count via the default `temporaryShutdown: false` — don't conflate the two) | ## Health Check Pattern diff --git a/apps/docs/content/guides/scaling.mdx b/apps/docs/content/guides/scaling.mdx index 286359e9..e785a6be 100644 --- a/apps/docs/content/guides/scaling.mdx +++ b/apps/docs/content/guides/scaling.mdx @@ -1,9 +1,9 @@ --- title: "Scaling and Autoscaling" -description: "Zerops autoscales vertically (CPU/RAM/disk) and horizontally (container count). Runtimes support both. Managed services (DB, cache, shared-storage) support vertical only with fixed container count (NON_HA=1, HA=3). Object-storage and Docker have no autoscaling. Extends grammar.md section 9 with mechanics, thresholds, YAML syntax, and common mistakes." +description: "Zerops autoscales vertically (CPU/RAM/disk) and horizontally (container count). Runtimes support both. Managed services (DB, cache, shared-storage) support vertical only with fixed container count (`:single`=1, `:ha`=3). Object-storage and Docker have no autoscaling. Extends grammar.md section 9 with mechanics, thresholds, YAML syntax, and common mistakes." --- -Zerops autoscales vertically (CPU/RAM/disk) and horizontally (container count). Runtimes support both. Managed services (DB, cache, shared-storage) support vertical only with fixed container count (NON_HA=1, HA=3). Object-storage and Docker have no autoscaling. Extends grammar.md section 9 with mechanics, thresholds, YAML syntax, and common mistakes. +Zerops autoscales vertically (CPU/RAM/disk) and horizontally (container count). Runtimes support both. Managed services (DB, cache, shared-storage) support vertical only with fixed container count (`:single`=1, `:ha`=3). Object-storage and Docker have no autoscaling. Extends grammar.md section 9 with mechanics, thresholds, YAML syntax, and common mistakes. ## When to Scale Which Way @@ -20,9 +20,9 @@ Zerops autoscales vertically (CPU/RAM/disk) and horizontally (container count). |---|---|---|---| | **Runtime** (Node.js, Go, PHP, Python, Java, etc.) | Yes | Yes (1-10 containers) | Full autoscaling | | **Linux containers** (Alpine, Ubuntu) | Yes | Yes (1-10 containers) | Same as runtimes | -| **Managed DB** (PostgreSQL, MariaDB) | Yes | No (fixed: NON_HA=1, HA=3) | Mode immutable after creation | -| **Managed cache** (Valkey) | Yes | No (fixed: NON_HA=1, HA=3) | Mode immutable after creation | -| **Shared storage** | Yes (cpu/ram/disk configurable) | No (fixed: NON_HA=1, HA=3) | Accepts verticalAutoscaling in import.yml | +| **Managed DB** (PostgreSQL, MariaDB) | Yes | No (fixed: `:single`=1, `:ha`=3) | Variant immutable after creation | +| **Managed cache** (Valkey) | Yes | No (fixed: `:single`=1, `:ha`=3) | Variant immutable after creation | +| **Shared storage** | Yes (cpu/ram/disk configurable) | No (fixed: `:single`=1, `:ha`=3) | Accepts verticalAutoscaling in import.yml | | **Object storage** | No | No | Fixed size at creation, no verticalAutoscaling | | **Docker** | No (manual, triggers VM restart) | Manual only (change VM count, triggers restart) | No automatic autoscaling | @@ -111,12 +111,12 @@ Applies to **runtimes and Linux containers only**. New containers are added when ### Managed Services (DB, Cache, Shared Storage) -Container count is **fixed by deployment mode**, set at creation, **immutable**: +Container count is **fixed by the deployment variant** (`:single` / `:ha` in the type), set at creation, **immutable**: -| Mode | Containers | Use case | +| Variant | Containers | Use case | |---|---|---| -| `NON_HA` | 1 | Development, non-critical | -| `HA` | 3 (on separate physical machines) | Production, automatic failover | +| `:single` | 1 | Development, non-critical | +| `:ha` | 3 (on separate physical machines) | Production, automatic failover | HA recovery: failed container is disconnected, new one created on different hardware, data synchronized from healthy copies, failed container removed. @@ -154,8 +154,8 @@ services: # Managed DB (vertical only, no container settings) - hostname: db - type: postgresql@16 - mode: HA + type: postgresql:ha@16 + profile: oltp-production verticalAutoscaling: cpuMode: DEDICATED minCpu: 1