From a2770e907277649afea764301a34298591e12e38 Mon Sep 17 00:00:00 2001 From: Karlos <73657806+krls2020@users.noreply.github.com> Date: Fri, 3 Apr 2026 14:33:11 +0200 Subject: [PATCH] chore(guides): update 25 guides --- apps/docs/content/guides/backup.mdx | 10 ---------- apps/docs/content/guides/build-cache.mdx | 9 --------- apps/docs/content/guides/cdn.mdx | 9 --------- apps/docs/content/guides/choose-cache.mdx | 9 --------- apps/docs/content/guides/choose-database.mdx | 9 --------- apps/docs/content/guides/choose-queue.mdx | 9 --------- apps/docs/content/guides/choose-runtime-base.mdx | 9 --------- apps/docs/content/guides/choose-search.mdx | 8 -------- apps/docs/content/guides/ci-cd.mdx | 12 ------------ apps/docs/content/guides/cloudflare.mdx | 10 ---------- .../docs/content/guides/deployment-lifecycle.mdx | 11 ----------- .../content/guides/environment-variables.mdx | 12 ------------ apps/docs/content/guides/firewall.mdx | 10 ---------- apps/docs/content/guides/local-development.mdx | 6 ------ apps/docs/content/guides/logging.mdx | 8 -------- apps/docs/content/guides/metrics.mdx | 9 --------- apps/docs/content/guides/networking.mdx | 16 ---------------- .../guides/object-storage-integration.mdx | 13 ------------- apps/docs/content/guides/php-tuning.mdx | 5 ----- .../docs/content/guides/production-checklist.mdx | 15 --------------- apps/docs/content/guides/public-access.mdx | 11 ----------- apps/docs/content/guides/scaling.mdx | 10 ---------- apps/docs/content/guides/smtp.mdx | 9 --------- apps/docs/content/guides/vpn.mdx | 9 --------- .../docs/content/guides/zerops-yaml-advanced.mdx | 10 ---------- 25 files changed, 248 deletions(-) diff --git a/apps/docs/content/guides/backup.mdx b/apps/docs/content/guides/backup.mdx index c4ae14d2..fca47ed3 100644 --- a/apps/docs/content/guides/backup.mdx +++ b/apps/docs/content/guides/backup.mdx @@ -3,11 +3,6 @@ title: "Backup on Zerops" description: "Zerops auto-backs up databases and storage daily (00:00-01:00 UTC) with X25519 encryption; backups are retained for 7 days minimum after service/project deletion." --- - -## Keywords -backup, restore, snapshot, daily backup, cron backup, encryption, retention, backup schedule - -## TL;DR Zerops auto-backs up databases and storage daily (00:00-01:00 UTC) with X25519 encryption; backups are retained for 7 days minimum after service/project deletion. ## Supported Services @@ -59,8 +54,3 @@ End-to-end with X25519 per-project keys. Decrypted only on download. 1. **Object Storage has no Zerops backup**: Use S3 lifecycle policies or external backup 2. **Valkey/KeyDB not backed up**: In-memory data — use persistence or application-level backup 3. **Backup storage is shared**: All services in a project share the backup quota - -## See Also -- zerops://themes/core — platform infrastructure -- zerops://themes/services — database service cards -- zerops://guides/scaling diff --git a/apps/docs/content/guides/build-cache.mdx b/apps/docs/content/guides/build-cache.mdx index 1d42f7ef..cf2efbfe 100644 --- a/apps/docs/content/guides/build-cache.mdx +++ b/apps/docs/content/guides/build-cache.mdx @@ -3,11 +3,6 @@ title: "Build Cache" description: "Zerops uses a two-layer build cache: base layer (OS + prepareCommands) and build layer (buildCommands output). The `cache:` attribute in zerops.yml controls which files persist between builds. Changing `build.os`, `build.base`, `build.prepareCommands`, or `build.cache` invalidates both layers (cascade)." --- - -## Keywords -build cache, cache, invalidation, prepareCommands, buildCommands, base layer, build layer, node_modules, vendor, cache paths, cache true, cache false, build speed, build optimization, two-layer cache, cascade invalidation - -## TL;DR Zerops uses a two-layer build cache: base layer (OS + prepareCommands) and build layer (buildCommands output). The `cache:` attribute in zerops.yml controls which files persist between builds. Changing `build.os`, `build.base`, `build.prepareCommands`, or `build.cache` invalidates both layers (cascade). --- @@ -97,7 +92,3 @@ CPU 1-5 cores, RAM 8 GB fixed, Disk 1-100 GB, Timeout 60 min. User `zerops` with 2. **`cache: false` is misleading**: Only clears `/build/source` cache. Globally installed packages (Go modules, pip packages) persist in the base layer 3. **No-clobber restore**: If source repo contains a file also in cache, **source wins** -- the cached version is silently skipped (logged but does not fail) 4. **Lock file caching**: Cache lock files (`package-lock.json`, `composer.lock`) alongside dependency directories for consistent installs - -## See Also -- zerops://themes/core -- zerops.yml schema and cache attribute syntax -- zerops://guides/deployment-lifecycle -- full build and deploy pipeline sequence diff --git a/apps/docs/content/guides/cdn.mdx b/apps/docs/content/guides/cdn.mdx index 1644ae50..3b9d2cb8 100644 --- a/apps/docs/content/guides/cdn.mdx +++ b/apps/docs/content/guides/cdn.mdx @@ -3,11 +3,6 @@ title: "CDN on Zerops" description: "Zerops CDN has 6 global regions with a **fixed 30-day cache TTL** (HTTP Cache-Control headers are ignored by CDN but still affect browsers). Built on Nginx + Cloudflare geo-steering." --- - -## Keywords -cdn, cache, edge, content delivery, static assets, object storage cdn, geo-steering, purge, cache invalidation - -## TL;DR Zerops CDN has 6 global regions with a **fixed 30-day cache TTL** (HTTP Cache-Control headers are ignored by CDN but still affect browsers). Built on Nginx + Cloudflare geo-steering. ## Regions @@ -63,7 +58,3 @@ zsc cdn purge /style.css$ # Purge exact file 1. **30-day fixed TTL**: Cannot be changed — `Cache-Control: max-age=3600` has no effect on CDN 2. **No wildcard domains on static CDN**: `*.domain.com` is not supported 3. **Purge wildcards at end only**: `/images/*.jpg` is invalid — use `/images/*` - -## See Also -- zerops://themes/services — Object Storage service card -- zerops://guides/public-access diff --git a/apps/docs/content/guides/choose-cache.mdx b/apps/docs/content/guides/choose-cache.mdx index 40f0cf08..1debb17d 100644 --- a/apps/docs/content/guides/choose-cache.mdx +++ b/apps/docs/content/guides/choose-cache.mdx @@ -3,11 +3,6 @@ title: "Choosing a Cache on Zerops" description: "**Use Valkey.** KeyDB development has stalled and is effectively deprecated on Zerops." --- - -## Keywords -cache, redis, valkey, keydb, in-memory, session, key-value, choose cache, which cache - -## TL;DR **Use Valkey.** KeyDB development has stalled and is effectively deprecated on Zerops. ## Decision Matrix @@ -35,7 +30,3 @@ cache, redis, valkey, keydb, in-memory, session, key-value, choose cache, which 1. **HA replication is async**: Brief data loss possible during master failover 2. **Port forwarding is Zerops-specific**: Replicas forward 6379/6380 to master — this is not standard Redis/Valkey behavior 3. **Read replicas use different ports**: 7000/7001 for direct replica reads - -## See Also -- zerops://themes/services — Valkey, KeyDB service cards and wiring -- zerops://decisions/choose-database diff --git a/apps/docs/content/guides/choose-database.mdx b/apps/docs/content/guides/choose-database.mdx index d173c54b..fd6231e4 100644 --- a/apps/docs/content/guides/choose-database.mdx +++ b/apps/docs/content/guides/choose-database.mdx @@ -3,11 +3,6 @@ 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." --- - -## Keywords -database, postgresql, mariadb, clickhouse, sql, relational, columnar, analytics, postgres, mysql, choose database, which database - -## TL;DR **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. ## Decision Matrix @@ -43,7 +38,3 @@ database, postgresql, mariadb, clickhouse, sql, relational, columnar, analytics, 1. **HA mode is immutable**: Cannot switch HA/NON_HA after creation — delete and recreate 2. **No internal TLS**: Use `http://hostname:port` internally — VPN provides encryption 3. **PostgreSQL URI scheme**: Some libraries need `postgres://` not `postgresql://` — create a custom env var - -## See Also -- zerops://themes/services — PostgreSQL, MariaDB, ClickHouse service cards and wiring -- zerops://decisions/choose-cache diff --git a/apps/docs/content/guides/choose-queue.mdx b/apps/docs/content/guides/choose-queue.mdx index 79fec030..cabc8c4f 100644 --- a/apps/docs/content/guides/choose-queue.mdx +++ b/apps/docs/content/guides/choose-queue.mdx @@ -3,11 +3,6 @@ title: "Choosing a Message Queue on Zerops" description: "**Use NATS** for most cases (simple, fast, JetStream persistence). Use **Kafka** only for enterprise event streaming with guaranteed ordering and unlimited retention." --- - -## Keywords -queue, message queue, kafka, nats, event, stream, pub-sub, broker, choose queue, which queue, messaging - -## TL;DR **Use NATS** for most cases (simple, fast, JetStream persistence). Use **Kafka** only for enterprise event streaming with guaranteed ordering and unlimited retention. ## Decision Matrix @@ -45,7 +40,3 @@ queue, message queue, kafka, nats, event, stream, pub-sub, broker, choose queue, 2. **Kafka single-node has no replication**: 1 broker = 3 partitions but zero redundancy 3. **NATS JetStream HA sync interval**: 1-minute sync across nodes — brief data lag possible 4. **Kafka SASL only**: No anonymous connections — always use the generated credentials - -## See Also -- zerops://themes/services — NATS, Kafka service cards and wiring -- zerops://decisions/choose-database diff --git a/apps/docs/content/guides/choose-runtime-base.mdx b/apps/docs/content/guides/choose-runtime-base.mdx index bbadfa7f..cbb9faff 100644 --- a/apps/docs/content/guides/choose-runtime-base.mdx +++ b/apps/docs/content/guides/choose-runtime-base.mdx @@ -3,11 +3,6 @@ title: "Choosing a Runtime Base on Zerops" description: "**Use Alpine** as the default base for all services. Use Ubuntu only when you need system packages not available in Alpine. Use Docker only for pre-built images." --- - -## Keywords -alpine, ubuntu, docker, container, base image, linux, runtime base, os, choose base, which container - -## TL;DR **Use Alpine** as the default base for all services. Use Ubuntu only when you need system packages not available in Alpine. Use Docker only for pre-built images. ## Decision Matrix @@ -48,7 +43,3 @@ alpine, ubuntu, docker, container, base image, linux, runtime base, os, choose b 2. **Docker is VM-based**: Vertical scaling restarts the VM — expect brief downtime 3. **Docker `:latest` is cached**: Zerops won't re-pull — always use specific tags like `myapp:1.2.3` 4. **Docker requires host networking**: Without `--network=host`, the container can't receive traffic - -## See Also -- `zerops://runtimes/{name}` — per-runtime guides (e.g. zerops://runtimes/alpine, zerops://runtimes/docker) -- zerops://themes/core — build environment rules diff --git a/apps/docs/content/guides/choose-search.mdx b/apps/docs/content/guides/choose-search.mdx index dd86385b..88425b86 100644 --- a/apps/docs/content/guides/choose-search.mdx +++ b/apps/docs/content/guides/choose-search.mdx @@ -3,11 +3,6 @@ title: "Choosing a Search Engine on Zerops" description: "**Use Meilisearch** for simple full-text search. Use **Elasticsearch** for advanced queries or HA requirements. Use **Qdrant** for vector/AI search." --- - -## Keywords -search, elasticsearch, meilisearch, typesense, qdrant, vector, full-text, choose search, which search engine - -## TL;DR **Use Meilisearch** for simple full-text search. Use **Elasticsearch** for advanced queries or HA requirements. Use **Qdrant** for vector/AI search. ## Decision Matrix @@ -55,6 +50,3 @@ search, elasticsearch, meilisearch, typesense, qdrant, vector, full-text, choose 2. **Qdrant is internal-only**: Cannot be exposed publicly — access via your runtime service 3. **Typesense API key is immutable**: Cannot change `apiKey` after service creation 4. **Elasticsearch plugins require restart**: Changing `PLUGINS` env var needs service restart - -## See Also -- zerops://themes/services — Meilisearch, Elasticsearch, Typesense, Qdrant service cards and wiring diff --git a/apps/docs/content/guides/ci-cd.mdx b/apps/docs/content/guides/ci-cd.mdx index 52d53f56..a9b8b2b7 100644 --- a/apps/docs/content/guides/ci-cd.mdx +++ b/apps/docs/content/guides/ci-cd.mdx @@ -3,11 +3,6 @@ title: "CI/CD on Zerops" description: "Zerops supports GitHub/GitLab webhook triggers (new tag or push to branch) and GitHub Actions / GitLab CI via `zcli push` with an access token." --- - -## Keywords -ci cd, github, gitlab, github actions, gitlab ci, webhook, automatic deploy, trigger, pipeline, continuous deployment, zcli push, jenkins, circleci, generic ci - -## TL;DR Zerops supports GitHub/GitLab webhook triggers (new tag or push to branch) and GitHub Actions / GitLab CI via `zcli push` with an access token. ## GitHub Integration (Webhook) @@ -20,7 +15,6 @@ Zerops supports GitHub/GitLab webhook triggers (new tag or push to branch) and G ### GitHub Actions ```yaml -# .github/workflows/deploy.yaml name: Deploy on: push jobs: @@ -59,7 +53,6 @@ Service detail → Build, Deploy, Run → Stop automatic build trigger. ## GitLab CI ```yaml -# .gitlab-ci.yml deploy: stage: deploy image: ubuntu:latest @@ -89,8 +82,3 @@ Any CI system with shell access can deploy via `zcli push`: | `--workspace-state` | `all` (default), `clean` (git clean), `staged` (staged only) | | `--no-git` | Deploy without git context | | `--deploy-git-folder` | Include `.git/` directory in deploy | - -## See Also -- zerops://themes/core -- zerops.yml schema reference -- zerops://guides/deployment-lifecycle -- build and deploy pipeline -- zerops://themes/core -- platform infrastructure diff --git a/apps/docs/content/guides/cloudflare.mdx b/apps/docs/content/guides/cloudflare.mdx index 72b70f5e..fecbeb49 100644 --- a/apps/docs/content/guides/cloudflare.mdx +++ b/apps/docs/content/guides/cloudflare.mdx @@ -3,11 +3,6 @@ title: "Cloudflare Integration with Zerops" description: "Always use **Full (strict)** SSL mode in Cloudflare — \"Flexible\" causes redirect loops. Shared IPv4 with Cloudflare proxy is not recommended." --- - -## Keywords -cloudflare, dns, ssl, tls, proxy, cname, aaaa, redirect loop, full strict, acme, wildcard domain, cloudflare ssl - -## TL;DR Always use **Full (strict)** SSL mode in Cloudflare — "Flexible" causes redirect loops. Shared IPv4 with Cloudflare proxy is not recommended. ## DNS Configuration @@ -70,8 +65,3 @@ Internal service-to-service communication must always use `http://` — never `h 3. **ACME challenge needs WAF exception**: Without it, Cloudflare blocks Let's Encrypt validation 4. **Wildcard SSL on Cloudflare Free**: Free plan doesn't proxy wildcard subdomains — use DNS-only or upgrade 5. **Subdomain on undeployed service**: `zerops_subdomain enable` returns "Service stack is not http or https" on READY_TO_DEPLOY services — deploy code first or use `enableSubdomainAccess` in import YAML - -## See Also -- zerops://guides/public-access -- zerops://guides/firewall -- zerops://guides/networking diff --git a/apps/docs/content/guides/deployment-lifecycle.mdx b/apps/docs/content/guides/deployment-lifecycle.mdx index 0016b844..0336490c 100644 --- a/apps/docs/content/guides/deployment-lifecycle.mdx +++ b/apps/docs/content/guides/deployment-lifecycle.mdx @@ -3,11 +3,6 @@ title: "Deployment Lifecycle" description: "Zerops build & deploy pipeline: temporary build container runs prepareCommands + buildCommands, uploads artifact via deployFiles, then deploys to runtime containers with optional readiness checks. Default is zero-downtime rolling deployment. Build has a 60-minute timeout. The pipeline emits events trackable via `zerops_events`." --- - -## Keywords -deploy, build, pipeline, lifecycle, build container, deploy process, rolling deployment, zero downtime, readiness check, health check, temporaryShutdown, build timeout, artifact, deploy files, prepareCommands, buildCommands, init commands, start command, container replacement, application version, build cancel, runtime prepare - -## TL;DR Zerops build & deploy pipeline: temporary build container runs prepareCommands + buildCommands, uploads artifact via deployFiles, then deploys to runtime containers with optional readiness checks. Default is zero-downtime rolling deployment. Build has a 60-minute timeout. The pipeline emits events trackable via `zerops_events`. --- @@ -174,9 +169,3 @@ When using SSHFS (`zerops_mount`) for dev workflows, deploy replaces the contain **Two kinds of "mount" (disambiguation):** - `zerops_mount` -- SSHFS tool, mounts service `/var/www` locally for development. This is a dev workflow tool. - Shared storage mount -- platform feature, attaches a shared-storage volume at `/mnt/{hostname}` via `mount:` in import.yml + zerops.yml `run.mount`. These are completely unrelated features. - -## See Also -- zerops://themes/core -- zerops.yml schema and platform rules -- zerops://guides/build-cache -- two-layer cache architecture and invalidation -- zerops://guides/ci-cd -- triggering pipelines from GitHub/GitLab -- zerops://guides/logging -- build and runtime log access diff --git a/apps/docs/content/guides/environment-variables.mdx b/apps/docs/content/guides/environment-variables.mdx index 8c4440fd..5cf1fe7d 100644 --- a/apps/docs/content/guides/environment-variables.mdx +++ b/apps/docs/content/guides/environment-variables.mdx @@ -3,11 +3,6 @@ title: "Environment Variables" description: "Zerops manages environment variables at two scopes (project and service) with strict build/runtime isolation. Variables are set via zerops.yml, import.yml, or GUI. Cross-service references use `${hostname_varname}` syntax. Project vars auto-inherit into all services. Secret vars are write-only after creation. Changes require service restart." --- - -## Keywords -environment variables, env, envVariables, envSecrets, dotEnvSecrets, envReplace, secrets, project variables, service variables, cross-service reference, variable precedence, build runtime isolation, RUNTIME_ prefix, BUILD_ prefix, variable shadowing, envIsolation, restart, placeholder replacement - -## TL;DR Zerops manages environment variables at two scopes (project and service) with strict build/runtime isolation. Variables are set via zerops.yml, import.yml, or GUI. Cross-service references use `${hostname_varname}` syntax. Project vars auto-inherit into all services. Secret vars are write-only after creation. Changes require service restart. --- @@ -96,11 +91,9 @@ Project variables are **automatically available** in every service (build and ru **DO NOT** re-reference project variables in service envVariables: ```yaml -# WRONG -- creates shadow, may cause circular reference envVariables: PROJECT_NAME: ${PROJECT_NAME} -# CORRECT -- just use it in your app code, it's already there ``` To **override** a project variable for one service, define a service-level variable with the same key: @@ -172,8 +165,3 @@ Zerops auto-generates variables per service (e.g., `hostname`, `PATH`, DB connec - **DO NOT** expect `envReplace` to recurse subdirectories -- it does not - **DO NOT** rely on reading secret values back -- they are write-only after creation - **DO NOT** create both secret and basic vars with same key -- basic silently wins - -## See Also -- zerops://themes/core -- schema, build/deploy semantics, variable basics -- zerops://themes/services -- cross-service wiring patterns using env vars -- zerops://guides/production-checklist -- pre-launch variable audit diff --git a/apps/docs/content/guides/firewall.mdx b/apps/docs/content/guides/firewall.mdx index 240ab6f8..8ab4916b 100644 --- a/apps/docs/content/guides/firewall.mdx +++ b/apps/docs/content/guides/firewall.mdx @@ -3,11 +3,6 @@ title: "Firewall on Zerops" description: "Zerops uses nftables with restricted TCP ports 1-1024 (only 22, 53, 80, 123, 443, 587 allowed); UDP and ports 1025-65535 are unrestricted." --- - -## Keywords -firewall, ports, nftables, tcp, udp, blocked ports, smtp port, port restriction, allowed ports - -## TL;DR Zerops uses nftables with restricted TCP ports 1-1024 (only 22, 53, 80, 123, 443, 587 allowed); UDP and ports 1025-65535 are unrestricted. ## TCP Ports 1-1024 (Restricted) @@ -43,8 +38,3 @@ Contact `support@zerops.io` with Project ID + Organization ID to request changes 1. **Port 25 is permanently blocked**: Use port 587 with STARTTLS for email sending 2. **Port 465 is blocked**: Legacy SMTPS — use 587 instead 3. **Cannot self-service unblock**: Must contact Zerops support for port exceptions - -## See Also -- zerops://guides/public-access -- zerops://guides/smtp -- zerops://guides/networking diff --git a/apps/docs/content/guides/local-development.mdx b/apps/docs/content/guides/local-development.mdx index 1abe9148..d0f8d029 100644 --- a/apps/docs/content/guides/local-development.mdx +++ b/apps/docs/content/guides/local-development.mdx @@ -3,11 +3,6 @@ title: "Local Development with Zerops" description: "Develop locally with hot reload while connecting to Zerops managed services (DB, cache, storage) via VPN. ZCP generates `.env` with real credentials. Deploy to Zerops with `zerops_deploy` which uses `zcli push` under the hood." --- - -## Keywords -local development, local dev, zcli push, vpn, env file, dotenv, hot reload, dev server, local mode, zcli vpn, local deploy, environment variables local - -## TL;DR Develop locally with hot reload while connecting to Zerops managed services (DB, cache, storage) via VPN. ZCP generates `.env` with real credentials. Deploy to Zerops with `zerops_deploy` which uses `zcli push` under the hood. --- @@ -47,7 +42,6 @@ zcli vpn up ### 2. Load credentials ZCP generates `.env` from `zerops_discover`: ``` -# db (postgresql@16) db_host=db db_port=5432 db_password= diff --git a/apps/docs/content/guides/logging.mdx b/apps/docs/content/guides/logging.mdx index b827818f..80d28e18 100644 --- a/apps/docs/content/guides/logging.mdx +++ b/apps/docs/content/guides/logging.mdx @@ -3,11 +3,6 @@ title: "Logging on Zerops" description: "Zerops captures stdout/stderr as logs; use syslog output format for severity filtering. Supports forwarding to Better Stack, Papertrail, or self-hosted ELK via syslog." --- - -## Keywords -logging, logs, syslog, build logs, runtime logs, service log, log access, log severity, log forwarding, better stack, papertrail, elk, logstash, syslog-ng, external logging, log aggregation - -## TL;DR Zerops captures stdout/stderr as logs; use syslog output format for severity filtering. Supports forwarding to Better Stack, Papertrail, or self-hosted ELK via syslog. ## Log Types @@ -66,6 +61,3 @@ Certificate paths: 3. **Source name must be `s_src`**: Using `s_sys` (common default) will not capture Zerops logs 4. **UDP for Logstash**: Zerops forwards logs via UDP syslog — ensure Logstash listens on UDP 5. **Custom certs path**: Place custom CA certs in `/etc/syslog-ng/user.crt` - -## See Also -- zerops://guides/metrics diff --git a/apps/docs/content/guides/metrics.mdx b/apps/docs/content/guides/metrics.mdx index 514bd7e3..851d73f9 100644 --- a/apps/docs/content/guides/metrics.mdx +++ b/apps/docs/content/guides/metrics.mdx @@ -3,11 +3,6 @@ title: "Metrics on Zerops" description: "Zerops supports ELK (APM + logs) and Prometheus/Grafana stacks; expose `/metrics` endpoint and set `ZEROPS_PROMETHEUS_PORT` for auto-scraping." --- - -## Keywords -metrics, monitoring, prometheus, grafana, elk, apm, elastic apm, observability, custom metrics, dashboard - -## TL;DR Zerops supports ELK (APM + logs) and Prometheus/Grafana stacks; expose `/metrics` endpoint and set `ZEROPS_PROMETHEUS_PORT` for auto-scraping. ## Deployment Modes @@ -55,7 +50,3 @@ envVariables: 1. **`ZEROPS_PROMETHEUS_PORT` is required**: Without it, Prometheus won't discover your custom metrics endpoint 2. **APM server must be public**: Use Zerops subdomain to expose apmserver for trace collection 3. **Cross-project needs forwarder**: Use `prometheuslight` service in source project to forward to global Prometheus - -## See Also -- zerops://guides/logging -- zerops://themes/services — Elasticsearch, PostgreSQL service cards diff --git a/apps/docs/content/guides/networking.mdx b/apps/docs/content/guides/networking.mdx index c354733e..b920ff61 100644 --- a/apps/docs/content/guides/networking.mdx +++ b/apps/docs/content/guides/networking.mdx @@ -3,11 +3,6 @@ title: "Networking on Zerops" description: "Zerops networking has two layers: a private VXLAN network per project (service-to-service via hostname, plain HTTP) and an L7 balancer for public traffic (SSL termination, round-robin, health checks). Apps must bind `0.0.0.0` — binding localhost causes 502. The L7 balancer is nginx-based with configurable timeouts, buffers, rate limiting, and access policies." --- - -## Keywords -networking, vxlan, l7 balancer, load balancer, ssl termination, 502, bad gateway, internal access, service discovery, hostname, proxy headers, x-forwarded-for, x-real-ip, bind, 0.0.0.0, localhost, round robin, health check, keepalive, nginx, connection timeout, websocket, rate limiting, access policy, basic auth, internal port, http, https - -## TL;DR Zerops networking has two layers: a private VXLAN network per project (service-to-service via hostname, plain HTTP) and an L7 balancer for public traffic (SSL termination, round-robin, health checks). Apps must bind `0.0.0.0` — binding localhost causes 502. The L7 balancer is nginx-based with configurable timeouts, buffers, rate limiting, and access policies. --- @@ -103,16 +98,12 @@ Work through these steps **in order**: **Common framework fixes:** ```bash -# Node.js/Express — bind to 0.0.0.0 app.listen(3000, '0.0.0.0') -# Python/Flask flask run --host=0.0.0.0 -# Go http.ListenAndServe(":8080", handler) // implicit 0.0.0.0 -# Java/Spring Boot — in application.properties server.address=0.0.0.0 ``` @@ -151,10 +142,3 @@ server.address=0.0.0.0 4. **send_timeout default is 2s**: Slow API responses may be cut off — increase for long-running endpoints 5. **Cross-project networking impossible**: Each project is an isolated VXLAN — use public access to bridge projects 6. **Shared IPv4 needs AAAA**: Missing AAAA record = silent routing failure on shared IPv4 - -## See Also -- zerops://themes/core — Traffic Flow, Binding & Networking, Port Rules -- zerops://guides/public-access — IP types, DNS setup, domain configuration -- zerops://guides/cloudflare — Cloudflare-specific DNS and SSL setup -- zerops://guides/firewall — port restrictions and outbound rules -- zerops://guides/vpn — VPN access to private network diff --git a/apps/docs/content/guides/object-storage-integration.mdx b/apps/docs/content/guides/object-storage-integration.mdx index 5a96144f..4e64de5b 100644 --- a/apps/docs/content/guides/object-storage-integration.mdx +++ b/apps/docs/content/guides/object-storage-integration.mdx @@ -3,11 +3,6 @@ title: "Object Storage Integration on Zerops" description: "Zerops Object Storage is S3-compatible (MinIO). Always set `AWS_USE_PATH_STYLE_ENDPOINT: true`. Use env var references `${storage_*}` for credentials. Container filesystem is lost on deploy — use Object Storage for any files that must persist across deployments." --- - -## Keywords -object storage, s3, minio, aws, upload, files, media, storage integration, flysystem, boto3, aws-sdk, path style, bucket, persistent files - -## TL;DR Zerops Object Storage is S3-compatible (MinIO). Always set `AWS_USE_PATH_STYLE_ENDPOINT: true`. Use env var references `${storage_*}` for credentials. Container filesystem is lost on deploy — use Object Storage for any files that must persist across deployments. ## Environment Variables @@ -27,7 +22,6 @@ When you create an Object Storage service, Zerops auto-generates these env vars Reference them in zerops.yml `run.envVariables`: ```yaml -# zerops.yml run.envVariables S3_ENDPOINT: ${storage_apiUrl} S3_ACCESS_KEY: ${storage_accessKeyId} S3_SECRET_KEY: ${storage_secretAccessKey} @@ -41,10 +35,8 @@ AWS_USE_PATH_STYLE_ENDPOINT: "true" Zerops uses MinIO which requires **path-style** URLs (not virtual-hosted): ``` -# Path-style (correct for Zerops): https://endpoint.com/bucket-name/object-key -# Virtual-hosted (WRONG for Zerops): https://bucket-name.endpoint.com/object-key ``` @@ -152,8 +144,3 @@ Each service = one bucket (auto-named, immutable). Need multiple buckets? Create 6. **One bucket per service**: Bucket name auto-generated (hostname + random prefix), cannot be changed. Need multiple buckets? Add more object-storage services 7. **No Zerops backup**: Object Storage is not covered by the Zerops backup system 8. **No autoscaling**: Quota (1-100 GB) must be set manually, changeable in GUI after creation - -## See Also -- zerops://themes/services — managed service reference (Object Storage section) -- zerops://themes/core — import.yml schema -- zerops://guides/environment-variables — cross-service env var references diff --git a/apps/docs/content/guides/php-tuning.mdx b/apps/docs/content/guides/php-tuning.mdx index 6441829b..9a0a9be2 100644 --- a/apps/docs/content/guides/php-tuning.mdx +++ b/apps/docs/content/guides/php-tuning.mdx @@ -3,11 +3,6 @@ title: "PHP Runtime Tuning on Zerops" description: "Override php.ini via `PHP_INI_*` env vars, FPM via `PHP_FPM_*`. Both require **restart** (not reload). Zerops defaults: upload/post = 1024M, FPM dynamic 20/2/1/3. Upload bottleneck is L7 balancer (50MB subdomain), not PHP." --- - -## Keywords -PHP_INI, PHP_FPM, php.ini, fpm, upload_max_filesize, post_max_size, memory_limit, max_execution_time, max_children, ondemand, dynamic, php tuning, upload limit, file upload - -## TL;DR Override php.ini via `PHP_INI_*` env vars, FPM via `PHP_FPM_*`. Both require **restart** (not reload). Zerops defaults: upload/post = 1024M, FPM dynamic 20/2/1/3. Upload bottleneck is L7 balancer (50MB subdomain), not PHP. ## PHP Configuration (`PHP_INI_*`) diff --git a/apps/docs/content/guides/production-checklist.mdx b/apps/docs/content/guides/production-checklist.mdx index 60d68d2f..152270ed 100644 --- a/apps/docs/content/guides/production-checklist.mdx +++ b/apps/docs/content/guides/production-checklist.mdx @@ -3,11 +3,6 @@ title: "Production Checklist for Zerops" description: "Before going to production: (1) databases to HA mode, (2) minContainers: 2 on app services, (3) replace Mailpit with real SMTP, (4) remove Adminer, (5) use Object Storage for uploads, (6) use Redis/Valkey for sessions." --- - -## Keywords -production, checklist, ha, high availability, minContainers, mailpit, smtp, adminer, volatile, sessions, object storage, deploy production, go-live, launch - -## TL;DR Before going to production: (1) databases to HA mode, (2) minContainers: 2 on app services, (3) replace Mailpit with real SMTP, (4) remove Adminer, (5) use Object Storage for uploads, (6) use Redis/Valkey for sessions. ## Database @@ -30,7 +25,6 @@ Before going to production: (1) databases to HA mode, (2) minContainers: 2 on ap | Debug mode | Enabled | Disabled | ```yaml -# Production app service - hostname: app type: nodejs@22 minContainers: 2 @@ -41,12 +35,10 @@ Before going to production: (1) databases to HA mode, (2) minContainers: 2 on ap ### Mailpit → Production SMTP ```yaml -# REMOVE for production: - hostname: mailpit type: go@1 buildFromGit: https://github.com/zeropsio/recipe-mailpit -# REPLACE with production SMTP env vars: envVariables: SMTP_HOST: smtp.sendgrid.net SMTP_PORT: "587" @@ -69,7 +61,6 @@ Remove entirely or disable `enableSubdomainAccess`. Use VPN + pgAdmin/DBeaver lo | Build artifacts | Deploy via zerops.yaml | ```yaml -# Add Object Storage for persistent files - hostname: storage type: object-storage objectStorageSize: 2 @@ -88,7 +79,6 @@ Remove entirely or disable `enableSubdomainAccess`. Use VPN + pgAdmin/DBeaver lo | Express sessions | Redis store | ```yaml -# Add Valkey for sessions/cache - hostname: cache type: valkey@7.2 mode: NON_HA # HA for production @@ -168,8 +158,3 @@ Readiness check gates traffic during deploy. Health check runs continuously — 4. **Mailpit is not production SMTP**: Only for dev — no delivery guarantees 5. **Debug mode leaks secrets**: Disable APP_DEBUG in production 6. **Missing health checks**: Load balancer can't route around unhealthy containers - -## See Also -- zerops://themes/core — import.yml patterns -- zerops://guides/scaling -- zerops://guides/backup diff --git a/apps/docs/content/guides/public-access.mdx b/apps/docs/content/guides/public-access.mdx index 1909c966..911e36b4 100644 --- a/apps/docs/content/guides/public-access.mdx +++ b/apps/docs/content/guides/public-access.mdx @@ -3,11 +3,6 @@ title: "Public Access on Zerops" description: "Zerops offers three public access methods: zerops.app subdomains (dev only, 50MB upload limit), custom domains (production, needs IPv4/IPv6), and direct port access (TCP/UDP on 10-65435)." --- - -## Keywords -public access, domain, subdomain, zerops.app, ipv4, ipv6, https, ssl, custom domain, dedicated ip, shared ip, direct port - -## TL;DR Zerops offers three public access methods: zerops.app subdomains (dev only, 50MB upload limit), custom domains (production, needs IPv4/IPv6), and direct port access (TCP/UDP on 10-65435). ## Access Methods @@ -52,9 +47,3 @@ Point your domain to the project's IP: 2. **zerops.app 50MB limit**: File uploads over 50MB fail on subdomains — use custom domain 3. **Dedicated IPv4 is non-refundable**: $3/30 days, auto-renews — cannot get refund if removed early 4. **Ports 80/443 reserved**: Your app cannot bind to these — Zerops uses them for SSL termination - -## See Also -- zerops://guides/cloudflare -- zerops://guides/firewall -- zerops://guides/networking -- zerops://themes/core — platform infrastructure diff --git a/apps/docs/content/guides/scaling.mdx b/apps/docs/content/guides/scaling.mdx index fd62116f..d612324a 100644 --- a/apps/docs/content/guides/scaling.mdx +++ b/apps/docs/content/guides/scaling.mdx @@ -3,11 +3,6 @@ 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." --- - -## Keywords -scaling, autoscaling, vertical scaling, horizontal scaling, CPU, RAM, disk, containers, SHARED, DEDICATED, cpuMode, minCpu, maxCpu, minRam, maxRam, minDisk, maxDisk, minContainers, maxContainers, minFreeRamGB, minFreeRamPercent, startCpuCoreCount, verticalAutoscaling, HA, NON_HA, OOM, out of memory, scale up, scale down, threshold, Docker VM - -## TL;DR 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. ## When to Scale Which Way @@ -207,8 +202,3 @@ zerops_scale serviceHostname="worker" cpuMode="SHARED" minCpu=1 maxCpu=8 minRam= **DO NOT** forget that disk **never shrinks** -- setting a high `minDisk` is permanent for that container's lifetime. **DO NOT** assume horizontal scaling works automatically -- your application must be stateless. File-based sessions, local uploads, and in-memory state break with multiple containers. - -## See Also -- zerops://themes/core -- import.yml schema and platform rules (section 9: Scaling basics) -- zerops://guides/production-checklist -- HA mode, minContainers recommendations -- zerops://themes/services -- managed service reference and mode constraints diff --git a/apps/docs/content/guides/smtp.mdx b/apps/docs/content/guides/smtp.mdx index f32ce2bf..dac7476a 100644 --- a/apps/docs/content/guides/smtp.mdx +++ b/apps/docs/content/guides/smtp.mdx @@ -3,11 +3,6 @@ title: "SMTP on Zerops" description: "Only port **587** (STARTTLS) is allowed for outbound email — ports 25 and 465 are permanently blocked. Use an external email service." --- - -## Keywords -smtp, email, mail, sendgrid, mailgun, ses, gmail, port 587, starttls, send email - -## TL;DR Only port **587** (STARTTLS) is allowed for outbound email — ports 25 and 465 are permanently blocked. Use an external email service. ## Port Configuration @@ -42,7 +37,3 @@ envSecrets: 1. **Port 25 is permanently blocked**: Cannot be unblocked — use 587 with STARTTLS 2. **Port 465 is also blocked**: Legacy SMTPS is deprecated — use 587 3. **Gmail needs App Password**: Regular Gmail passwords won't work — generate an App Password in Google Account settings - -## See Also -- zerops://guides/firewall -- zerops://guides/environment-variables diff --git a/apps/docs/content/guides/vpn.mdx b/apps/docs/content/guides/vpn.mdx index 7bb7c006..4799a7b4 100644 --- a/apps/docs/content/guides/vpn.mdx +++ b/apps/docs/content/guides/vpn.mdx @@ -3,11 +3,6 @@ title: "VPN on Zerops" description: "Zerops VPN uses WireGuard via `zcli vpn up ` — connects to one project at a time, services accessible by hostname, but env vars are NOT available through VPN." --- - -## Keywords -vpn, wireguard, zcli vpn, vpn up, vpn down, local development, service access, mtu - -## TL;DR Zerops VPN uses WireGuard via `zcli vpn up ` — connects to one project at a time, services accessible by hostname, but env vars are NOT available through VPN. ## Commands @@ -44,7 +39,3 @@ zcli vpn down # Disconnect 1. **No env vars via VPN**: Must read env vars from GUI or API — VPN only provides network access 2. **One project at a time**: Cannot connect to multiple projects simultaneously 3. **Hostname resolution**: Both `hostname` and `hostname.zerops` work (VPN sets up DNS search domain). Use plain hostname for simplicity. If resolution fails on Windows, add `zerops` to DNS suffix list in Advanced TCP/IP Settings. - -## See Also -- zerops://guides/networking -- zerops://guides/firewall diff --git a/apps/docs/content/guides/zerops-yaml-advanced.mdx b/apps/docs/content/guides/zerops-yaml-advanced.mdx index e6402a78..8fb7980a 100644 --- a/apps/docs/content/guides/zerops-yaml-advanced.mdx +++ b/apps/docs/content/guides/zerops-yaml-advanced.mdx @@ -3,11 +3,6 @@ title: "zerops.yml Advanced Behavioral Reference" description: "Behavioral semantics for advanced zerops.yml features: health/readiness checks, deploy strategies, cron, background processes, runtime init, envReplace, routing, and `extends`. Schema is in grammar.md -- this file covers what the schema cannot express." --- - -## Keywords -zerops.yml, health check, healthCheck, readiness check, readinessCheck, routing, cors, redirects, headers, crontab, cron, startCommands, initCommands, prepareCommands, envReplace, temporaryShutdown, zero downtime, rolling deploy, base image, extends, container lifecycle - -## TL;DR Behavioral semantics for advanced zerops.yml features: health/readiness checks, deploy strategies, cron, background processes, runtime init, envReplace, routing, and `extends`. Schema is in grammar.md -- this file covers what the schema cannot express. --- @@ -188,8 +183,3 @@ Available runtimes and versions are listed in **Service Stacks (live)** -- injec - `@latest` = newest stable version --- - -## See Also -- zerops://themes/core -- zerops.yml schema reference and platform rules -- `zerops://runtimes/{name}` -- per-runtime configuration guides (e.g. zerops://runtimes/nodejs) -- zerops://guides/production-checklist -- production readiness including health check setup