zeropsio · fxck · Apr 1, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 <project-id>
 ### 2. Load credentials
 ZCP generates `.env` from `zerops_discover`:
 ```
-# db (postgresql@16)
 db_host=db
 db_port=5432
 db_password=<actual-password>

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -3,7 +3,6 @@ title: "VPN on Zerops"
 description: "Zerops VPN uses WireGuard via `zcli vpn up <project-id>` — 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
@@ -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
-Original file line number
+Diff line change
@@ Expand Up / @@ -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
@@ Expand Down @@