From 1bde05e1d003f2fe5540632cbc023f5dc0a1438f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ale=C5=A1?= Date: Wed, 1 Apr 2026 13:04:34 +0200 Subject: [PATCH] chore(guides): update 25 guides --- apps/docs/content/guides/backup.mdx | 1 - apps/docs/content/guides/build-cache.mdx | 3 +-- apps/docs/content/guides/cdn.mdx | 1 - apps/docs/content/guides/choose-cache.mdx | 1 - apps/docs/content/guides/choose-database.mdx | 1 - apps/docs/content/guides/choose-queue.mdx | 1 - apps/docs/content/guides/choose-runtime-base.mdx | 1 - apps/docs/content/guides/choose-search.mdx | 1 - apps/docs/content/guides/ci-cd.mdx | 3 --- apps/docs/content/guides/cloudflare.mdx | 1 - apps/docs/content/guides/deployment-lifecycle.mdx | 1 - apps/docs/content/guides/environment-variables.mdx | 3 --- apps/docs/content/guides/firewall.mdx | 1 - apps/docs/content/guides/local-development.mdx | 2 -- apps/docs/content/guides/logging.mdx | 1 - apps/docs/content/guides/metrics.mdx | 1 - apps/docs/content/guides/networking.mdx | 5 ----- apps/docs/content/guides/object-storage-integration.mdx | 4 ---- apps/docs/content/guides/php-tuning.mdx | 1 - apps/docs/content/guides/production-checklist.mdx | 6 ------ apps/docs/content/guides/public-access.mdx | 1 - apps/docs/content/guides/scaling.mdx | 1 - apps/docs/content/guides/smtp.mdx | 1 - apps/docs/content/guides/vpn.mdx | 1 - apps/docs/content/guides/zerops-yaml-advanced.mdx | 1 - 25 files changed, 1 insertion(+), 43 deletions(-) diff --git a/apps/docs/content/guides/backup.mdx b/apps/docs/content/guides/backup.mdx index c4ae14d2..03729b10 100644 --- a/apps/docs/content/guides/backup.mdx +++ b/apps/docs/content/guides/backup.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/build-cache.mdx b/apps/docs/content/guides/build-cache.mdx index 1d42f7ef..ed4b262f 100644 --- a/apps/docs/content/guides/build-cache.mdx +++ b/apps/docs/content/guides/build-cache.mdx @@ -3,7 +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 @@ -75,7 +74,7 @@ Any change to these zerops.yml fields invalidates **both layers**: | Runtime | Recommended `cache:` paths | |---------|---------------------------| -| Node.js / Bun | `node_modules`, `.next`, `.turbo`, `package-lock.json` | +| Node.js / Bun | `node_modules`, `.next`, `.turbo`, `package-lock.json`, `bun.lock` | | Go | `cache: true` (modules live outside /build/source) | | PHP | `vendor`, `composer.lock` | | Python | `cache: true` (pip installs globally) or `.venv` | diff --git a/apps/docs/content/guides/cdn.mdx b/apps/docs/content/guides/cdn.mdx index 1644ae50..b6231f9a 100644 --- a/apps/docs/content/guides/cdn.mdx +++ b/apps/docs/content/guides/cdn.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/choose-cache.mdx b/apps/docs/content/guides/choose-cache.mdx index 40f0cf08..ce6a1a19 100644 --- a/apps/docs/content/guides/choose-cache.mdx +++ b/apps/docs/content/guides/choose-cache.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/choose-database.mdx b/apps/docs/content/guides/choose-database.mdx index d173c54b..746e5e9f 100644 --- a/apps/docs/content/guides/choose-database.mdx +++ b/apps/docs/content/guides/choose-database.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/choose-queue.mdx b/apps/docs/content/guides/choose-queue.mdx index 79fec030..473f5835 100644 --- a/apps/docs/content/guides/choose-queue.mdx +++ b/apps/docs/content/guides/choose-queue.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/choose-runtime-base.mdx b/apps/docs/content/guides/choose-runtime-base.mdx index bbadfa7f..971a78f1 100644 --- a/apps/docs/content/guides/choose-runtime-base.mdx +++ b/apps/docs/content/guides/choose-runtime-base.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/choose-search.mdx b/apps/docs/content/guides/choose-search.mdx index dd86385b..a03f00a0 100644 --- a/apps/docs/content/guides/choose-search.mdx +++ b/apps/docs/content/guides/choose-search.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/ci-cd.mdx b/apps/docs/content/guides/ci-cd.mdx index 52d53f56..acc5bba8 100644 --- a/apps/docs/content/guides/ci-cd.mdx +++ b/apps/docs/content/guides/ci-cd.mdx @@ -3,7 +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 @@ -20,7 +19,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 +57,6 @@ Service detail → Build, Deploy, Run → Stop automatic build trigger. ## GitLab CI ```yaml -# .gitlab-ci.yml deploy: stage: deploy image: ubuntu:latest diff --git a/apps/docs/content/guides/cloudflare.mdx b/apps/docs/content/guides/cloudflare.mdx index 72b70f5e..98022ad1 100644 --- a/apps/docs/content/guides/cloudflare.mdx +++ b/apps/docs/content/guides/cloudflare.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/deployment-lifecycle.mdx b/apps/docs/content/guides/deployment-lifecycle.mdx index 0016b844..21d1c100 100644 --- a/apps/docs/content/guides/deployment-lifecycle.mdx +++ b/apps/docs/content/guides/deployment-lifecycle.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/environment-variables.mdx b/apps/docs/content/guides/environment-variables.mdx index 8c4440fd..73cf6b71 100644 --- a/apps/docs/content/guides/environment-variables.mdx +++ b/apps/docs/content/guides/environment-variables.mdx @@ -3,7 +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 @@ -96,11 +95,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: diff --git a/apps/docs/content/guides/firewall.mdx b/apps/docs/content/guides/firewall.mdx index 240ab6f8..e6ce82ae 100644 --- a/apps/docs/content/guides/firewall.mdx +++ b/apps/docs/content/guides/firewall.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/local-development.mdx b/apps/docs/content/guides/local-development.mdx index 1abe9148..18685a36 100644 --- a/apps/docs/content/guides/local-development.mdx +++ b/apps/docs/content/guides/local-development.mdx @@ -3,7 +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 @@ -47,7 +46,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..f6efa10d 100644 --- a/apps/docs/content/guides/logging.mdx +++ b/apps/docs/content/guides/logging.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/metrics.mdx b/apps/docs/content/guides/metrics.mdx index 514bd7e3..dbfd0361 100644 --- a/apps/docs/content/guides/metrics.mdx +++ b/apps/docs/content/guides/metrics.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/networking.mdx b/apps/docs/content/guides/networking.mdx index c354733e..cade3926 100644 --- a/apps/docs/content/guides/networking.mdx +++ b/apps/docs/content/guides/networking.mdx @@ -3,7 +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 @@ -103,16 +102,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 ``` diff --git a/apps/docs/content/guides/object-storage-integration.mdx b/apps/docs/content/guides/object-storage-integration.mdx index 5a96144f..870f64d5 100644 --- a/apps/docs/content/guides/object-storage-integration.mdx +++ b/apps/docs/content/guides/object-storage-integration.mdx @@ -3,7 +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 @@ -27,7 +26,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 +39,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 ``` diff --git a/apps/docs/content/guides/php-tuning.mdx b/apps/docs/content/guides/php-tuning.mdx index 6441829b..f4bcfc86 100644 --- a/apps/docs/content/guides/php-tuning.mdx +++ b/apps/docs/content/guides/php-tuning.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/production-checklist.mdx b/apps/docs/content/guides/production-checklist.mdx index 60d68d2f..6ed65386 100644 --- a/apps/docs/content/guides/production-checklist.mdx +++ b/apps/docs/content/guides/production-checklist.mdx @@ -3,7 +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 @@ -30,7 +29,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 +39,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 +65,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 +83,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 diff --git a/apps/docs/content/guides/public-access.mdx b/apps/docs/content/guides/public-access.mdx index 1909c966..2f40cf20 100644 --- a/apps/docs/content/guides/public-access.mdx +++ b/apps/docs/content/guides/public-access.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/scaling.mdx b/apps/docs/content/guides/scaling.mdx index fd62116f..ccbae8ba 100644 --- a/apps/docs/content/guides/scaling.mdx +++ b/apps/docs/content/guides/scaling.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/smtp.mdx b/apps/docs/content/guides/smtp.mdx index f32ce2bf..3c227513 100644 --- a/apps/docs/content/guides/smtp.mdx +++ b/apps/docs/content/guides/smtp.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/vpn.mdx b/apps/docs/content/guides/vpn.mdx index 7bb7c006..1a64f6d1 100644 --- a/apps/docs/content/guides/vpn.mdx +++ b/apps/docs/content/guides/vpn.mdx @@ -3,7 +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 diff --git a/apps/docs/content/guides/zerops-yaml-advanced.mdx b/apps/docs/content/guides/zerops-yaml-advanced.mdx index e6402a78..c19fb3c5 100644 --- a/apps/docs/content/guides/zerops-yaml-advanced.mdx +++ b/apps/docs/content/guides/zerops-yaml-advanced.mdx @@ -3,7 +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