diff --git a/.gitignore b/.gitignore
index 656e2e629..3ee8c4417 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,8 +30,15 @@ www/**/.yarn/*
.eslintcache
.idea
+.vscode
.turbo
.yarn
build/**
**/dist
**/stats
+
+# ZCP local-mode runtime state — written by `zcp init` / `zcp serve`
+.zcp/
+
+# Generated full-text knowledge artifact (built via `zerops-llm-script.ts` prebuild)
+knowledge/
diff --git a/apps/docs/content/features/coding-agents.mdx b/apps/docs/content/features/coding-agents.mdx
new file mode 100644
index 000000000..6e8efb8ae
--- /dev/null
+++ b/apps/docs/content/features/coding-agents.mdx
@@ -0,0 +1,219 @@
+---
+title: 'Infrastructure for Coding Agents'
+description: 'Real project infrastructure for coding agents — runtimes, managed services, private networking, deploys, logs, and verification, exposed through MCP.'
+---
+
+import Icons from '@theme/Icon';
+import CodingAgentsTopology from '@site/src/components/CodingAgentsTopology';
+import IntroAgentVisual from '@site/src/components/IntroAgentVisual';
+
+Zerops was built on the idea of **environment parity** — giving developers the full development lifecycle, from remote development to highly available production, with the observability and developer tools for maximum flexibility, and sensible defaults so the configs stay reasonable. Turns out that's **exactly what coding agents need** to produce and iterate on production-ready applications.
+
+
+
+## What is it
+
+An **[MCP server](/zcp/overview)** for your agents — with an optional remote cloud development environment container to run them in — that makes use of the flexibility and processes Zerops provides. There's no "Zerops system prompt" hogging your context window. The MCP server is a thin layer that makes **your agent a Zerops platform power user** — when needed — so it understands:
+
+- how networking, scaling, debugging, build & deployment, environment variables, and service provisioning work on the platform
+- the development loop: start a dev server → implement → deploy to stage → verify
+
+The depth of the platform underneath is what gives the agent room to actually work. A single agent can scaffold and iterate on projects with multiple runtimes (`app`, `api`, `worker`) backed by multiple [managed services](/features/infrastructure) (object storage `storage`, Postgres `db`, Elasticsearch `search`, NATS `broker`, Valkey `cache`) — just as easily as it can work on a simple Next.js presentational website.
+
+A **[recipe ecosystem](https://app.zerops.io/recipes)** covering the most popular frameworks — pre-prepared for the whole lifecycle — gives the agent a baseline to start from, or a guide for setting up any stack on Zerops.
+
+
+
+
+
+Most coding-agent platforms went agent-first, then bolted on infrastructure — where it runs, how it reaches the database, how its output becomes production-ready, which third-party services to wire up. **Zerops went platform-first.** The complete development lifecycle existed before coding agents did; we taught them to operate it — **not just how to call APIs, but how to ship software the way a senior developer would.**
+
+
+
+
+
+## Main features
+
+### Your agent, your subscription
+
+Bring whichever agent you already use. Claude Code today; Codex, Gemini CLI, opencode, and any MCP-capable client next. The container is a regular Ubuntu — install your own CLI tools, drop in your `.claude` / `.cursor` configs, attach your IDE over SSH. **Zerops doesn't resell tokens or proxy your model calls** — sign in with your own Anthropic / OpenAI / Google subscription and the agent talks to its provider directly.
+
+### An ordinary Zerops project underneath
+
+The agent operates inside a normal Zerops project — same shape as production. Managed databases (PostgreSQL, MariaDB, ClickHouse), key-value stores (KeyDB, Valkey), search (Elasticsearch, Meilisearch, Typesense), vector store (Qdrant), message queues (NATS, Kafka), object and shared storage, managed Nginx — all on a private network, addressable by hostname. The same pipeline that deploys here can deploy to a separate HA production project with no `zcp` service attached. Not a sandbox the work outgrows.
+
+### Human ↔ agent handover
+
+The agent and the human share the same workspace — same filesystem, same SSH key, same Cloud IDE in the browser, same remote-dev attach from your local IDE. Take over mid-session, set something up before the agent runs, debug in the same container the agent just left. Nothing reaches production until you merge the PR — the agent opens it, you gate it.
+
+### Recipes for any stack
+
+Runtimes for Bun, Deno, Node.js, Go, Python, Rust, Java, .NET, PHP, Elixir, Gleam — with curated recipes for the framework on top: Next.js, Nuxt, Astro, Svelte, React, Vue, Angular, Solid, Qwik, Analog, NestJS, Laravel, and more. Pick a recipe, select the **AI Agent** environment, and the project comes up with a working dev runtime, a stage runtime, the right managed services wired in, and a coding agent briefed on the Zerops surface.
+
+
+
+## How it works in practice
+
+The agent reaches your project's private network one of two ways:
+
+- **Remote** — a `zcp` service deployed into the project runs the agent. You attach to it with Claude Code's IDE extension, with any IDE that supports remote development (Cursor, Windsurf, VS Code Remote), or by running [`zcli vpn up`](/references/networking/vpn) and ssh-ing into `zcp` to drive the rest of the project from a shell.
+- **Local** — install the `zcp` MCP on your machine and run `zcli vpn up` to join the network. From there your IDE, agent, and shell can ssh directly into any container.
+
+Either way, the agent reaches [managed services by hostname](/references/networking/internal-access) (`db:5432`, `cache:6379`), deploys through the [Zerops pipeline](/features/pipeline), and reads logs and events the same way you would.
+
+
+
+The agent runs through two workflows. **Bootstrap** settles which services and runtime targets the app needs. **Develop** is the short work loop — edit code on `appdev`, deploy to `appstage`, check it's reachable, verify behavior against `db:5432` and `cache:6379`, fix from evidence. A session ends with a URL you can open, or a specific blocker — failure category, attempts, what's still needed. Same hostnames, same managed services, same pipeline as production — just at smaller scale. See [Workflows in depth](/zcp/reference/agent-workflow) for both.
+
+{` `}{`zcp (local or remote)`}{`
+ │
+ ▼
+ edit code on `}{`appdev`}{` ◀────────────────────────┐
+ └ dev server, hot reload │
+ │ │
+ ▼ │
+ deploy to `}{`appstage`}{` │
+ │ │
+ ▼ │
+ check reachability │
+ │ │
+ ▼ │
+ verify behavior ─── fail ─────┐ │
+ │ │ │
+ │ pass ▼ │
+ ▼ read logs / events │
+ URL (proof) fix from evidence ─────┘`}
+
+Once the loop produces verified work, the agent doesn't push to production. It hands off — through whichever path your team uses: a tag push, a protected-branch merge, a manual `zcli` release, a pull request, or a CI job. **A human gates the release**, and the production deploy runs into a [separate production project](/zcp/security/production-policy) that has no `zcp` service at all.
+
+{` Dev project GitHub Prod project
+
+┌─────────────────────┐ ┌──────────────┐ ┌─────────────────────┐
+│ appdev │ │ │ │ app (HA) │
+│ appstage │ │ Pull │ │ │
+│ │ push │ Request │ CI/CD │ db (HA) │
+│ db, cache │ ────▶ │ │ ────▶ │ │
+│ │ │ `}{`+ human`}{` │ │ cache (HA) │
+│ `}{`zcp service`}{` │ │ `}{`review`}{` │ │ │
+│ │ │ │ │ (no zcp service) │
+└─────────────────────┘ └──────────────┘ └─────────────────────┘`}
+
+
+
+## Where does this fit in the agent landscape
+
+With the model clear, here's where ZCP sits among adjacent tools. People say "agent infrastructure," "infra for Claude agents," "agent hosting," or "agent sandboxes" to mean different things — usually one of the categories below.
+
+
+
+
Most major PaaS providers have shipped an MCP — provision services, deploy code, list resources, read operational state. Great for "let my agent ship to my Railway account." These are *deploy and operate* surfaces, driven from outside the platform — and they reflect what's underneath: platforms optimized for day-one deploy that tuck the infrastructure behind a wall. Once an agent needs to actually *develop* against that infrastructure — debug a failed health check, follow real logs, hit Postgres from inside the network, inspect what a build is doing, run the dev loop before it ships anything — the wall stops it. That's by design on those platforms, not a missing feature.
+
+
ZCP exposes the full **Bootstrap and Develop** loop as MCP-addressable primitives because Zerops was built around the development lifecycle from the start — not a dev loop retrofitted onto a deploy-first platform.
"Let your agent manage your Hetzner VPS." An MCP gives the agent access to a Linux box — provision it, SSH in, install Docker and Postgres and nginx, set up systemd units, point a domain at it. Maximum control, lowest cost, full Linux to play with. The same reason senior developers reach for managed platforms applies here: even if you *can* harden SSH, write nginx configs, tune `pg_hba.conf`, rotate TLS, set firewall rules, run fail2ban, and stay on top of CVEs across kernel, OpenSSL, Docker, Postgres, and nginx — you usually don't want to. Each layer is its own domain with its own gotchas, each is a security surface that drifts the moment you stop tending it, and every project becomes a snowflake. Hand that work to an agent and you also hand it the blast radius: misconfigured firewall, debug endpoint left open, port 5432 exposed to the internet, keys never rotated. ZCP is the inverse trade-off — the **guardrails** of a managed platform. Private networking, TLS, isolated services, safe defaults, managed backups, no exposed ports unless you opt in — all built in. The agent operates through [project-scoped MCP tools](/zcp/reference/mcp-operations) instead of `sudo` on a fresh Ubuntu box, so the mistakes that matter on a VPS aren't reachable from where it sits.
A managed Linux container in the cloud with your editor and an AI assistant attached. Solves "where the agent runs" so state survives between sessions and machine setup stops being a question. The `zcp` service is the closest thing in this category — managed Linux container, Cloud IDE, your agent of choice — except it lives *inside* a Zerops project, addressing the project's runtimes, database, and cache by hostname, with deploys and logs as primitives the agent can call.
The agent, the workspace, the stack, and (often) the hosting target are fused into one closed product. Fast for prototypes. Decisions are made for you. Switching agents usually means switching platforms, and production-grade primitives — a real dev/stage/prod release flow, private networking, observability — tend to be limited or absent. **ZCP doesn't bundle**: the agent and model stay yours on your own subscription, and the platform underneath is normal Zerops with the full stack of managed services, networking, deploys, and observability.
The agent runs on your machine, edits your local checkout, runs local commands. Excellent at code changes. Anything beyond your machine — databases, networking, deploy targets, runtime logs — is yours to wire in. Install the ZCP MCP locally and run `zcli vpn up`, and any of these agents can now reach a real Zerops project alongside your local code: services addressed by hostname, deploys, logs, events.
+
+
+
+
+
Code-execution sandboxes
+
+
+
+
+
+
+
E2B · Modal · Daytona · CodeSandbox SDK
+
+
Ephemeral Linux environments that AI *applications* spin up — often per request — to execute generated code safely. The right primitive when you're building a product that needs a model to run untrusted code and hand back the output. They're a building block for AI applications, not somewhere a coding agent settles in to iterate on your project. Different shape from ZCP; they show up here because the names cluster nearby.
Libraries for building and shipping agents to *your* users — tool calling, memory, orchestration, model providers, sometimes hosting. They're how somebody would build a product like ZCP, not where a coding agent runs against a project. Same disambiguation — adjacent on the shelf, different shape.
+
+
+
+
+## Where to start
+
+
diff --git a/apps/docs/content/features/local-remote-development.mdx b/apps/docs/content/features/local-remote-development.mdx
new file mode 100644
index 000000000..af7cc8269
--- /dev/null
+++ b/apps/docs/content/features/local-remote-development.mdx
@@ -0,0 +1,138 @@
+---
+title: Local & Remote Development
+description: Three ways to develop on Zerops — local with VPN, Cloud IDE, or your native IDE over SSH. Same network, same managed services, same pipeline as production.
+---
+
+import Icons from '@theme/Icon';
+
+Zerops development is network-first. Keep your editor on your laptop, work fully inside Zerops, or use a native editor over SSH — in each case you join the same project-private network with the same hostnames, credentials, managed services, and deploy pipeline that staging and production use. What changes between environments is policy: credentials, resources, access rules, data, and release authority — not the platform underneath.
+
+## How development on Zerops works
+
+Every project ships with a private network. Services reach each other by hostname (`db:5432`, `api:3000`, `redis:6379`), with credentials injected as environment variables.
+
+The development question is how you get onto that network. Three paths give you the same project-private reach, with different filesystem, tooling, and credential boundaries.
+
+- **Local + VPN.** Your laptop joins the private network via WireGuard. Editor, toolchain, and processes stay where they are. A hosted workspace is not required.
+- **Cloud IDE.** A Linux workspace in the project, accessed through VS Code Server in the dashboard. Zero local setup.
+- **Native IDE over SSH.** SSH from your local VS Code, JetBrains Gateway, Cursor, or plain `ssh` into a workspace or directly into a runtime service container.
+
+Switch paths without reprovisioning the project. A teammate on Local + VPN and another in the Cloud IDE are hitting the same `db:5432`.
+
+{` Laptop + editor Browser tab Laptop + native IDE
+ │ │ │
+ `}{`zcli vpn up`}{` `}{`VS Code Server`}{` `}{`zcli vpn up`}{`
+ (WireGuard) on the project + `}{`ssh apidev`}{`
+ │ │ │
+ └──────────────────────┴────────────────────────┘
+ │
+ ▼
+ ┌─────────── project private network ───────────┐
+ │ │
+ │ `}{`api:3000`}{` `}{`db:5432`}{` `}{`cache:6379`}{` │
+ │ │
+ └───────────────────────────────────────────────┘`}
+
+## Local + VPN
+
+**Best for:** keeping your existing editor, dotfiles, and toolchain — and offloading just the dependencies that are painful to run locally.
+
+```bash
+zcli vpn up
+
+psql "postgresql://app:secret@db:5432/myapp"
+redis-cli -h cache -p 6379
+ssh apidev
+```
+
+Your laptop can reach project services by hostname: Postgres, Valkey, S3-compatible storage, runtime containers, and any other service in the project. You can keep your normal dev loop and point it at `db:5432` instead of a local mock or Docker Compose dependency.
+
+You do not need a hosted workspace, `zcli push`, or a new editor for this path.
+
+**Source control.** Use git on your laptop the way you always have. Commits, pushes, SSH agent against GitHub, your existing credentials — nothing about Zerops sits between you and the remote.
+
+:::info Complete VPN setup
+See the [VPN reference guide](/references/networking/vpn).
+:::
+
+## Cloud IDE in Zerops
+
+**Best for:** zero local setup, working from a machine that isn't yours, or wanting a pristine environment that doesn't touch your laptop.
+
+A hosted workspace is a normal Zerops service in the project. It gives you a project-contained Linux environment with private-network access, optional Browser VS Code, `zcli`, git tooling, database CLIs, and shell utilities.
+
+The workspace can also mount runtime service files, so you can inspect or edit code that runs in another container without moving it to your laptop:
+
+```bash
+ls /var/www/apidev
+ls /var/www/frontenddev
+vim /var/www/apidev/src/server.ts
+```
+
+The dev server in the runtime container hot-reloads, the database is the same `db:5432`, and staging deploys still go through the Zerops deploy pipeline.
+
+The Cloud IDE itself is configurable. Two access methods:
+
+- **VPN Only.** The IDE is reachable through `zcli vpn up`, no public exposure. Most secure.
+- **Public Access.** The IDE is reachable on a `.zerops.app` subdomain, gated by an auto-generated password.
+
+**Source control.** The hosted workspace isn't on your laptop, so your local SSH keys don't follow it. Two patterns work:
+
+- **GitHub via `gh`.** The GitHub CLI is preinstalled. Run `gh auth login` once and `gh` handles HTTPS auth, PR creation, and review flows from the container.
+- **Token in env vars.** Save a fine-grained personal access token to the workspace service's secret environment variables; `git` reads it through a credential helper.
+
+Either pattern keeps your token in the workspace service, not in your project's source.
+
+## Native IDE over SSH
+
+**Best for:** native editor UX without carrying the toolchain or databases on your laptop.
+
+Once `zcli vpn up` is connected, every container on the project's private network is reachable from your laptop over SSH. Any editor that speaks Remote SSH can use it: VS Code Remote SSH, JetBrains Gateway, Cursor, Zed, or plain `vim`.
+
+```bash
+ssh apidev # any runtime service in the project
+ssh frontenddev
+```
+
+In this path, a hosted workspace is convenient but not required. You can connect straight to `apidev`, edit the source there, and run the dev server in the same container. A hosted workspace is only a convenience layer when you want shared tools, runtime file mounts, or Cloud IDE.
+
+**Source control.** SSH agent forwarding works the same way it does to any other machine. Add your local SSH key to your agent (`ssh-add`), and `git push` from inside `apidev` or the workspace service uses your laptop's GitHub key over the forwarded agent socket — no token storage required.
+
+```ssh-config
+# Local ~/.ssh/config
+Host apidev.zerops
+ HostName apidev
+ ForwardAgent yes
+```
+
+:::info SSH access details
+See the [SSH reference guide](/references/networking/ssh).
+:::
+
+## Picking a path
+
+| | Local + VPN | Cloud IDE | Native IDE over SSH |
+| --------------------- | ------------------ | -------------------------- | --------------------------------- |
+| Editor runs | Local | Browser | Local |
+| Toolchain | Local | Hosted workspace | Hosted workspace or service container |
+| Network entry | WireGuard VPN | Browser into the project | WireGuard VPN, then SSH |
+| Hosted workspace required | No | Yes | No (convenience) |
+| Git auth | Local credentials | `gh` or token in env | SSH agent forwarding |
+| Best for | Keeping your setup | Disposable environments | Native UX, lighter laptop |
+
+## Why this is not just a cloud IDE
+
+If you've used GitHub Codespaces or Gitpod, Cloud IDE looks similar: a Linux container in the cloud, accessed from a browser or local IDE. Two structural differences matter.
+
+**You don't have to be in the editor.** Codespaces and Gitpod are editor-first. Zerops is network-first. Cloud IDE is one way to reach the project's private network; `zcli vpn up` lets you skip the editor environment entirely and consume the project's managed services from your existing local setup. The hosted workspace itself is just another Zerops service — SSH in, install packages, run processes, configure it however you want.
+
+**Your dev environment runs the same platform as production.** On a CDE, your dev container is one platform and the deployment target is another — making "works on my machine" a fact of life. On Zerops, dev Postgres, queue, cache, or object storage is the same managed service type the app meets later in stage and prod, on the same private network, with the same `zerops.yaml`. Policy differs across environments; the platform underneath doesn't.
+
+## Where to start
+
+
diff --git a/apps/docs/content/guides/local-development.mdx b/apps/docs/content/guides/local-development.mdx
deleted file mode 100644
index d0f8d0292..000000000
--- a/apps/docs/content/guides/local-development.mdx
+++ /dev/null
@@ -1,131 +0,0 @@
----
-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."
----
-
-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.
-
----
-
-## Setup
-
-### Prerequisites
-- **zcli** installed: `npm i -g @zerops/zcli` or [docs.zerops.io/references/cli](https://docs.zerops.io/references/cli)
-- **VPN**: WireGuard (installed by zcli automatically on first `zcli vpn up`)
-- **Project-scoped token**: Create in Zerops GUI → Settings → Access Tokens → Custom access per project
-
-### Configuration
-```json
-// .mcp.json (in project root)
-{
- "mcpServers": {
- "zcp": {
- "command": "zcp",
- "env": { "ZCP_API_KEY": "" }
- }
- }
-}
-```
-
----
-
-## Workflow
-
-### 1. Connect to Zerops services
-```bash
-zcli vpn up
-```
-- All services accessible by hostname (e.g., `db`, `cache`)
-- One project at a time — switching disconnects the current
-- **Env vars NOT available via VPN** — use `.env` file instead
-
-### 2. Load credentials
-ZCP generates `.env` from `zerops_discover`:
-```
-db_host=db
-db_port=5432
-db_password=
-db_connectionString=postgresql://db:@db:5432/db
-```
-
-How to load:
-| Runtime | Method |
-|---------|--------|
-| Node.js 20+ | `node --env-file .env app.js` |
-| Next.js, Vite, Nuxt | Automatic (reads `.env`) |
-| PHP/Laravel | Automatic (reads `.env`) |
-| Python | `python-dotenv` or `django-environ` |
-| Go | `godotenv.Load()` or `source .env && go run .` |
-| Java/Spring | `spring-dotenv` or `application.properties` |
-
-### 3. Develop locally
-Start your dev server as usual — hot reload works against Zerops managed services over VPN.
-
-### 4. Deploy to Zerops
-```
-zerops_deploy targetService="appstage"
-```
-Uses `zcli push` under the hood. Blocks until build completes.
-
----
-
-## zerops.yml for Local Mode
-
-The same `zerops.yml` works for both local push and container deploy:
-
-```yaml
-zerops:
- - setup: appstage
- build:
- base: nodejs@22
- buildCommands:
- - npm ci
- - npm run build
- deployFiles: ./dist
- run:
- start: node dist/server.js
- ports:
- - port: 3000
- httpSupport: true
- envVariables:
- DB_URL: ${db_connectionString}
-```
-
-`${hostname_varName}` references are resolved by Zerops at container runtime — they work regardless of push source (local or container).
-
----
-
-## Connection Troubleshooting
-
-| Symptom | Diagnosis | Fix |
-|---------|-----------|-----|
-| `nc -zv db 5432` times out | VPN not connected | `zcli vpn up ` |
-| VPN connected, still timeout | Wrong project | `zcli vpn up ` |
-| Connected but auth fails | Stale .env | Regenerate from `zerops_discover includeEnvs=true` |
-| Service unreachable | Service stopped | `zerops_manage action="start" serviceHostname="db"` |
-
-### Diagnostic sequence
-1. `zerops_discover service="db"` — is service RUNNING?
-2. `nc -zv db 5432 -w 3` — network reachable?
-3. Compare `.env` vs `zerops_discover includeEnvs=true` — credentials current?
-
----
-
-## Multi-Project
-
-Each project directory has its own `.mcp.json` + `.zcp/state/`. VPN is one per machine — switch manually:
-```bash
-zcli vpn up # work on project A
-zcli vpn up # auto-disconnects A, connects B
-```
-
----
-
-## Gotchas
-
-1. **VPN = network only**: Env vars must come from `.env` file, not VPN connection
-2. **`.env` contains secrets**: Add to `.gitignore` immediately — never commit
-3. **Deploy = new container**: Local files on Zerops are lost on every deploy. Only `deployFiles` content persists
-4. **One VPN project at a time**: Connecting to project B disconnects project A
-5. **Object storage (S3)**: Uses HTTPS apiUrl — may work without VPN but not fully verified. Include VPN as fallback
-6. **zcli must be installed**: `zerops_deploy` requires zcli in PATH. Error message includes install link if missing
diff --git a/apps/docs/content/zcp/concept/how-it-works.mdx b/apps/docs/content/zcp/concept/how-it-works.mdx
new file mode 100644
index 000000000..c1124ff8d
--- /dev/null
+++ b/apps/docs/content/zcp/concept/how-it-works.mdx
@@ -0,0 +1,175 @@
+---
+title: 'How it works'
+description: 'The work loop: live state, runtime target, service setup, app work, verification, recovery, and delivery.'
+---
+
+The ZCP MCP setup gives a coding agent a **work loop** for Zerops app work. The agent reads live state, chooses the app runtime and dependencies, changes the app, deploys through Zerops, verifies real behavior, and returns proof or a blocker.
+
+The loop is carried by project-scoped Zerops operations, Zerops-specific knowledge, and instructions for what to inspect, what to change, when to ask, and what counts as done. You describe the product outcome; the agent uses the loop to make its decisions visible while it works.
+
+The source of truth is the real project: runtimes, managed services, env references, logs, events, and deploy results. A separate preview sandbox is not the source of truth.
+
+## The work loop
+
+```mermaid
+flowchart TD
+ intent["Product intent Build a task board for my team."]
+ state["Live state services, runtime layout, env vars, logs, events, saved work state"]
+ scope["Runtime target which app service changes"]
+ setup{"Missing or unsuitable services?"}
+ provision["Service setup use existing services or create missing runtimes/dependencies"]
+ appwork["App work code, zerops.yaml, env refs, migrations, seeds, framework config"]
+ deploy["Direct deploy through Zerops"]
+ reachability{"Runtime reachable? status, logs, HTTP probe"}
+ behavior{"Requested behavior works? endpoint, UI flow, worker result, persisted state"}
+ evidence["Evidence build logs, runtime logs, events, verify output"]
+ proof["Proof URL, endpoint result, UI state, or stored result"]
+ delivery["Delivery after proof keep direct deploy, push to git, or hand off"]
+ blocker["Blocker credential, decision, unsupported fit, repeated failure"]
+
+ intent --> state --> scope --> setup
+ setup -->|yes| provision --> appwork
+ setup -->|no| appwork
+ appwork --> deploy --> reachability
+ reachability -->|no, fixable| evidence --> appwork
+ reachability -->|yes| behavior
+ behavior -->|no, fixable| evidence
+ behavior -->|yes| proof --> delivery
+ setup -->|needs decision| blocker
+ reachability -->|needs human| blocker
+ behavior -->|needs human| blocker
+
+ classDef user fill:#f7fbff,stroke:#2d72d9,stroke-width:1.5px,color:#172033;
+ classDef zcpbox fill:#eef7f1,stroke:#32845a,stroke-width:1.5px,color:#172033;
+ classDef work fill:#fffaf0,stroke:#c47f17,stroke-width:1.5px,color:#172033;
+ classDef done fill:#f5f3ff,stroke:#7157d9,stroke-width:1.5px,color:#172033;
+ classDef stop fill:#fff1f2,stroke:#d33f49,stroke-width:1.5px,color:#172033;
+
+ class intent user;
+ class state,scope zcpbox;
+ class setup,provision,appwork,deploy,reachability,behavior,evidence work;
+ class proof,delivery done;
+ class blocker stop;
+```
+
+The loop keeps the agent working from evidence instead of a guessed checklist: current state, Zerops wiring rules, deploy evidence, and the distinction between proof and blocker.
+
+## What "live state" means
+
+The MCP tools read Zerops instead of asking you to paste a service inventory into the prompt. Useful state includes:
+
+- runtime services and managed services,
+- whether the app has one runtime, a dev+stage pair, or local files linked to a Zerops runtime,
+- env-var keys and Zerops references,
+- recent build/deploy events,
+- build logs, runtime logs, and verification output,
+- saved work state after an interrupted session.
+
+This is why a short prompt can be enough. The agent can ask what exists, which runtime was last deployed, which checks passed, and where a previous run stopped.
+
+Chat history is not the source of truth. If the agent sounds confused, starts from an old assumption, or a session was interrupted, the recovery move is:
+
+```text
+Read current project status and tell me where this project stands before changing anything.
+```
+
+## What the workflow handles
+
+The workflow handles the things an agent must resolve during app work so you do not have to name them in the prompt. The tools and instructions supply the state, guidance, operations, and verification surface so the agent can work from evidence.
+
+| What the workflow handles | What the agent gets | What that means for you |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Live state | Services, env-var keys, Zerops references, recent events, logs, verification output, and saved work state. | You do not have to paste a service inventory or reconstruct what happened. |
+| Runtime target | Rules for choosing the app runtime that should receive code changes. | The agent can identify where app work belongs before editing or deploying. |
+| Managed services | Knowledge and env wiring patterns for database, cache, queue, search, storage, mail, and similar services. | Product intent can imply real dependencies without a manual wiring checklist. |
+| Service setup | Operations for using existing services or creating missing runtimes and dependencies. | Runtime layout and dependencies can be established before app work starts. |
+| App wiring | Zerops-specific rules for `zerops.yaml`, env references, ports, commands, public access, and build/deploy behavior. | The app is wired for Zerops rather than for a generic cloud template. |
+| Deploy evidence | Build logs, runtime logs, platform events, service status, HTTP checks, and structured verification output. | A failed deploy becomes a diagnosis surface instead of guesswork. |
+| Behavior proof | The proof gate is the requested behavior, not only a successful build or reachable root URL. | The final answer can point to what was actually checked. |
+| Delivery handoff | Direct proof first; then git push, CI, or human handoff when that is the chosen delivery choice. | Shipping setup follows a verified running result. |
+
+The exact labels for layouts, delivery modes, and setup routes live in the [Glossary](/zcp/glossary) and [Workflows in depth](/zcp/reference/agent-workflow).
+
+## Service setup prepares the project layout
+
+Before app code work starts, the workflow makes three decisions visible:
+
+- Which runtime service is the app target?
+- Which managed services are dependencies?
+- Does the existing project layout fit the request?
+
+If the services already exist, the agent can use them. If a needed runtime or dependency is missing, the tools can create it. If the choice affects cost, product scope, credentials, a destructive action, or which stage/runtime should be used, the agent should stop and ask.
+
+Service setup is finished when the app runtime and dependencies are known. It is the layout that lets app work happen in the right place.
+
+## App work changes code and platform wiring together
+
+After the runtime target is known, the agent gets the platform knowledge needed to make the application change. In practice this often spans both source code and Zerops wiring:
+
+- app files,
+- `zerops.yaml` build and run setup,
+- env references to managed services,
+- migrations, seeds, and framework config,
+- start commands, ports, and public HTTP support,
+- local `.env` generation when using local setup.
+
+That guidance matters because Zerops is its own platform. Service references, build/deploy behavior, public access, scaling, and env resolution do not follow Docker Compose or Kubernetes conventions.
+
+The first functional deploy goes directly through MCP so the agent has a running result to verify. A repository push or CI handoff can follow, but it should not replace the first proof.
+
+## Recovery is evidence-driven
+
+When something fails, the workflow puts the agent on the matching evidence surface — build logs for build failures, prepare/runtime logs for start failures, verify output and request-time logs for behavior failures, transport surfaces for network failures, field-level rejection for config, and the named credential surface for credential failures. The full categories, what to read first, and what to avoid live in [Troubleshooting](/zcp/reference/troubleshooting).
+
+Retrying the same deploy without new evidence is not progress. The loop pushes toward one of three outcomes: fix from a cause, ask for the missing decision, or report a blocker with the category, evidence read, and attempts made.
+
+## Verification has two layers
+
+A successful deploy proves that Zerops accepted the build and started the runtime. Reachability checks prove the service is running and reachable. They still do not prove the product request.
+
+For a task-board app, useful behavior proof might be:
+
+- create a task,
+- move it between columns,
+- refresh the page,
+- confirm the task is still there.
+
+For an API task, proof might be a JSON response from the requested endpoint and stored data behind it. For a worker task, proof might be a processed job and the resulting database or object-storage state. For a staging request, proof belongs on the stage runtime, not only on dev.
+
+The final answer should make proof inspectable: runtime name, URL or endpoint, behavior checked, and delivery choice if one was set.
+
+## Delivery happens after proof
+
+Delivery choice controls how future changes ship after a verified runtime exists: keep direct deploy, push to git, or hand off to CI/release/human action. The user-facing version of this choice and what to tell the agent for each option lives in [Build and ship → Choose delivery after proof](/zcp/workflows/build-with-zcp#choose-delivery-after-proof).
+
+Packaging a running service turns a deployed runtime into a re-importable bundle for another Zerops project. It is useful for handoff or reuse after proof, not for deploying the next app change; see [Package a running service](/zcp/workflows/package-running-service).
+
+## Remote and local setup use the same loop
+
+The same `zcp` binary can run in two places. The control loop stays the same; filesystem and network access change. A human can take over from the same evidence either way: files, runtime target, logs, events, verification result, and delivery state.
+
+| Setup | What runs where | Practical effect |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Remote setup | A `zcp@1` service runs the `zcp` binary inside Zerops. **Include Coding Agent** adds the bundled agent CLI; **Cloud IDE** adds Browser VS Code. | Work happens inside the remote workspace, with private networking and runtime file mounts. |
+| Local setup | The `zcp` binary runs on your laptop after `zcp init`, and your local editor or CLI agent talks to it. | App files, deploy source, and git credentials stay local. Managed services are reached over Zerops VPN, and `.env` generation bridges credentials into your local app. |
+
+Choose setup by where the agent and filesystem should live: [Remote or local setup](/zcp/setup/choose-workspace).
+
+## Signs of a healthy run
+
+A well-shaped run should:
+
+- name the runtime target before editing or deploying,
+- use existing services when they fit,
+- create missing services only before app work starts,
+- read logs, events, and verify output when failure occurs,
+- distinguish runtime reachability from requested behavior,
+- stop before destructive actions, ambiguous runtime/stage choices, or missing credentials,
+- end with proof or a blocker.
+
+That is the practical difference between "the agent wrote code" and "the app task is done".
+
+## Next steps
+
+- [Build and ship](/zcp/workflows/build-with-zcp) — normal app work after setup.
+- [Workflows in depth](/zcp/reference/agent-workflow) — process gates, generated files, runtime layouts, delivery labels, and completion evidence.
diff --git a/apps/docs/content/zcp/glossary.mdx b/apps/docs/content/zcp/glossary.mdx
new file mode 100644
index 000000000..b9012bcdc
--- /dev/null
+++ b/apps/docs/content/zcp/glossary.mdx
@@ -0,0 +1,134 @@
+---
+title: 'Glossary'
+description: 'Short definitions for ZCP MCP, remote setup, local setup, workflow, delivery, production, and credential terms.'
+---
+
+Use these definitions when a page, workflow status, agent handoff, or policy needs exact wording. In normal prompts, describe the outcome you want.
+
+## Core names
+
+**ZCP MCP** - Zerops Control Plane MCP: the MCP tool surface that exposes project-scoped Zerops operations to coding agents.
+
+**MCP server** - the Model Context Protocol server exposed by the `zcp` binary.
+
+**ZCP MCP tools** - the project-scoped Zerops operations exposed to an agent or MCP-capable client. In MCP clients, this usually appears as the `zerops` server.
+
+**`zcp` binary** - the executable that can run inside remote setup or on your machine in local setup.
+
+**`zcp` service** - the service instance in a Zerops project that hosts remote setup.
+
+**`zcp@1` service** - the Zerops service type used for remote setup.
+
+**zCLI** - the Zerops command-line client for humans, scripts, VPN, and CI. It is separate from ZCP MCP.
+
+**zsc** - the in-container Zerops Setup Control utility used from `zerops.yaml`.
+
+## Setup and workspace
+
+**Remote setup** - the `zcp` binary running inside a Zerops `zcp@1` service.
+
+**Include Coding Agent** - remote setup option that adds the bundled agent CLI, currently Claude Code, and preconfigures it to use ZCP MCP tools.
+
+**Cloud IDE** - browser-based VS Code served by remote setup.
+
+**Browser VS Code** - dashboard entry point into the Cloud IDE.
+
+**AI Agent environment** - recipe environment preset that creates app services plus remote setup with **Include Coding Agent** enabled.
+
+**Local setup** - the `zcp` binary running on your machine after `zcp init`, while your local editor or CLI agent talks to it.
+
+**Env bridge** - local setup behavior that writes a local `.env` snapshot from Zerops env vars and references so local app code can reach managed services over VPN.
+
+**Agent client** - the editor, CLI, hosted agent runtime, or custom MCP client that connects to ZCP MCP.
+
+## Generated files and state
+
+**Generated workflow block** - the managed section in `CLAUDE.md` between `` and ``. Durable project instructions belong outside it.
+
+**`.mcp.json`** - local MCP server config. It points the local agent client at `zcp serve` and stores `ZCP_API_KEY`; keep it out of git.
+
+**`.zcp/state/`** - local workflow metadata for a project directory: known runtimes, pairing, delivery choice, sessions, deploy attempts, verify attempts, and coordination locks. It is not source code.
+
+**Workflow state** - saved metadata that lets the agent resume, audit, or close a guided run after interruption.
+
+## Workflow
+
+**Bootstrap** - workflow phase that reads the current project and settles which runtime services and managed services the app should use before app code work starts.
+
+**Service setup** - the phase that decides which runtime services and managed services the app should use before app code work starts.
+
+**Develop** - workflow phase that changes app code/config, deploys, verifies reachability and behavior, and fixes failures from evidence.
+
+**Runtime target** - the app runtime selected for the current change, such as `appdev`, `appstage`, `app`, or a linked local target.
+
+**Runtime layout** - which app runtime services the workflow should use:
+
+- `standard` - dev runtime plus explicit stage runtime.
+- `dev` - one mutable development runtime.
+- `simple` - one runtime with no dev/stage split.
+- `local-stage` - local source directory linked to one Zerops runtime as deploy target.
+- `local-only` - local source directory with no linked runtime yet.
+
+**Managed service** - database, cache, queue, search, storage, mail, or similar dependency. It provides connection details; it is not an app deploy target.
+
+**Direct deploy** - deploy from the current source to the scoped runtime through ZCP MCP. The first verified running result uses direct deploy before delivery setup is applied.
+
+**Reachability verification** - checks that the runtime exists, is running, has no recent blocking errors, and can answer an HTTP probe when it is an HTTP service.
+
+**Behavior verification** - checks that the requested app behavior works on the real URL, endpoint, worker result, or stored state.
+
+**Proof** - user-inspectable completion evidence, such as a URL, endpoint result, UI state, processed job, or stored result.
+
+**Blocker** - a clear stop state with evidence: failure category, runtime in scope, what was tried, and what decision or credential is needed.
+
+## Delivery and production
+
+**Delivery choice** - what happens after a verified deploy: keep direct deploy, push to git, or hand off to CI/release/human process.
+
+**Delivery mode** - exact reference label for delivery choice:
+
+- `auto` - keep direct deploy for future changes.
+- `git-push` - commit and push to a configured remote, then observe/verify any tracked build.
+- `manual` - external CI, release process, or a human owns future delivery.
+
+**Git-push capability** - whether remote setup has enough remote URL and credential setup to push from remote setup. It can exist even when the current delivery mode is `auto`.
+
+**Build integration** - repository-triggered build/deploy path that ZCP MCP may configure or observe, such as a Zerops dashboard webhook or GitHub Actions. It is separate from git-push capability and delivery mode.
+
+**Package a running service** - workflow that turns one verified runtime and its managed dependencies into a re-importable, git-backed Zerops bundle.
+
+**Production release** - the release operation that moves verified dev or stage work into a separate production Zerops project. It is set up once per project (production infrastructure) and once per runtime (production deploy trigger), then runs every release.
+
+**Production boundary** - policy that production should live in a separate Zerops project without a `zcp` service and receive promoted work through CI, release process, or human action.
+
+## Platform and failure terms
+
+**Service scaling mode** - Zerops scaling setting such as `HA` or `NON_HA`. Different from runtime layout.
+
+**Public subdomain access** - Zerops `.zerops.app` URL access for an eligible HTTP runtime. Workers and non-HTTP services do not get useful public URLs.
+
+**Failure category** - label that points to the first useful evidence surface:
+
+- `build` - build phase failed.
+- `start` - build passed, but runtime start or prepare failed.
+- `verify` - runtime exists, but reachability or behavior failed.
+- `network` - transport, DNS, VPN, SSH, or service-to-service reach failed.
+- `config` - `zerops.yaml`, env vars, setup block, or service settings mismatch.
+- `credential` - Zerops, git, SSH, managed-service, or external API credential failed.
+- `other` - no known category matched.
+
+**Confirmation gate** - an operation that pauses until the user explicitly confirms the named target or consequence.
+
+**Destructive import override** - import action that would replace an existing service stack. ZCP MCP refuses first, names affected services, and requires a matching acknowledgement before proceeding.
+
+## Credentials
+
+**Single-project token** - Zerops token that can access exactly one project. ZCP MCP expects this shape.
+
+**`ZCP_API_KEY`** - single-project Zerops token used by ZCP MCP.
+
+**`GIT_TOKEN`** - git provider credential used by remote git-push delivery when needed.
+
+**`ZEROPS_TOKEN`** - Zerops token commonly used by GitHub Actions or external CI that runs `zcli`.
+
+**External secret** - third-party credential such as Stripe, OpenAI, Mailgun, or GitHub API access. The agent can wire placeholders and env vars, but the secret value remains your responsibility.
diff --git a/apps/docs/content/zcp/overview.mdx b/apps/docs/content/zcp/overview.mdx
new file mode 100644
index 000000000..fbaf5ebe0
--- /dev/null
+++ b/apps/docs/content/zcp/overview.mdx
@@ -0,0 +1,152 @@
+---
+title: 'ZCP MCP for Zerops projects'
+description: 'How the ZCP MCP server lets a coding agent work with one real Zerops project.'
+---
+
+import Image from '/src/components/Image';
+
+:::info Public preview
+ZCP MCP is a public preview and is under active development. If you hit a bug, confusing behavior, or a missing workflow, please report it on Discord; feedback from real projects is especially useful.
+:::
+
+This section covers, in order:
+
+
+
+
+
+GET STARTED
+
+
Quickstart and concept
+
+[Quickstart](/zcp/quickstart) for hands-on; [How it works](/zcp/concept/how-it-works) for the work loop.
+
+
+
+
+
+SETUP
+
+
Remote or local workspace
+
+[Remote or local setup](/zcp/setup/choose-workspace), [Trust model](/zcp/security/trust-model), and [Production boundary](/zcp/security/production-policy).
+
+
+
+
+
+WORKFLOWS
+
+
Build, package, promote
+
+[Build and ship](/zcp/workflows/build-with-zcp), [Package a running service](/zcp/workflows/package-running-service), [Promote to production](/zcp/workflows/promote-to-production).
+
+
+
+For the broader feature concept — why coding agents need real project infrastructure rather than a sandbox or generated artifact — start with [Infrastructure for Coding Agents](/features/coding-agents).
+
+With the generated workflow instructions enabled, an app task ends in proof or a blocker. **Proof** is a deployed runtime plus the URL, endpoint response, UI state, worker result, or stored data that shows the requested behavior works. A **blocker** is the agent reading the relevant Zerops evidence and naming the missing credential, decision, unsupported fit, or repeated failure.
+
+Your prompt can stay about the product. Name the stack, runtime layout, acceptance criteria, delivery path, external credentials, or risky approval only when those decisions matter.
+
+## What the agent gets
+
+
+
+
+
+STATE
+
+### Current state
+
+Services, runtime layout, managed dependencies, env-var keys and references, logs, events, deploy history, verification state, and saved work state.
+
+
+
+
+
+CONTROLS
+
+### Zerops operations
+
+Project-scoped tools for discovering services, changing env vars, managing runtimes, deploying, verifying, scaling, public access, and delivery setup.
+
+
+
+
+
+INSTRUCTIONS
+
+### Workflow
+
+The generated instructions combine service setup and app development: inspect state, choose the runtime target, use or create services, wire code and `zerops.yaml`, deploy, verify, and choose delivery. The Zerops work stays behind the product task instead of becoming another checklist.
+
+
+
+
+
+EVIDENCE
+
+### Evidence-based completion
+
+A build or deploy is not the finish line. A completed app task should end with a working URL, endpoint result, UI proof, or a blocker backed by logs, events, and verification evidence.
+
+
+
+
+
+## What you no longer have to script
+
+Without this layer, an app prompt often turns into an operations runbook. With MCP tools and workflow instructions enabled, you should not need to paste:
+
+- the service map, runtime target, dev/stage state, or managed-service inventory,
+- database credentials, private hostnames, env-var references, or generated connection strings,
+- build logs, runtime logs, event timelines, or a guess about why the last deploy failed,
+- a deploy/verify/recovery script for every task,
+- a recap after the chat loses context; the agent can read current workflow status.
+
+**You still own the decisions that need human judgment:** product intent, technology constraints, acceptance criteria, external credentials, repository policy, and approval for destructive actions.
+
+## Where it runs
+
+The **same `zcp` binary** runs in both setups. In [remote setup](/zcp/setup/hosted-workspace), Zerops packages it as a `zcp@1` service with Browser VS Code and bundled agent wiring. In [local setup](/zcp/setup/local-agent-bridge), you install it on your machine and connect your own editor or CLI agent. The project surface is the same; the workspace, network access, deploy source, and safety profile differ.
+
+To start, add remote setup in Zerops or initialize local setup beside your editor or CLI agent. The [Quickstart](/zcp/quickstart) uses remote setup because it needs no local install.
+
+
+
+
+
+## Your agent, credentials, and workspace
+
+**Agent account.** Remote setup can include a bundled agent CLI, currently Claude Code, already configured for MCP. Zerops wires the agent to the tools; you still authenticate with your own subscription login or API credentials.
+
+**Zerops token.** The MCP server connects through `ZCP_API_KEY`, a Zerops token limited to one project. Remote setup gets it from the platform; local setup reads it from `.mcp.json`. Token details live in [Tokens and credentials](/zcp/security/tokens-and-project-access).
+
+**Workspace freedom.** The `zcp@1` service is still a normal Zerops service. You can install another agent CLI, add private MCP servers or helper tools, edit `CLAUDE.md`, add team dotfiles, and adapt the workspace. Details live in [What remote workspace gives you](/zcp/setup/hosted-workspace#make-customization-persistent).
+
+:::caution Production boundary
+Use this setup for development or staging work. Production should stay in a separate Zerops project and receive released work through your CI or release process; see [Promote to production](/zcp/workflows/promote-to-production) for the practical flow and [Production boundary](/zcp/security/production-policy) for the policy.
+:::
+
+## What stays outside
+
+This section is not a replacement for Zerops platform references. The Zerops [build and deploy pipeline](/features/pipeline), [permissions](/features/rbac), networking, scaling, and service references remain canonical for platform behavior.
diff --git a/apps/docs/content/zcp/quickstart.mdx b/apps/docs/content/zcp/quickstart.mdx
new file mode 100644
index 000000000..c41570832
--- /dev/null
+++ b/apps/docs/content/zcp/quickstart.mdx
@@ -0,0 +1,126 @@
+---
+title: 'Quickstart'
+description: 'Try ZCP with a ready-made AI Agent recipe, Browser VS Code, Claude Code, and one product change.'
+---
+
+import Image from '/src/components/Image';
+import Icons from '@theme/Icon';
+
+Use this when you want the fastest hands-on ZCP loop: deploy an **AI Agent** recipe, authorize Claude Code, open Browser VS Code, and ask for one product change.
+
+Some [Zerops recipes](https://app.zerops.io/recipes) include an **AI Agent** environment. That preset creates app services, managed services, the `zcp@1` workspace, Browser VS Code, and bundled agent wiring in one deploy.
+
+This quickstart uses [Laravel showcase](https://app.zerops.io/recipes/laravel-showcase?environment=ai-agent) because it includes real managed services. The same flow works for other recipes that offer AI Agent (local variants exist too).
+
+## Prerequisites
+
+- A Zerops account with permission to create a project.
+- A Claude Code subscription login or API authentication. Zerops wires Claude Code to ZCP, but your agent subscription or model credentials stay yours.
+
+## 1. Choose the AI Agent recipe
+
+1. Open the [Zerops recipes catalog](https://app.zerops.io/recipes).
+2. Open a recipe with an **AI Agent** environment. For example, open [Laravel showcase](https://app.zerops.io/recipes/laravel-showcase?environment=ai-agent).
+3. Select **AI Agent**.
+4. Keep **Coding Agent** and **Cloud IDE** enabled.
+5. Deploy the recipe.
+
+
+
+
+
+The deploy creates app runtimes, managed dependencies, and a `zcp@1` workspace. In this recipe it appears as the `zcp` service. The agent, terminal, and browser IDE run there. App code still deploys to the app runtimes, not to `zcp`.
+
+## 2. Authorize Claude Code
+
+When provisioning finishes, the dashboard opens the Claude Code authentication flow. Use your own Claude Code subscription login or API credentials.
+
+This is separate from `ZCP_API_KEY`, the Zerops token used by ZCP. Your Claude login or API key is used only by the bundled agent.
+
+If you close the prompt, open the `zcp` service in the dashboard. Its panel shows the browser workspace, web terminal, SSH access, desktop editor access, and agent authorization state.
+
+
+
+
+
+## 3. Open the workspace
+
+After authentication, continue into **Browser VS Code**. The workspace opens with files, ZCP configuration, terminal access, and the Claude Code panel.
+
+
+
+
+
+You are now inside the remote workspace. The agent can read live state, use the MCP tools, reach private services, and deploy app changes to the runtimes created by the recipe.
+
+## 4. Ask for a product outcome
+
+In Claude Code, ask for the app behavior in natural language. A good first prompt is intentionally short:
+
+```text
+Build a task board for my team.
+Tasks should stay saved after refresh.
+```
+
+The agent should deploy, verify, read evidence, and return proof for the app task. Add detail only when it changes the work.
+
+Add details when they change the product, stack, runtime layout, acceptance criteria, or delivery preference:
+
+```text
+In this Laravel app, add a task board backed by the existing PostgreSQL service.
+A user can create a task, refresh the page, and still see it.
+```
+
+:::note Prompt shape
+
+Quickstart prompts are short so you can see what ZCP carries behind the request. Longer, detailed prompts are fine for larger engineering work, especially when they change product behavior, stack, runtime layout, acceptance criteria, delivery preference, credentials, or safety approvals.
+:::
+
+## 5. Read the proof
+
+The final answer should give you a real URL, endpoint, UI state, stored result, or blocker. Open the URL and try the behavior the agent says it verified.
+
+For the task-board prompt, create a task, refresh the page, and confirm the task is still there. If it disappears, the app is not done; ask the agent to verify that exact behavior again and continue from current evidence rather than starting over.
+
+If the agent cannot finish, useful output names the blocker: missing credential, missing decision, unsupported runtime choice, or repeated failure it could not recover from.
+
+## Next steps
+
+
diff --git a/apps/docs/content/zcp/reference/agent-workflow.mdx b/apps/docs/content/zcp/reference/agent-workflow.mdx
new file mode 100644
index 000000000..e2ed76ebe
--- /dev/null
+++ b/apps/docs/content/zcp/reference/agent-workflow.mdx
@@ -0,0 +1,173 @@
+---
+title: 'Workflows in depth'
+description: 'The bootstrap and develop process behind generated-workflow ZCP MCP agent runs.'
+---
+
+Use this page when you want the process and exact labels behind a run that follows the generated workflow. Normal prompts should still describe outcomes. The workflow exists so the agent can read the project, prepare the right runtime and services, make the app change, deploy, verify, recover from evidence, and stop with proof or a concrete blocker.
+
+The useful mental split is:
+
+| Phase | What it settles | What should be true when it ends |
+| ----- | --------------- | -------------------------------- |
+| **Bootstrap** | Where the app should run and which services it depends on. | Runtime target and managed dependencies are known. |
+| **Develop** | Code, `zerops.yaml`, env wiring, deploy, verification, recovery, and delivery choice. | The requested behavior is proved, or the blocker is concrete. |
+
+For the loop itself, see [How it works](/zcp/concept/how-it-works). This page catalogs the exact phases, routes, layouts, labels, and gates.
+
+## Session layers
+
+Most workflow mistakes come from confusing these layers:
+
+| Layer | What it is | What changes here |
+| ----- | ---------- | ----------------- |
+| **Workspace** | Where `zcp` and the agent run: remote `zcp@1` service or local machine. | Agent config, tools, local workflow state. App code should not be deployed to the workspace itself. |
+| **Target runtime service** | The app runtime in scope: `appdev`, `appstage`, `app`, or a linked local deploy target. | App files, `zerops.yaml`, deploys, runtime logs, verification target. |
+| **Managed services** | Databases, caches, queues, search, storage, mail, and similar dependencies. | Schema/data operations and credentials, never app code deploys. |
+
+The `zcp` service is the control surface, not the app runtime.
+
+## What drives the workflow
+
+The generated workflow is made from four pieces:
+
+| Piece | Role |
+| ----- | ---- |
+| **MCP tools** | Project-scoped Zerops operations: discover, deploy, read logs/events, manage env vars, verify, import/export, and related actions. |
+| **Generated instructions** | Agent policy for when to inspect, when to ask, when to deploy, what evidence to read, and what counts as done. |
+| **Saved workflow state** | Local metadata about bootstrap sessions, runtime pairing, delivery choice, deploy attempts, verify attempts, and interrupted work. |
+| **Live Zerops project** | Source of truth for services, status, env refs, logs, events, deploys, runtime files, and public access. |
+
+The workflow does not replace judgment from the user or the agent. It gives the agent a process and evidence surface so app work does not depend on stale chat memory or a pasted runbook.
+
+## Bootstrap
+
+Bootstrap starts before app code changes when the workflow needs to understand or prepare the project layout.
+
+```mermaid
+flowchart TD
+ start(["Read live project state"])
+ interrupted{"Interrupted bootstrap to resume?"}
+ runtime{"Runtime services already exist?"}
+ known{"Request matches known recipe or stack?"}
+ resume(["resume"])
+ adopt(["adopt"])
+ recipe(["recipe"])
+ classic(["classic"])
+ done(["Runtime target and dependencies known"])
+
+ start --> interrupted
+ interrupted -- yes --> resume --> done
+ interrupted -- no --> runtime
+ runtime -- yes --> adopt --> done
+ runtime -- no --> known
+ known -- yes --> recipe --> done
+ known -- no --> classic --> done
+```
+
+| Route | Use when | Wrong signal |
+| ----- | -------- | ------------ |
+| `adopt` | Runtime services already exist, including recipe-created projects. | Recreating services that already fit, or targeting the `zcp` service as the app. |
+| `recipe` | The project is empty or only has remote setup, and the request matches a known stack recipe. | Treating an unchanged starter as the finished requested product. |
+| `classic` | The project is empty and needs a custom service plan. | Writing app code before service ownership and runtime target are known. |
+| `resume` | A previous bootstrap was interrupted. | Starting from scratch without checking live services and saved state. |
+
+Bootstrap ends when the app runtime target and managed dependencies are known. It should also make visible any choice that needs human judgment: cost, credentials, data, runtime layout, production risk, or destructive behavior.
+
+## Runtime layouts
+
+Runtime layout describes which app runtime services the workflow should use. Exact layout labels (`standard`, `dev`, `simple`, `local-stage`, `local-only`) and the runtime names they map to live in the [Glossary](/zcp/glossary#runtime-layout). The user-facing three (dev, dev + stage, stage / linked target) are in [Build and ship → Choose the runtime layout](/zcp/workflows/build-with-zcp#choose-the-runtime-layout). Service scaling mode (`HA`/`NON_HA`) is a separate service setting.
+
+In `standard`, stage is explicit. Work scoped to `appdev` does not silently touch `appstage`; a release or stage verification happens when the user asks for it.
+
+## Develop
+
+Develop is the main app-work loop. It begins after bootstrap has a runtime target and dependencies. It closes only when runtime reachability and requested behavior both pass, or when the agent has a blocker that needs a human decision. The loop itself is in [How it works → The work loop](/zcp/concept/how-it-works#the-work-loop). The labeled steps are:
+
+1. **Name runtime target.** State which runtime is in scope: `appdev`, `appstage`, `app`, or a linked local target.
+2. **Change code and config.** Edit app files, `zerops.yaml`, env references, migrations, seeds, framework config, or local `.env` bridge when needed.
+3. **Deploy directly first.** The first verified runtime deploy goes through MCP tools. Git or CI handoff comes after proof.
+4. **Start or restart if needed.** Dynamic dev runtimes may need an explicit start or restart after deploy. Built-in webserver runtimes do not need a separate dev-server step unless the framework requires one.
+5. **Verify runtime reachability.** Check service status, recent error logs, and HTTP readiness when the runtime is an HTTP service.
+6. **Verify requested behavior.** Check endpoint body, UI state, job result, persisted data, or another result tied to the user request.
+7. **Fix from evidence.** Read failure category, logs, events, and check output. Repeating the same deploy without new evidence is not progress.
+
+Reachability and requested behavior are separate gates. A green deploy with a broken route is not done.
+
+## Failure categories
+
+Failure categories (`build`, `start`, `verify`, `network`, `config`, `credential`, `other`) point the agent to the first useful evidence surface. The full read-first / avoid playbook is in [Troubleshooting → Evidence order](/zcp/reference/troubleshooting#evidence-order); the term definitions are in the [Glossary](/zcp/glossary#failure-category).
+
+Categorization is what turns retries into evidence-driven fixes.
+
+## Delivery after proof
+
+Delivery mode applies after a verified deploy. It does not replace the first proof.
+
+| Exact mode | User-facing choice | Meaning |
+| ---------- | ------------------ | ------- |
+| `auto` | Keep direct deploy | The agent keeps deploying future changes directly to the target runtime. |
+| `git-push` | Push to git | The agent commits and pushes to a configured remote; any resulting build still needs observation and verification. |
+| `manual` | External handoff | CI, release process, or a human owns future delivery; the workflow records evidence but does not initiate the next deploy. |
+
+Git-push capability, delivery mode, and build integration are separate. A project can have git-push configured while still using direct deploy for a given session.
+
+Packaging and production release are deliberate handoffs after proof. Packaging turns a verified runtime into a git-backed import bundle. A production release moves verified work into a separate production project through GUI setup, git/CI triggers, or the team's release process.
+
+## Generated files and state
+
+Remote setup and `zcp init` create configuration around the MCP server and workflow guidance.
+
+| File or directory | Created where | Purpose |
+| ----------------- | ------------- | ------- |
+| `CLAUDE.md` | Remote workspace or local project directory | Claude Code instruction surface. ZCP MCP writes a managed block between `` and ``. User content outside that block is preserved. |
+| `.claude/settings.local.json` | Remote workspace or local project directory | Claude Code per-project settings and ZCP MCP tool permissions for that directory. |
+| `.mcp.json` | Local project directory | Project-local MCP server config. It contains the local `zcp` command and the project-scoped `ZCP_API_KEY`; keep it out of git. |
+| `~/.claude.json` and SSH config | Remote setup | Workspace-level Claude Code and SSH wiring used inside the Zerops-hosted workspace. |
+| `.zcp/state/` | Working directory where the MCP server runs | Workflow state and service metadata for that project directory. |
+
+The managed `CLAUDE.md` block is refreshed by `zcp init` and by the MCP server when the block already exists. Put durable project instructions outside the ZCP markers. Edits inside the managed block are treated as generated content.
+
+`.zcp/state/` is not application source code and should not be committed. It stores metadata such as known runtime services, local/stage pairing, delivery preference, git-push setup, build integration, first-deploy stamps, workflow sessions, deploy attempts, verify attempts, and local coordination locks.
+
+ZCP MCP does not use `.zcp/state/` as a stale copy of the Zerops project. Service status, logs, events, runtime files, env-var values, and current platform configuration are read from Zerops or from the local filesystem when tools run. Local `.env` files are generated separately and may contain secrets.
+
+Do not edit `.zcp/state/` by hand during normal work. Use workflow operations to reset, resume, iterate, or reconfigure state. Deleting it intentionally discards local memory of services and delivery setup for that directory; the tools can rediscover live Zerops state, but delivery preferences and workflow history may need to be set again.
+
+## Completion evidence
+
+A completed app task should answer:
+
+- which bootstrap route was used when setup was needed,
+- which runtime target changed,
+- which managed services were used or created,
+- which deploy passed,
+- which reachability check passed,
+- which requested behavior passed,
+- which URL, endpoint, UI state, worker result, or stored value proves it,
+- which delivery choice applies next,
+- or which blocker remains and what evidence supports it.
+
+A clear blocker is acceptable completion only when it names the runtime in scope, failure category, evidence read, fixes tried, and human decision or credential still needed.
+
+## Confirmation gates
+
+Two operations pause because the loss is not safely reversible from inside the conversation: **service deletion** (named approval) and **destructive import override** (refuse-then-acknowledge). See [Tokens and credentials → What ZCP enforces for destructive actions](/zcp/security/tokens-and-project-access#what-zcp-enforces-for-destructive-actions) for the user-facing confirmation flow.
+
+## Auditing a workflow
+
+A workflow run is well-shaped if the evidence answers:
+
+| Question | Evidence |
+| -------- | -------- |
+| Where did bootstrap start? | Live service list, saved workflow state, and bootstrap route. |
+| Where did bootstrap end? | Runtime target, managed dependencies, and any human decisions. |
+| Which runtime was developed and deployed? | Runtime target, deploy result, events, and logs. |
+| What proved reachability? | Verify output, service status, public URL, or HTTP probe. |
+| What proved behavior? | Endpoint, UI flow, job result, database/object state, or other requested proof. |
+| What controls future delivery? | Delivery mode, git-push state, build integration, package bundle, or production release handoff note. |
+
+## Related reference
+
+- [ZCP MCP tools](/zcp/reference/mcp-operations) — operation names and direct tool calls.
+- [Troubleshooting](/zcp/reference/troubleshooting) — recovery order when a run gets stuck.
+- [Glossary](/zcp/glossary) — exact terms used across the ZCP MCP reference.
diff --git a/apps/docs/content/zcp/reference/index.mdx b/apps/docs/content/zcp/reference/index.mdx
new file mode 100644
index 000000000..e11240461
--- /dev/null
+++ b/apps/docs/content/zcp/reference/index.mdx
@@ -0,0 +1,83 @@
+---
+title: "Reference"
+description: "Process details, MCP tool names, recovery guidance, and glossary for ZCP MCP."
+---
+
+import Icons from '@theme/Icon';
+
+Reference pages exist for the moments when an exact label, tool name, or recovery step matters. For day-to-day app work, start in [Build and ship](/zcp/workflows/build-with-zcp); for the loop itself, [How it works](/zcp/concept/how-it-works).
+
+
+
+## Common scenarios
+
+
+
+
+
+SCENARIO
+
+### Debugging a stuck deploy
+
+[Troubleshooting → Evidence order](/zcp/reference/troubleshooting#evidence-order) names what to read first; [Workflows in depth → Failure categories](/zcp/reference/agent-workflow#failure-categories) maps the labels.
+
+
+
+
+
+SCENARIO
+
+### Building a custom MCP client
+
+[ZCP MCP tools](/zcp/reference/mcp-operations) for the tool surface; [Workflows in depth → What drives the workflow](/zcp/reference/agent-workflow#what-drives-the-workflow) for what the generated workflow adds on top of bare tools.
+
+
+
+
+
+SCENARIO
+
+### Auditing a finished run
+
+[Workflows in depth → Completion evidence](/zcp/reference/agent-workflow#completion-evidence) for what should be in the final answer; [Trust model → Audit evidence](/zcp/security/trust-model#audit-evidence) for what Zerops records platform-side.
+
+
+
+
diff --git a/apps/docs/content/zcp/reference/mcp-operations.mdx b/apps/docs/content/zcp/reference/mcp-operations.mdx
new file mode 100644
index 000000000..582b61ad5
--- /dev/null
+++ b/apps/docs/content/zcp/reference/mcp-operations.mdx
@@ -0,0 +1,103 @@
+---
+title: 'ZCP MCP tools'
+description: 'Use ZCP MCP as a direct MCP tool surface: what the tools do, what they do not decide, and which operations exist.'
+---
+
+Most app work should be phrased as an outcome: build this, fix that, deploy and prove it. Operation names matter when you configure agent-client policy, debug an MCP integration, build a custom client, or use ZCP MCP pragmatically as a set of project-scoped Zerops tools.
+
+ZCP MCP is the MCP server exposed by the `zcp` binary. Any MCP-capable client can connect to it and call tools such as `zerops_discover`, `zerops_logs`, `zerops_events`, `zerops_deploy`, or `zerops_verify`.
+
+## Tool-only use
+
+The MCP server exposes operations. It does not, by itself, decide the whole app lifecycle.
+
+Claude Code with the generated workflow uses its instructions to decide sequencing: inspect state before changing things, choose the runtime target, use existing services or create missing ones, deploy, read failure evidence, verify requested behavior, and stop with proof or a blocker.
+
+Tool-only use is valid when you want a custom MCP client, script, dashboard, policy-gated agent, or narrow operational task. In that setup, your integration owns the sequencing:
+
+- which project services are in scope,
+- when a deploy is allowed,
+- what counts as verification,
+- which logs or events should be read after failure,
+- when to ask a human,
+- when to stop.
+
+Tool-level gates still apply. Service deletion requires explicit named approval, and destructive import override requires an acknowledgement of the exact targets.
+
+If you use Claude Code but do not want the generated workflow guidance, keep the MCP connection and remove the ZCP-managed workflow block from `CLAUDE.md`, or keep your own policy outside the ZCP markers. What you lose is the generated instruction layer that makes the agent plan around live state, deploy with bounded retries, verify behavior, and report proof or a concrete blocker.
+
+Generated files and workflow state are documented in [Workflows in depth](/zcp/reference/agent-workflow#generated-files-and-state).
+
+## What the tools can do
+
+| Area | Tools | Typical use |
+| ---- | ----- | ----------- |
+| Discover | `zerops_discover` | Read services, service metadata, env-var keys, and project topology. |
+| Observe | `zerops_logs`, `zerops_events`, `zerops_verify`, `zerops_process` | Diagnose deploys, read runtime/build evidence, run health checks, and watch async processes. |
+| Deploy | `zerops_deploy` | Push source through Zerops build/deploy pipeline and return build/deploy evidence. |
+| Configure | `zerops_env`, `zerops_subdomain`, `zerops_scale`, `zerops_manage` | Change env vars, public subdomain access, scaling, lifecycle, reload/restart, and storage attachment. |
+| Import/export | `zerops_import`, `zerops_export`, `zerops_preprocess` | Import project/service YAML, read export YAML, and expand Zerops preprocessor expressions. |
+| Workspace | `zerops_mount` | Mount or unmount runtime filesystems in remote setup. |
+| Workflow | `zerops_workflow` | Track, recover, or configure workflow sessions and packaging/export flow. |
+| Destructive | `zerops_delete` | Delete one named service after explicit user approval. |
+
+Recipe-authoring and ZCP-internal maintenance operations are intentionally out of scope for this public reference.
+
+## Read-only operations
+
+| Operation | Purpose |
+| --------- | ------- |
+| `zerops_discover` | Read services, ports, env-var keys, and current state. |
+| `zerops_export` | Read platform project/service export YAML and service metadata. |
+| `zerops_logs` | Read runtime/build logs filtered by service, severity, time, or search. |
+| `zerops_events` | Read service activity, deploys, builds, scaling, and failures. |
+| `zerops_verify` | Run service health, recent error log, and HTTP-readiness checks. |
+| `zerops_knowledge` | Fetch ZCP MCP guidance or platform knowledge for the current state. |
+| `zerops_process` | Check a known async process; cancel is a mutating action. |
+
+## Mutating operations
+
+| Operation | Purpose |
+| --------- | ------- |
+| `zerops_deploy` | Ship code through the Zerops build and deploy pipeline. |
+| `zerops_env` | Read, set, delete, or generate env vars and local `.env` files. |
+| `zerops_manage` | Start, stop, restart, reload, or connect storage. |
+| `zerops_scale` | Change CPU, RAM, disk, CPU mode, or container autoscaling where supported. `HA`/`NON_HA` is set at service creation. |
+| `zerops_subdomain` | Enable or disable public subdomain access. |
+| `zerops_delete` | Delete a service. Explicit named approval is required. |
+
+## Operational setup
+
+| Operation | Purpose |
+| --------- | ------- |
+| `zerops_workflow` | Track, recover, or configure workflow sessions; also carries the package-running-service export flow. |
+| `zerops_import` | Import project/service definitions. Destructive override is gated. |
+| `zerops_mount` | Mount or unmount runtime filesystems in remote setup. |
+| `zerops_preprocess` | Expand Zerops preprocessor expressions. |
+
+## Remote and local tool differences
+
+The operation names are the same, but the filesystem and network boundary differ.
+
+| Area | Remote setup | Local setup |
+| ---- | ------------ | ----------- |
+| Files | Runtime files through SSHFS or remote containers. | Local working directory. |
+| Deploy source | Remote service or batch deploy inside Zerops. | Local `workingDir`. |
+| Dev server | Remote setup can run or inspect remote dev processes. | Your local tool owns the dev server. |
+| Env bridge | Env vars are already available in Zerops. | `.env` generation resolves Zerops references for local use. |
+| Git | Workspace-managed credentials. | User's local git credentials. |
+
+## Confirmation gates
+
+Two operations require explicit care:
+
+- **Service deletion** requires explicit user approval in the current conversation, by service name.
+- **Destructive import override** first refuses and names what would be replaced; a second call must acknowledge the same targets.
+
+See [Tokens and credentials](/zcp/security/tokens-and-project-access#what-zcp-enforces-for-destructive-actions) for the user-facing confirmation flow.
+
+## Related reference
+
+- [Workflows in depth](/zcp/reference/agent-workflow) - how a generated-workflow run uses these tools.
+- [Troubleshooting](/zcp/reference/troubleshooting) - evidence order when a run gets stuck.
+- [Tokens and credentials](/zcp/security/tokens-and-project-access) - token scope, storage, and confirmation gates.
diff --git a/apps/docs/content/zcp/reference/troubleshooting.mdx b/apps/docs/content/zcp/reference/troubleshooting.mdx
new file mode 100644
index 000000000..a575472fd
--- /dev/null
+++ b/apps/docs/content/zcp/reference/troubleshooting.mdx
@@ -0,0 +1,94 @@
+---
+title: 'Troubleshooting'
+description: 'A recovery playbook for stuck ZCP MCP sessions: status first, evidence order, local setup checks, and stop conditions.'
+---
+
+Use troubleshooting when the agent is confused, a session was interrupted, deploy keeps failing, verification does not match the final answer, or you are taking over manually.
+
+Start from current state, not chat memory:
+
+```text
+Read current project status and tell me where things stand before changing anything.
+```
+
+That should make the agent read live services, saved workflow state, recent deploys, logs, events, and verification output before it edits anything else.
+
+## Find where the run is stuck
+
+| Stuck point | Ask for | What you should get |
+| ----------- | ------- | ------------------- |
+| Agent lost context | Current project status and services in scope. | Runtime target, managed services, last deploy, last verify result, and any saved workflow state. |
+| Service setup is unclear | Runtime target and dependency plan. | Which existing services will be used, which missing services are needed, and what needs human approval. |
+| Deploy failed | Failure category plus build logs, runtime logs, and recent service events. | A cause or next diagnostic step, not another blind deploy. |
+| Runtime is reachable but app behavior fails | The failing behavior check and request-time runtime logs. | Endpoint/UI/job/data evidence tied to the product request. |
+| Local app cannot reach services | VPN state, generated `.env`, and selected runtime/setup. | Whether MCP auth works separately from private service access. |
+| Delivery is ambiguous | Delivery mode, git-push state, build integration, or handoff note. | What will happen after proof: direct deploy, git push, CI, package, or production handoff. |
+
+Useful prompt:
+
+```text
+Show me the runtime in scope, failure category, evidence read, fixes tried, and the next decision needed.
+```
+
+## Evidence order
+
+The useful evidence depends on the failure category surfaced by deploy or verify tools.
+
+| Category | Read first | Avoid |
+| -------- | ---------- | ----- |
+| `build` | Build logs, build commands, dependency manifests, deploy file list. | Runtime logs; the runtime did not start yet. |
+| `start` | Prepare/runtime logs, start command, ports, env references. | Rebuilding without checking why the process exited. |
+| `verify` | Failing check detail, HTTP response, request-time runtime logs, stored state. | Calling a green deploy "done" before behavior passes. |
+| `network` | VPN, SSH, DNS, subdomain readiness, service status, transport error. | Editing app code before proving connectivity. |
+| `config` | Field-level rejection, `zerops.yaml`, setup name, env references, service settings. | Guessing from service names or dashboard memory. |
+| `credential` | The named credential surface: `ZCP_API_KEY`, git, SSH, managed-service, CI, or external API. | Rotating unrelated secrets. |
+| `other` | Raw events/logs and the exact phase that failed. | Repeating the same attempt after the same unknown reason. |
+
+Failure categories come from the deploy/verify evidence surface. They are not a verdict; they tell the agent where the next useful signal is.
+
+## Local setup checks
+
+Local setup has two separate connections:
+
+- MCP uses `ZCP_API_KEY` to talk to the Zerops API.
+- Your local app and shell use `zcli vpn up` to reach private service hostnames such as `db` or `cache`.
+
+That means MCP can work while the app cannot reach the database.
+
+| Symptom | Check |
+| ------- | ----- |
+| Agent does not list the `zerops` MCP server. | Relaunch the agent from the directory containing `.mcp.json`. |
+| MCP startup says the token reaches multiple projects. | Replace `ZCP_API_KEY` with a single-project token. |
+| Re-running `zcp init` made MCP disappear. | Re-add the `ZCP_API_KEY` env block to `.mcp.json` and restart the agent. |
+| Local app cannot reach `db`, `cache`, or storage hostnames. | Run `zcli vpn up ` again. |
+| Local app reads stale credentials. | Regenerate `.env`; it is a snapshot, not a live sync. |
+| `zcp` is not found after install. | Add `~/.local/bin` or the install target to `PATH`, then restart the shell/agent. |
+
+For local setup details, use [Run locally](/zcp/setup/local-agent-bridge).
+
+## Manual takeover
+
+If you take over from the agent, read evidence in this order:
+
+1. Service list and runtime target.
+2. Service-scoped events for the runtime in question.
+3. Build logs for build failures, runtime logs for start or request failures.
+4. Verify output for reachability and requested behavior.
+5. Git history only when delivery uses git-push or CI.
+
+Do not inspect every service first. Start with the runtime in scope and expand only when the evidence points to a dependency.
+
+## When to stop
+
+Stop the loop when:
+
+- the same failure repeats without new evidence,
+- the agent needs an external credential,
+- the target runtime or stage choice is ambiguous,
+- a destructive action would delete or replace a service,
+- production release authority is needed,
+- the request no longer fits the current project layout.
+
+A blocker is acceptable only when it names the runtime in scope, failure category, evidence read, fixes attempted, and the human decision or credential still needed.
+
+Before destructive recovery, read service-scoped events, logs, deploy/verify result, and git history when delivery uses git-push. Token scope and destructive confirmations are covered in [Tokens and credentials](/zcp/security/tokens-and-project-access).
diff --git a/apps/docs/content/zcp/security/production-policy.mdx b/apps/docs/content/zcp/security/production-policy.mdx
new file mode 100644
index 000000000..202716c20
--- /dev/null
+++ b/apps/docs/content/zcp/security/production-policy.mdx
@@ -0,0 +1,93 @@
+---
+title: 'Production boundary'
+description: 'Keep ZCP in development or staging. Promote verified work to production through CI, release tooling, or a deliberate human action.'
+---
+
+Use the MCP setup in development or staging. Keep production in a separate Zerops project without a `zcp` service. Production deploys should come from CI, a release pipeline, or a deliberate human `zcli` push using production credentials.
+
+Zerops does not prevent you from adding `zcp` to production. The policy exists because ZCP MCP gives a coding agent operational access. In production, that is the wrong blast radius for normal app development.
+
+The production boundary does not make ZCP output disposable. The intended path is production-shaped dev or stage infrastructure, verified behavior, and then a controlled production release outside the agent loop.
+
+## Recommended project layout
+
+| Project | Contains | Who operates it |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| Development / staging project | `zcp` service, agent workspace, dev runtime, optional stage runtime, non-production managed services | Agent plus humans |
+| Production project | Production runtimes, production managed services, production env values, production backups and scaling | CI/release process plus humans |
+
+The two projects use different Zerops tokens. A development token cannot reach production. A production token should not be placed in the development `zcp` service or a local `.mcp.json` used by the agent.
+
+## Why production is a separate project
+
+- **The Zerops project is the security boundary.** ZCP binds to one project at startup. Keeping production separate prevents a development agent from touching it by accident.
+- **Secrets stay clean.** Production env values, database credentials, object-storage keys, and third-party secrets stay in the production project.
+- **Operational policies can differ.** Production often needs HA services, stronger backup retention, stricter scaling, alerts, and release approvals. Development can stay cheaper and more flexible.
+- **Audit trails stay readable.** Development experiments and agent retries do not mix with production deploy evidence.
+
+This separation matters even when the same source repository deploys to both projects.
+
+## What stage proves
+
+Stage is the production-like rehearsal inside development or staging. It is where the agent proves the change before the release leaves the ZCP loop.
+
+Use stage to match production where it matters:
+
+- same runtime family and version,
+- same managed service types,
+- same build and start command pattern,
+- same deploy route,
+- behavior checks against a real running service.
+
+Stage is not production. It should use non-production data and non-production secrets. A green stage means the change is ready for release, not that the agent should deploy to production itself.
+
+## The release
+
+After stage verifies, ZCP's job is done for that change. The production release happens outside the agent loop:
+
+- CI deploys a merged commit or release tag to the production project.
+- A release pipeline runs `zcli push` with a production-scoped `ZEROPS_TOKEN`.
+- A human runs `zcli push` against the production project with production credentials.
+
+The agent can prepare the handoff by pushing code, summarizing verification evidence, and naming the runtime and URL it verified. It should not bridge development to production.
+
+For the practical workflow, see [Promote to production](/zcp/workflows/promote-to-production).
+
+## Credential rules
+
+| Credential | Production policy |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Development `ZCP_API_KEY` | Never grants production access. Keep it scoped to the development/staging project. |
+| Production `ZEROPS_TOKEN` | Store only in the production CI/release secret store. Do not place it in the development `zcp` service. |
+| Agent subscription or model API key | May be used by the agent, but it does not grant Zerops production access by itself. |
+| Git credentials | May push source changes, but production deploy authority should stay with the release process. |
+
+If a production deploy fails, investigate in the production project with production logs, events, backups, and CI output. Do not attach the development agent directly to production as a shortcut.
+
+## Production separation rules
+
+| Rule | Why it matters |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| Keep the production project without a `zcp` service | Production should not host an agent workspace with operational access. |
+| Keep production tokens out of local `.mcp.json` | Local agents should operate development or staging projects, not production. |
+| Keep production `ZEROPS_TOKEN` in the release secret store | Development tooling should not deploy to production outside the release process. |
+| Treat stage proof as release evidence, not production approval | Stage is the rehearsal; production approval is a separate release decision. |
+| Promote through CI, release tooling, or a deliberate human action | Production execution should use production credentials. |
+
+## Acceptable agent involvement
+
+The agent can still help before the production release:
+
+- make the code change in development,
+- deploy and verify dev/stage runtimes,
+- produce the URL, endpoint result, or UI proof it verified,
+- push or prepare the branch your team uses for review,
+- summarize release notes and known blockers for the human or CI handoff.
+
+ZCP's involvement stops at the handoff. Production execution belongs to the release process.
+
+## Related security
+
+- [Promote to production](/zcp/workflows/promote-to-production) - practical production release paths after ZCP proof.
+- [Trust model](/zcp/security/trust-model) - the boundary that makes this policy enforceable.
+- [Tokens and credentials](/zcp/security/tokens-and-project-access) - production and development credentials stay separate.
diff --git a/apps/docs/content/zcp/security/tokens-and-project-access.mdx b/apps/docs/content/zcp/security/tokens-and-project-access.mdx
new file mode 100644
index 000000000..266dd630e
--- /dev/null
+++ b/apps/docs/content/zcp/security/tokens-and-project-access.mdx
@@ -0,0 +1,162 @@
+---
+title: 'Tokens and credentials'
+description: 'ZCP_API_KEY, agent credentials, git credentials, CI tokens, and destructive-action confirmations.'
+---
+
+ZCP uses a Zerops API token to operate exactly one project. The important rule is simple: `ZCP_API_KEY` is the Zerops credential for ZCP, not an agent login, not a git token, and not a general account token.
+
+Remote setup gets `ZCP_API_KEY` from Zerops. Local setup reads it from `.mcp.json`. In both setups, ZCP validates the token at startup and refuses tokens that resolve to no project or multiple projects.
+
+## Credential map
+
+| Name | What it authorizes | Where it belongs |
+| ---------------------------- | -------------------------------------------- | --------------------------------------------------------------------------- |
+| `ZCP_API_KEY` | ZCP against one Zerops project | Remote: `zcp` service env injected by Zerops. Local: `.mcp.json` env block. |
+| Agent login or model API key | The coding agent itself | The bundled agent in remote setup, or your local agent client. |
+| `GIT_TOKEN` | Git push from remote setup to a git provider | Secret env var on the `zcp` service when remote git-push delivery needs it. |
+| `ZEROPS_TOKEN` | `zcli` in GitHub Actions or external CI | Separate Zerops delivery token stored in the CI/release secret store. |
+
+Keeping these names separate prevents most setup and delivery failures.
+
+## Recommended `ZCP_API_KEY` shape
+
+Use a Zerops API token with **Custom access per project**, exactly one selected project, and **Full access** for normal agent work.
+
+Read-only tokens can authenticate, but they fail as soon as the agent needs to deploy, write env vars, restart services, scale, or change public access. Account-wide or multi-project tokens are refused before the agent can operate.
+
+To generate the token:
+
+1. Open [Settings -> Access Tokens Management](https://app.zerops.io/settings/token-management).
+2. Create a token and name it for the project, for example `zcp-`.
+3. Choose **Custom access per project**.
+4. Add exactly one project.
+5. Set that project to **Full access** for normal ZCP MCP work.
+6. Create the token and copy the value. Zerops shows it only at creation time.
+
+The token's blast radius equals the project and its granted permissions. Other projects, organization settings, and billing stay out of reach. Zerops [Roles & Permissions](/features/rbac#integration-tokens) remain the platform authority.
+
+## Rejected token shapes
+
+ZCP validates token shape at startup.
+
+| Token shape | What happens | Fix |
+| ----------------------------------- | ------------------------------------------- | -------------------------------------------------------------------- |
+| Account-wide or multi-project token | ZCP refuses to start. | Generate a token scoped to exactly one project. |
+| Token with no project access | ZCP refuses to start. | Grant one project or create a new single-project token. |
+| Expired or revoked token | ZCP refuses to start or receives HTTP 401. | Replace the token and restart the agent or ZCP process. |
+| Read-only project token | Startup may pass, but mutations fail later. | Use full access for normal agent work, or expect read-only behavior. |
+
+Common messages:
+
+| Message | Meaning |
+| -------------------------------------------------------------- | ------------------------------------------------- |
+| `Token accesses N projects; use project-scoped token` | The token can see more than one project. |
+| `Token has no project access` | The token authenticates but reaches no project. |
+| `No authentication found: set ZCP_API_KEY or log in with zcli` | The `zcp` process did not receive a usable token. |
+| `AUTH_TOKEN_EXPIRED` or HTTP 401 | The token expired, was revoked, or is invalid. |
+
+For ZCP MCP setup, provide `ZCP_API_KEY`. `zcli` login is a diagnostic fallback, not the normal agent setup.
+
+## Where the token lives - remote vs local {#where-the-token-lives--remote-vs-local}
+
+ZCP reads `ZCP_API_KEY` from its process environment at startup. It does not write the token somewhere else or exchange it for a derived credential.
+
+| Setup | Where `ZCP_API_KEY` comes from | Who provisions it |
+| -------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------- |
+| [Remote setup](/zcp/setup/hosted-workspace) | The `zcp` service environment | Zerops injects it automatically when the service starts. |
+| [Local setup](/zcp/setup/local-agent-bridge) | The `env` block of `.mcp.json` in the app directory | You add it after `zcp init`. |
+
+In remote setup, do not hand-edit `ZCP_API_KEY`. Replace or rotate it through the Zerops-managed surface so the service keeps the intended project boundary.
+
+In local setup, `zcp init` writes a token-less `.mcp.json`. Add the token manually:
+
+```json
+{
+ "mcpServers": {
+ "zerops": {
+ "command": "zcp",
+ "args": ["serve"],
+ "env": {
+ "ZCP_API_KEY": ""
+ }
+ }
+ }
+}
+```
+
+Add `.mcp.json` to `.gitignore`. Each app directory should have its own file and token. Switching projects means switching directories, not editing one shared credential.
+
+## Agent credentials are separate
+
+The bundled agent in remote setup may ask you to sign in or provide a model API key. That is not `ZCP_API_KEY`.
+
+Zerops wires the agent to ZCP. It does not provide your model subscription, store your agent login, or rotate your agent provider credentials. Treat the agent account exactly as you would outside Zerops.
+
+## Git and CI credentials
+
+`GIT_TOKEN` matters only when remote setup pushes to a git remote. It authorizes git provider access from the `zcp` service. In local setup, your local git CLI uses your normal SSH key or credential helper, so ZCP does not need `GIT_TOKEN`.
+
+`ZEROPS_TOKEN` is a Zerops API token used by GitHub Actions or another CI system when that system runs `zcli` against Zerops. It is not a GitHub token. Use a separate delivery token so ZCP sessions and CI/release workflows can be named, rotated, and audited independently.
+
+For production delivery, `ZEROPS_TOKEN` should reach production only and live only in the production CI or release secret store.
+
+With GitHub CLI, the secret shape is:
+
+```bash
+gh secret set ZEROPS_TOKEN -b "$ZEROPS_DELIVERY_TOKEN"
+```
+
+Use the GitHub UI or your CI secret manager instead if your team does not allow local CLI secret writes.
+
+## Rotation
+
+Rotate in the Zerops dashboard, then update the surface that consumes the token.
+
+| Surface | Rotation step |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Remote `ZCP_API_KEY` | Reconfigure or redeploy the remote workspace through the dashboard-managed flow, then restart the `zcp` service so the process gets the new value. |
+| Local `ZCP_API_KEY` | Paste the new token into `.mcp.json`, then restart the local agent client. |
+| `ZEROPS_TOKEN` in CI | Replace the repository or CI secret. The next workflow run uses the new value. |
+| `GIT_TOKEN` | Replace the git-provider credential stored for remote setup. |
+
+Rotation is picked up on the next process start or CI run, not in the middle of a live agent session.
+
+## What ZCP enforces for destructive actions
+
+A valid token does not remove every guardrail. ZCP MCP adds explicit confirmation for operations where the loss is not safely reversible from inside the conversation.
+
+| Operation | Gate |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Service deletion | Requires explicit approval in the same conversation, including the service name. Remote setup also blocks deleting the `zcp` service it is running in. |
+| Wholesale service replacement after failed deploy history | The first request refuses, surfaces what would be replaced, and requires the agent to read failure evidence before asking you to confirm. |
+
+Deploys, env changes, lifecycle actions, restarts, scaling, and public-access changes do not get an additional ZCP-specific confirmation gate. They are normal operations for a full-access token and should be reviewed through service events, logs, verification output, and team policy.
+
+Approval from a previous chat does not carry forward. A new conversation needs a new approval.
+
+## Evidence before destructive recovery
+
+When a service has recent failure history, ZCP enforces one recovery rule: read the platform evidence before destroying or replacing the service.
+
+The agent should inspect service events, build logs, runtime logs, and failure summaries, then either fix the cause or show you the evidence before asking for destructive confirmation. The point is to preserve the failure context the next session needs.
+
+A service waiting for first code deploy is not the same thing as a failed service. The gate is about recorded failure history, not idle state.
+
+Threat model and boundaries: [Trust model](/zcp/security/trust-model).
+
+## Credential checks
+
+- **Account-wide full-access tokens are refused.** ZCP needs one project, not a broad account credential.
+- **`zcp init` regenerates `.mcp.json`.** Re-add `ZCP_API_KEY` after rerunning it.
+- **`GIT_TOKEN` is not `ZCP_API_KEY`.** One authorizes git provider access; the other authorizes Zerops operations.
+- **`ZEROPS_TOKEN` in GitHub Actions is not a GitHub PAT.** It is a Zerops API token for `zcli`.
+- **A rotated token needs a restart.** The live ZCP process keeps the old environment value until it starts again.
+- **A successful confirmation is still destructive.** Backups, git history, and service events are your recovery evidence; ZCP does not auto-rollback a confirmed deletion or replacement.
+
+## Related pages
+
+- [Trust model](/zcp/security/trust-model) - the access boundary this page enforces.
+- [What remote workspace gives you](/zcp/setup/hosted-workspace) - automatic token injection.
+- [Run locally](/zcp/setup/local-agent-bridge) - local `.mcp.json` token setup.
+- [Production boundary](/zcp/security/production-policy) - why production gets separate credentials.
+- [GitHub integration](/references/github-integration) - CI secret usage with Zerops.
diff --git a/apps/docs/content/zcp/security/trust-model.mdx b/apps/docs/content/zcp/security/trust-model.mdx
new file mode 100644
index 000000000..f7fc945f8
--- /dev/null
+++ b/apps/docs/content/zcp/security/trust-model.mdx
@@ -0,0 +1,110 @@
+---
+title: 'Trust model'
+description: 'How MCP access is limited, and how remote and local setup change the surrounding blast radius.'
+---
+
+The trust model starts with one rule: one ZCP process operates one Zerops project. `ZCP_API_KEY` decides that boundary at startup, and ZCP refuses tokens that resolve to no project or multiple projects.
+
+That boundary is strong on the Zerops side. It does not make the agent harmless. A valid token can still deploy, change env vars, restart services, read logs, scale services, and change public access when Zerops permissions allow it. Treat it like an operations credential.
+
+## Boundary summary
+
+| Question | Answer |
+| ------------------------------------ | ------------------------------------------------------------------------------------------- |
+| What project can ZCP see? | Exactly one project resolved from `ZCP_API_KEY` at startup. |
+| What can ZCP change? | Whatever Zerops RBAC grants that token inside the project. |
+| What is outside reach? | Other projects, organization-wide settings, billing, and any operation Zerops RBAC rejects. |
+| What network can remote setup reach? | Private services from inside the `zcp` service. |
+| What network can local setup reach? | The Zerops API directly, plus private services only when your laptop VPN is up. |
+| Who owns the agent login? | You. The agent subscription or model API key is separate from `ZCP_API_KEY`. |
+
+Zerops [RBAC](/features/rbac) remains the authority. ZCP does not bypass platform permissions; it exposes project operations to the agent only through the token it was given.
+
+## Remote and local blast radius
+
+Remote setup and local setup share the same Zerops boundary, but not the same surroundings.
+
+| Area | Remote setup | Local setup |
+| -------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Agent location | Inside the `zcp@1` service when **Include Coding Agent** is enabled | On your machine through your editor or CLI agent |
+| Files visible to the agent | Workspace files and mounted runtime files | Local files and anything your client permits |
+| Private service access | Private network without laptop VPN | `zcli vpn up ` from your machine |
+| Local machine exposure | No direct access to your laptop | Agent client runs as your local user |
+| Best safety posture | Keep ZCP in a development/staging project and avoid mounting unrelated files | Restrict client permissions, shell access, and filesystem scope |
+
+Remote setup is contained inside Zerops by design. Local setup is supervise-the-client by design. Either can be right, but local setup requires more attention to your agent client's local permissions.
+
+## Credential ownership
+
+There are three separate credential surfaces people often mix together:
+
+| Credential | Owner | Purpose |
+| ----------------------------------- | ---------------------------- | ------------------------------------------------------ |
+| `ZCP_API_KEY` | Zerops token | Lets ZCP operate one Zerops project. |
+| Agent subscription or model API key | You / the agent provider | Lets the coding agent run. Zerops does not provide it. |
+| Git or CI credentials | You / your repository system | Lets finished work push to git or deploy through CI. |
+
+In both setups, the agent account is still authenticated through the agent's own login flow. For where each credential lives (remote injection vs `.mcp.json`), rotation, rejected token shapes, and `GIT_TOKEN` / `ZEROPS_TOKEN`, see [Tokens and credentials](/zcp/security/tokens-and-project-access).
+
+## What the token lets the agent do
+
+The agent can perform normal operational work when the token has permission:
+
+- discover runtime and managed services,
+- create or adjust services when the task requires it,
+- read and write service env vars,
+- deploy app code to runtime services,
+- read build logs, runtime logs, and service events,
+- restart, reload, stop, start, or scale services,
+- enable or disable public access,
+- prepare delivery such as git push or CI handoff.
+
+This is why development and staging projects are the right place for ZCP. Production should be a separate project without a `zcp` service; see [Production boundary](/zcp/security/production-policy).
+
+## Remote setup specifics
+
+- **`zcp` service is not the app.** It is the workspace and control surface. Deploys target app runtimes, not the `zcp` service.
+- **The service has operational reach.** A terminal in the `zcp` service can use the same ZCP access as the agent. Review the dashboard's additional changes before deploying the service; they are what give the workspace its operating surface.
+- **Network reach is broader than file reach.** The workspace can reach private services, but it only sees runtime files that are mounted into it.
+- **Do not hand-edit `ZCP_API_KEY`.** Remote setup gets the value from Zerops. Manual replacement can break the intended one-project boundary.
+
+## Local setup specifics
+
+- **The agent inherits local reach.** ZCP MCP is limited to one project, but the local agent client can read files, run commands, and use credentials allowed by your client settings.
+- **Each local directory has its own config.** `.mcp.json` and `.zcp/state/` belong to one app directory. Launching from the wrong directory can connect the wrong token or no token.
+- **VPN is outside MCP authority.** Bringing up Zerops VPN needs your operating-system approval. The tools cannot grant that for the agent.
+- **`.env` files are snapshots.** They contain real project credentials and should stay out of git.
+
+## Human confirmation gates
+
+Most project operations do not get an extra ZCP-specific confirmation prompt. Deploys, env changes, restarts, scaling, and public-access changes are normal project operations and are audited through platform evidence.
+
+ZCP MCP adds hard gates where the loss is not safely reversible from the conversation: **service deletion** (explicit same-conversation approval by service name; remote setup also blocks deleting the `zcp` service it is running in) and **wholesale service replacement after failed deploy history** (refuse-then-acknowledge with failure evidence first). Approval from an old chat does not carry forward. The full enforcement rules are in [Tokens and credentials → What ZCP enforces for destructive actions](/zcp/security/tokens-and-project-access#what-zcp-enforces-for-destructive-actions).
+
+## Audit evidence
+
+Zerops records platform-side evidence. It does not record the agent's private reasoning, every shell edit, browser-helper action, or prompt history outside your agent client.
+
+When taking over from an agent, read evidence in this order:
+
+1. service-scoped events,
+2. build logs,
+3. runtime logs,
+4. deploy and verification output,
+5. git history when delivery uses git-push.
+
+| Surface | What it proves | What it does not prove |
+| -------------- | ------------------------------------------------------------------------- | -------------------------------------------- |
+| Service events | Deploy lifecycle, failures, restarts, scaling, and public-access changes. | The exact source edit that caused the event. |
+| Build logs | Dependency install, build commands, compile/package failures. | Runtime request behavior after deploy. |
+| Runtime logs | Start crashes, port binding, request-time app errors. | Why the build failed. |
+| Verify output | Whether reachability and requested behavior passed. | That unrelated app flows work. |
+| Git history | Source changes pushed during git-push delivery. | Uncommitted shell edits. |
+
+Filter by service hostname when possible. Project-level timelines can include unrelated services and older failures.
+
+## Related security
+
+- [Tokens and credentials](/zcp/security/tokens-and-project-access) - token scope, storage, rotation, and confirmation gates.
+- [Remote or local setup](/zcp/setup/choose-workspace) - compare blast radius before setup.
+- [Production boundary](/zcp/security/production-policy) - keep production outside the agent loop.
diff --git a/apps/docs/content/zcp/setup/choose-workspace.mdx b/apps/docs/content/zcp/setup/choose-workspace.mdx
new file mode 100644
index 000000000..143bb9ccf
--- /dev/null
+++ b/apps/docs/content/zcp/setup/choose-workspace.mdx
@@ -0,0 +1,73 @@
+---
+title: 'Remote or local setup'
+description: 'Where the zcp binary and agent workspace run: inside Zerops or on your machine.'
+---
+
+Use this page to decide where the agent workspace lives: inside Zerops, or on your machine beside the local app directory.
+
+Both setups connect the agent to one Zerops project and the same project-scoped operations. The tradeoff is where the agent works: filesystem ownership, private-service access, credential location, bundled tooling, and shell blast radius. The runtime layout is a separate app-work decision.
+
+## What you are choosing
+
+**Remote setup** always includes the `zcp@1` workspace service. If the chosen **runtime layout** has a development runtime, the agent works with that service too.
+
+**Local setup** does not need the workspace service or a separate development runtime. It runs beside your **local source tree** and deploys to the Zerops runtime you choose to link.
+
+Remote setup is the **safer default** for broader agent autonomy because the agent shell, private networking, and workspace files stay **inside Zerops** instead of on your machine. Use local setup when local files, data, desktop tools, git credentials, or a **local-only agent client** need to stay local.
+
+## Setup comparison
+
+| | Remote setup | Local setup |
+| ----------------------- | ------------------------------------------------- | -------------------------------------------- |
+| Workspace service | Always has `zcp@1`. | Not required. |
+| Development runtime | Only if the runtime layout includes one. | Not required for local work. |
+| `zcp` process | Runs in Zerops. | Runs on your machine. |
+| Agent process | Runs in the remote workspace. | Runs in your local editor or CLI. |
+| Files the agent edits | Workspace files and mounted runtime files. | Files on your machine. |
+| Private service access | Private Zerops network from the workspace. | Zerops VPN from your machine. |
+| Token storage | Injected into the workspace service. | `.mcp.json` in the local app directory. |
+| Git credentials | Configured inside the workspace service. | Your local git credentials. |
+| Safety posture | Broad agent shell permissions stay in Zerops. | Agent shell permissions affect your machine. |
+
+## Starting points
+
+Remote setup can start from:
+
+- **Recipe with AI Agent environment.** A guided path for a known stack. A recipe creates app services, managed services, and the `zcp@1` workspace together.
+- **New Zerops setup with remote setup enabled.** Start from blank services or a custom stack and add the `zcp@1` service during creation.
+- **Existing development or staging setup.** Add the `zcp` workspace next to services that already exist. Do not add ZCP to production; promote verified work through your release process instead.
+
+Local setup can start from:
+
+- **Empty local directory.** The agent creates the app structure from a product request and uses ZCP to select or create Zerops services.
+- **Existing app directory.** The app code, editor setup, local data, and git credentials already live on your machine.
+- **Recipe prepared for local setup.** The recipe creates the Zerops service baseline, while the agent and files stay local.
+
+## Runtime layout is separate
+
+Remote or local only answers where the agent and `zcp` process run. The project can still use:
+
+- one mutable dev runtime,
+- a dev + stage pair,
+- a single app runtime,
+- local files linked to a stage target.
+
+That choice belongs to app work: [Build and ship](/zcp/workflows/build-with-zcp#choose-the-runtime-layout).
+
+Stage is not production. Keep production in a separate Zerops project and promote work through your release process; see [Production boundary](/zcp/security/production-policy).
+
+## Switching later
+
+Remote and local setup are not permanent, but switching is a handoff between workspaces, not a sync operation. Before switching, make the handoff explicit:
+
+- Preserve the current source tree through git or another explicit copy path.
+- Choose one deploy source for the next task: the remote workspace, mounted runtime files, or the local app directory.
+- Do not edit mounted runtime files and a local repo in parallel unless you have a merge plan.
+- Regenerate local `.env` snapshots after Zerops env changes.
+- If the local deploy target changed, have the agent inspect the current local link before deploying.
+
+## Next steps
+
+- [What remote workspace gives you](/zcp/setup/hosted-workspace) - remote setup, Browser VS Code, bundled agent CLI, and workspace persistence.
+- [Run locally](/zcp/setup/local-agent-bridge) - local install, `zcp init`, `.mcp.json`, VPN, env snapshots, and deploy target linking.
+- [Trust model](/zcp/security/trust-model) - how the safety boundary changes between remote setup and local setup.
diff --git a/apps/docs/content/zcp/setup/hosted-workspace.mdx b/apps/docs/content/zcp/setup/hosted-workspace.mdx
new file mode 100644
index 000000000..e49473183
--- /dev/null
+++ b/apps/docs/content/zcp/setup/hosted-workspace.mdx
@@ -0,0 +1,121 @@
+---
+title: 'What remote workspace gives you'
+description: 'What the zcp@1 workspace provides: Claude Code, Browser VS Code, private networking, and ZCP access inside Zerops.'
+---
+
+A remote workspace puts the agent, terminal, and optional browser IDE inside Zerops, next to private networking and ZCP access.
+
+The `zcp@1` service runs the same `zcp` binary used by local setup, but broad shell permissions and private service access stay in a clean Zerops service instead of on your laptop.
+
+Use remote setup when you want the default workspace, a safer boundary for broad agent permissions, or a preconfigured environment with Claude Code and Browser VS Code.
+
+App code still deploys to your app runtime services. The `zcp` service is the workspace and control surface; it is not the application runtime.
+
+Taking over is straightforward in this setup. You open the same workspace, terminal, files, and workflow status the agent used, then continue, inspect, or stop the work from there.
+
+## What it includes
+
+- **`zcp@1` workspace service.** Runs ZCP inside Zerops and gives the agent project-scoped operations.
+- **Platform-injected `ZCP_API_KEY`.** Zerops injects the token into the workspace; you normally do not set it by hand.
+- **Bundled Claude Code when enabled.** The **Include Coding Agent** option installs and preconfigures Claude Code. You authenticate with your own Claude subscription login or API key.
+- **Browser VS Code when enabled.** The **Cloud IDE** option gives you a browser editor, terminal, and a place to supervise or take over the agent session.
+- **Private networking.** The workspace can reach managed services by hostname without laptop VPN.
+- **Open workspace model.** You can add other agent CLIs, private MCP servers, helper processes, dotfiles, package installs, or a derived team image.
+
+For the local alternative, see [Run locally](/zcp/setup/local-agent-bridge). For the tradeoffs, see [Remote or local setup](/zcp/setup/choose-workspace).
+
+## Choose a starting point
+
+### First-time trial
+
+Use the [Quickstart](/zcp/quickstart) when you want the guided recipe route. It covers the recipe catalog, **AI Agent** environment, Claude Code authentication, Browser VS Code, first product prompt, and proof.
+
+After provisioning, continue with a product prompt in [Build and ship](/zcp/workflows/build-with-zcp).
+
+### Recipe with AI Agent environment
+
+Use this when you want a guided stack baseline for development or staging. A recipe with an **AI Agent** environment creates app services, managed services, and the `zcp@1` workspace together.
+
+Keep **Coding Agent** enabled when you want bundled Claude Code. Keep **Cloud IDE** enabled when you want Browser VS Code.
+
+### New Zerops setup with remote setup enabled
+
+Use this when you want blank services or a custom stack.
+
+1. Open [Add new project](https://app.zerops.io/dashboard/project-add).
+2. Enter the project name, region, and tags.
+3. Enable the `zcp@1` remote setup service.
+4. Keep **Include Coding Agent** enabled if you want bundled Claude Code.
+5. Keep **Cloud IDE** enabled if you want browser VS Code.
+6. Create the project.
+
+This gives you the `zcp@1` workspace. App runtimes and managed services may still be created later by normal ZCP app work.
+
+### Existing development or staging setup
+
+Use this when runtime or managed services already exist in development or staging. Do not add `zcp` to production; promote verified work through your release process.
+
+Add a `zcp` service from the dashboard the same way you add another Zerops service. The workspace appears next to the existing services and receives ZCP access from the platform.
+
+The agent should still read current state before changing anything. Existing services are context, not instructions for the next task.
+
+## Open the workspace
+
+For a returning remote workspace, open the existing `zcp` service:
+
+1. Open the project in the [Zerops dashboard](https://app.zerops.io/).
+2. Open the `zcp` service.
+3. Use **Browser VS Code** when **Cloud IDE** is enabled.
+4. Complete the Claude Code login or API-token flow if prompted.
+
+After authentication, Claude Code is connected to ZCP and ready to work from the Browser VS Code terminal. If the workspace was already authorized, use the same route to resume, supervise, or take over work.
+
+First load can take a minute while the image, Cloud IDE, and bundled agent finish starting. If the page opens before the service is ready, wait until the service is running and reload.
+
+## Use your own editor or tools
+
+Browser VS Code is the quickest entry point, not the only one.
+
+Editors that support remote development can connect to the workspace or runtime services over SSH, depending on how your team wants to work. Common options include VS Code Remote SSH, JetBrains Gateway, Cursor, Zed, and plain SSH.
+
+This keeps the agent and private network inside Zerops while letting you use a desktop editor UI. Broader editor patterns live in [Local & Remote Development](/features/local-remote-development#native-ide-over-ssh).
+
+You can also install another agent CLI or additional MCP servers inside the `zcp` service. The bundled Claude Code flow is a convenience, not a closed product boundary.
+
+## Advanced customization guardrails
+
+Tools installed inside the `zcp` service may see workspace environment variables, private networking, and any runtime files mounted into the workspace. Use trusted and pinned tools. Keep model credentials, git delivery tokens, external API keys, and production credentials out of the workspace unless the current task explicitly needs them.
+
+## What belongs where
+
+| Concern | Where it belongs |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Agent workspace | The `zcp@1` service: agent CLI, browser VS Code, shell tools, MCP servers, helper processes, dotfiles. |
+| App code deploys | Your app runtime services; not the `zcp` workspace service. |
+| `ZCP_API_KEY` | Injected by Zerops into the `zcp` workspace. |
+| Agent account | Your Claude subscription login or model API credential. Zerops wires the agent to ZCP, but the agent account remains yours. |
+| Git credentials | Configured inside the workspace when the agent should commit or push from remote setup. |
+| Production release | A separate production project and release process. |
+
+## Runtime file access
+
+Remote setup can mount runtime service filesystems into the `zcp` workspace after the first setup pass. Each mounted runtime appears as its own folder. Editing a mounted file changes the file inside that runtime service, with no upload step from your laptop.
+
+Filesystem reach is narrower than network reach. The workspace can reach services over the private network, but it only sees runtime files mounted into it.
+
+## Make customization persistent
+
+The `zcp@1` service is a normal Zerops service. One-off shell installs disappear when the service is rebuilt unless you make them part of the service setup.
+
+Use these patterns:
+
+- **Small additions:** put package installs, dotfiles, or bootstrap scripts into service init commands.
+- **Team-standard workspace:** build a derived image based on `zcp@1` with required tools already present.
+- **Helper processes:** run private helpers next to the agent and editor workspace when your team needs internal integrations.
+
+Keep app runtime build steps with the runtime services. The remote workspace carries the agent, tools, and ZCP access; runtime services own app builds and deploys.
+
+## Next steps
+
+- [Build and ship](/zcp/workflows/build-with-zcp) - normal app work after setup.
+- [Tokens and credentials](/zcp/security/tokens-and-project-access) - how `ZCP_API_KEY`, git credentials, and CI secrets differ.
diff --git a/apps/docs/content/zcp/setup/local-agent-bridge.mdx b/apps/docs/content/zcp/setup/local-agent-bridge.mdx
new file mode 100644
index 000000000..80fc61f2d
--- /dev/null
+++ b/apps/docs/content/zcp/setup/local-agent-bridge.mdx
@@ -0,0 +1,175 @@
+---
+title: 'Run locally'
+description: 'Install the zcp binary, initialize a local app directory, add ZCP_API_KEY, and connect a local agent to Zerops.'
+---
+
+Local setup installs the `zcp` binary on your machine and runs it from the app directory where your agent works.
+
+Use it when the agent should work next to local files, local data, your desktop editor, terminal tools, and git credentials. The MCP server limits Zerops operations to one project, but the agent client runs as your local user, so local approvals and filesystem allowlists matter.
+
+[Remote setup](/zcp/setup/hosted-workspace) is the safer default when the agent does not need local files or tools. Use local setup when local control is the point.
+
+:::warning Public preview
+Local setup has more moving parts than remote setup and may change faster. The binary install path, `.mcp.json` shape, and files written by `zcp init` are still settling between releases.
+:::
+
+## Choose a local starting point
+
+Pick the folder that should own app work:
+
+- **Empty local directory.** Start with no app code yet. The agent can create the app structure and use the MCP tools to select or create Zerops services.
+- **Existing app directory.** Use this when app code, local data, editor setup, test fixtures, and git credentials already live on your machine.
+- **Recipe prepared for local setup.** Use a recipe to create the Zerops service baseline, then run the agent locally from the directory that should own source changes.
+
+After that choice, the mechanics are the same: install `zcp`, run `zcp init`, add `ZCP_API_KEY`, start VPN when private service access is needed, and link a runtime when the agent should deploy.
+
+## What local setup gives the agent
+
+- **Local files as source.** The agent edits the directory on your machine, and deploys use that working directory.
+- **Your editor and terminal.** Framework CLIs, test runners, local data, and local feedback stay under your normal tools.
+- **Your git credentials.** Pushes use your local git CLI, SSH agent, or credential helper.
+- **Zerops operations.** The MCP tools let the agent discover services, generate env snapshots, deploy to linked runtimes, read logs, and verify.
+- **Private service access through VPN.** Your local app and shell reach private service hostnames through `zcli vpn up`.
+
+Security note: local setup cannot protect your laptop from the agent client. Configure approvals as you would for any local coding agent.
+
+## Prerequisites
+
+- A Zerops project. Create one from the [Zerops dashboard](https://app.zerops.io/dashboard/project-add), from a [recipe](https://app.zerops.io/recipes), or use an existing development/staging setup.
+- [zCLI](/references/cli) installed and authenticated on your machine.
+- A compatible local agent client installed and logged in.
+- A **single-project Zerops token**. Multi-project tokens are refused at startup.
+- A local directory where the agent should run.
+
+You do not need MCP just to develop locally against Zerops services as a human. `zcli vpn up` plus your editor is enough. Add MCP when a local coding agent should also understand and operate Zerops.
+
+## 1. Get `ZCP_API_KEY`
+
+The MCP server needs a Zerops API token that reaches exactly one project. For normal agent work, use a full-access token; read-only tokens can authenticate but fail on deploys, env changes, lifecycle actions, and other mutations. Token generation, rejected shapes, and rotation are covered in [Tokens and credentials](/zcp/security/tokens-and-project-access).
+
+## 2. Install `zcp`
+
+```bash
+curl -sSfL https://raw.githubusercontent.com/zeropsio/zcp/main/install.sh | sh
+```
+
+The installer downloads the latest release for your platform into `~/.local/bin`, or `/usr/local/bin` when run as root. Verify the install:
+
+```bash
+zcp version
+```
+
+If your shell cannot find `zcp`, add the install directory to `PATH` and reload the shell.
+
+## 3. Run `zcp init`
+
+From the local directory the agent should operate:
+
+```bash
+zcp init
+```
+
+`zcp init` writes local MCP config and agent instructions:
+
+- `.mcp.json` - MCP server config for this directory.
+- `CLAUDE.md` - agent instructions for Zerops work.
+- `.claude/settings.local.json` - Claude Code per-project settings when that client is used.
+- `~/.config/zerops/aliases` plus a shell-rc sourcing line - helper aliases for launching the agent here.
+- `.zcp/state/` - workflow state created when MCP first writes local state.
+
+Re-running `zcp init` may refresh generated config. `CLAUDE.md` preserves edits outside managed markers, but `.mcp.json` is regenerated from the token-less template. If you rerun it, re-check the `ZCP_API_KEY` block before launching the agent.
+
+## 4. Add `ZCP_API_KEY`
+
+`zcp init` writes a token-less `.mcp.json`. Add the project token under the `env` block:
+
+```json
+{
+ "mcpServers": {
+ "zerops": {
+ "command": "zcp",
+ "args": ["serve"],
+ "env": {
+ "ZCP_API_KEY": ""
+ }
+ }
+ }
+}
+```
+
+Add `.mcp.json` to `.gitignore`. It contains a live Zerops credential and should not leave the machine. Each app directory should have its own `.mcp.json` and token.
+
+The server name `zerops` is intentional. Do not rename it unless your agent client requires a different name and you understand the prompt/instruction changes.
+
+## 5. Launch the agent from the app directory
+
+Start the agent from the directory that contains `.mcp.json`. The client should list `zerops` as an available MCP server.
+
+Sanity check:
+
+```text
+List the Zerops services through MCP.
+```
+
+A working connection answers with the runtime and managed services. If not, check the launch directory, token scope, and whether the client loaded `.mcp.json`.
+
+## 6. Bring up VPN when private services are needed
+
+The MCP server can talk to the Zerops API without VPN. Your local app, shell, tests, database clients, and framework commands need VPN to reach private hostnames such as `db` or `cache`.
+
+```bash
+zcli vpn up
+```
+
+VPN setup needs admin or root approval on macOS and Linux. The tools can tell the agent which command is needed, but they cannot approve or start it for you. After the tunnel is up, service hostnames resolve from your machine; rerun the command when local service connections fail.
+
+## 7. Generate local env when needed
+
+When the local app needs service credentials, ask the agent for the app work and let the tools generate the env bridge. For a standalone check:
+
+```text
+Generate a .env file for my local app from Zerops env references.
+```
+
+Env generation needs `zerops.yaml` in the working directory, the runtime or setup the local app should use, a matching `setup:` entry, and non-empty `run.envVariables` under that setup.
+
+The tools read `run.envVariables`, resolve Zerops references such as `${db_user}`, `${db_password}`, and `${db_hostname}`, and write the resulting values into `.env`. Cross-service references resolve recursively, so a `DATABASE_URL` can land as a complete local connection string.
+
+If those inputs are missing, the agent should fix `zerops.yaml` or ask for the target runtime/setup. It should not invent env values from service names or dashboard memory.
+
+The file is a snapshot, not a live sync. Regenerate it after changing env variables in Zerops. VPN is still required for your local app to use private service hostnames from that `.env`.
+
+Keep `.env` out of git. It contains real connection values.
+
+## 8. Link a deploy target
+
+Local setup needs a Zerops runtime when the agent should deploy from your working directory. A stage runtime is the usual target because it lets local work prove itself before the production release.
+
+If there is exactly one runtime, the agent can use it automatically. If multiple runtimes exist, it should ask which one to link:
+
+```text
+Link this local directory to appstage for deploys.
+```
+
+Without a linked runtime, the tools can still inspect services and generate env snapshots, but local deploys need a target first.
+
+## What stays outside
+
+MCP does not replace your local feedback loop. Vite, Valet, Docker Compose, your IDE runner, framework CLIs, local fixtures, and test data stay under your normal tooling.
+
+Local setup does not mount Zerops runtime filesystems on your laptop. Remote setup can mount runtime files into the workspace; local setup works from files on your machine. To inspect runtime files from your machine, use [SSH](/references/networking/ssh) directly.
+
+The MCP server does not own your git credentials. In local setup, your local git CLI, SSH agent, or credential helper handles pushes.
+
+## Local setup checks
+
+- **Launch directory matters.** Start the agent from the folder that contains `.mcp.json`.
+- **`zcp init` can remove the token from `.mcp.json`.** Re-add `ZCP_API_KEY` after rerunning init.
+- **VPN is separate from MCP auth.** MCP may work while your app still cannot reach `db`.
+- **`.env` generation depends on `run.envVariables`.** If generation fails, check that the working directory has `zerops.yaml`, the selected `setup:` exists, and env entries live under `run.envVariables`.
+- **`.env` is a credential snapshot.** Regenerate after env changes and keep it out of git.
+
+## Next steps
+
+- [Build and ship](/zcp/workflows/build-with-zcp) - normal app work after setup.
+- [Tokens and credentials](/zcp/security/tokens-and-project-access) - token scope, storage, rotation, and destructive confirmations.
diff --git a/apps/docs/content/zcp/workflows/build-with-zcp.mdx b/apps/docs/content/zcp/workflows/build-with-zcp.mdx
new file mode 100644
index 000000000..2457ea76f
--- /dev/null
+++ b/apps/docs/content/zcp/workflows/build-with-zcp.mdx
@@ -0,0 +1,138 @@
+---
+title: 'Build and ship'
+description: 'The practical choices you control when a coding agent works on a Zerops project.'
+---
+
+Use Build and ship for the decisions that shape normal app work. ZCP MCP gives the agent Zerops project state, platform guidance, project-scoped operations, deploy evidence, and recovery rules. You still decide what should be built, where it should run, how strict the acceptance criteria are, and what happens after proof.
+
+```text
+Build a task board.
+Tasks should stay saved after refresh.
+```
+
+A prompt can be that short when the outcome is enough. Add detail when it changes behavior, architecture, stack, runtime layout, acceptance criteria, credentials, delivery, packaging, or the production release.
+
+The expected output is a verified running change, not only generated files. The agent should prove the request against a real runtime, real managed services when used, and the logs, events, and checks that explain what happened.
+
+## The decisions
+
+
+
+ Product prompt
+ Build a task board...
+
+
+
+
+
1. Runtime layout
+
Choose where app work should land.
+
+
Use existing services
+
Create missing services
+
Pick dev, stage, or linked target
+
+
+
+
2. Development
+
The agent gets current state, Zerops knowledge, deploy evidence, and your product instructions.
-> just the table.
+function convertExpandableTableToMarkdown(content) {
+ return content.replace(
+ /]*)?>([\s\S]*?)<\/ExpandableTable>/g,
+ '$1'
+ );
+}
+
+// Standalone -> markdown bullet list of
+// backticked items. `getData` is a `(siteDir) => object` loader.
+function convertUnorderedCodeListStandalone(content, getData, siteDir) {
+ return content.replace(
+ //g,
+ (match, dataPath) => {
+ try {
+ const data = getData(siteDir);
+ const keys = dataPath.trim().replace(/^data\./, '').split('.');
+ let val = data;
+ for (const key of keys) {
+ if (val && typeof val === 'object' && key in val) val = val[key];
+ else return match;
+ }
+ if (Array.isArray(val)) {
+ return '\n' + val.map((item) => {
+ if (Array.isArray(item)) {
+ return `- ${item.map((s) => `\`${s}\``).join(', ')}`;
+ }
+ const commentMatch = String(item).match(/^(.+?)\s*\(([^()]+)\)\s*$/);
+ if (commentMatch) {
+ return `- \`${commentMatch[1].trim()}\` (${commentMatch[2].trim()})`;
+ }
+ return `- \`${item}\``;
+ }).join('\n') + '\n';
+ }
+ return `\`${val}\``;
+ } catch (_) {
+ return match;
+ }
+ }
+ );
+}
+
+// Drop components that have no useful markdown representation (purely
+// decorative / interactive without source content). Handles both self-closing
+// and wrapping forms.
+const SILENT_DROP_COMPONENTS = [
+ 'PricingCalculator',
+ 'BrandAssets',
+ 'BackgroundPattern',
+ 'ResourceTable',
+ 'TechCard',
+ 'GroupCards',
+ 'TabbedCodeBlocks',
+ 'ExpandableTable', // already converted to inner table above; this is a fallback
+];
+function dropSilentComponents(content, names = SILENT_DROP_COMPONENTS) {
+ for (const name of names) {
+ const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ // wrapping form first (lazy)
+ content = content.replace(
+ new RegExp(`<${escaped}\\b[^>]*>[\\s\\S]*?<\\/${escaped}>`, 'g'),
+ ''
+ );
+ // self-closing form. Use brace-aware skip for props that contain `{...}`
+ content = stripSelfClosing(content, name);
+ }
+ return content;
+}
+
+// Remove `` instances where `...` may include JSX expression
+// containers `{ ... }` with `>` inside (e.g. `items={[ ...arrow funcs > 0 ... ]}`).
+function stripSelfClosing(content, name) {
+ const TAG = `<${name}`;
+ const out = [];
+ let cursor = 0;
+ while (cursor < content.length) {
+ const start = content.indexOf(TAG, cursor);
+ if (start === -1) {
+ out.push(content.slice(cursor));
+ break;
+ }
+ out.push(content.slice(cursor, start));
+ // After `)
+ // to avoid matching `` or `>`.
+ let i = start + TAG.length;
+ let inString = null;
+ let braceDepth = 0;
+ let tagEnd = -1;
+ let selfClosing = false;
+ while (i < content.length) {
+ const ch = content[i];
+ const prev = i > 0 ? content[i - 1] : '';
+ if (inString) {
+ if (ch === inString && prev !== '\\') inString = null;
+ i++;
+ continue;
+ }
+ if (ch === "'" || ch === '"' || ch === '`') {
+ inString = ch;
+ i++;
+ continue;
+ }
+ if (ch === '{') {
+ braceDepth++;
+ i++;
+ continue;
+ }
+ if (ch === '}') {
+ braceDepth--;
+ i++;
+ continue;
+ }
+ if (braceDepth === 0 && ch === '/' && content[i + 1] === '>') {
+ tagEnd = i + 2;
+ selfClosing = true;
+ break;
+ }
+ if (braceDepth === 0 && ch === '>') {
+ tagEnd = i + 1;
+ break;
+ }
+ i++;
+ }
+ if (tagEnd === -1) {
+ // Couldn't parse — emit and advance.
+ out.push(content[start]);
+ cursor = start + 1;
+ continue;
+ }
+ if (selfClosing) {
+ cursor = tagEnd;
+ } else {
+ // Drop matching close tag too if present
+ const closeTag = ``;
+ const closeIdx = content.indexOf(closeTag, tagEnd);
+ cursor = closeIdx !== -1 ? closeIdx + closeTag.length : tagEnd;
+ }
+ }
+ return out.join('');
+}
+
+module.exports = {
+ // helpers
+ getAttr,
+ findMatchingBrace,
+ splitTopLevelObjects,
+ stripSelfClosing,
+ // pre-existing
+ convertTabsToMarkdown,
+ convertDetailsToMarkdown,
+ convertFAQToMarkdown,
+ // new
+ convertNoteToMarkdown,
+ convertAsciiGraphToMarkdown,
+ convertDocCardListToMarkdown,
+ convertBadgeToMarkdown,
+ convertButtonToMarkdown,
+ convertLinkToMarkdown,
+ convertCustomCardToMarkdown,
+ convertDeployButtonToMarkdown,
+ convertDropdownToMarkdown,
+ convertVideoToMarkdown,
+ convertCodingAgentsTopologyToMarkdown,
+ convertIntroAgentVisualToMarkdown,
+ convertSectionLandscapeToMarkdown,
+ convertExpandableTableToMarkdown,
+ convertUnorderedCodeListStandalone,
+ dropSilentComponents,
+ NOTE_TYPE_TO_ADMONITION,
+ BADGE_TYPE_LABELS,
+ SILENT_DROP_COMPONENTS,
+};
diff --git a/apps/docs/src/plugins/markdown-source/index.js b/apps/docs/src/plugins/markdown-source/index.js
index 388a37b77..f3213541a 100644
--- a/apps/docs/src/plugins/markdown-source/index.js
+++ b/apps/docs/src/plugins/markdown-source/index.js
@@ -1,5 +1,6 @@
const fs = require('fs-extra');
const path = require('path');
+const C = require('./converters');
/**
* Docusaurus plugin to copy raw markdown files to build output
@@ -34,8 +35,9 @@ function extractFrontmatter(content) {
const titleMatch = frontmatter.match(/^title:\s*(.+)$/m);
const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
- const title = titleMatch ? titleMatch[1].trim() : null;
- const description = descMatch ? descMatch[1].trim() : null;
+ const stripQuotes = (s) => s.trim().replace(/^['"]([\s\S]*)['"]$/, '$1');
+ const title = titleMatch ? stripQuotes(titleMatch[1]) : null;
+ const description = descMatch ? stripQuotes(descMatch[1]) : null;
// Remove frontmatter from content
const contentWithoutFrontmatter = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
@@ -520,6 +522,57 @@ function cleanMarkdownForDisplay(content, filepath, siteDir, docsDir) {
// 14. Convert Tabs/TabItem components to readable markdown (preserve content)
content = convertTabsToMarkdown(content);
+ // --- Custom-component converters (order matters) -----------------------
+ // 14a. Note callouts -> Docusaurus admonitions (with title preserved)
+ content = C.convertNoteToMarkdown(content);
+
+ // 14b. ASCII diagram blocks -> fenced code blocks, JSX template literals
+ // and inline highlights unwrapped to plain text.
+ content = C.convertAsciiGraphToMarkdown(content);
+
+ // 14c. DocCardList items array -> markdown bullet list of links
+ content = C.convertDocCardListToMarkdown(content);
+
+ // 14d. CustomCard -> ### heading + body
+ content = C.convertCustomCardToMarkdown(content);
+
+ // 14e. Dropdown / DropdownItem -> #### per item
+ content = C.convertDropdownToMarkdown(content);
+
+ // 14f. Landscape section (coding-agents.mdx) -> heading + examples + body
+ content = C.convertSectionLandscapeToMarkdown(content);
+
+ // 14g. ExpandableTable -> unwrap to inner table (will be picked up by
+ // convertHtmlTablesToMarkdown next build, but at this point tables have
+ // already been converted; this is mostly a safety net).
+ content = C.convertExpandableTableToMarkdown(content);
+
+ // 14h. Standalone UnorderedCodeList (not inside a table) -> bullet list
+ content = C.convertUnorderedCodeListStandalone(content, getDataJson, siteDir);
+
+ // 14i. CodingAgentsTopology / IntroAgentVisual -> placeholders pointing at the live page
+ content = C.convertCodingAgentsTopologyToMarkdown(content);
+ content = C.convertIntroAgentVisualToMarkdown(content);
+
+ // 14j. DeployButton -> markdown link to recipe deploy URL
+ content = C.convertDeployButtonToMarkdown(content);
+
+ // 14k. Video -> text link to video src
+ content = C.convertVideoToMarkdown(content);
+
+ // 14l. Badge -> *[Optional]* / *[Required]* inline label
+ content = C.convertBadgeToMarkdown(content);
+
+ // 14m. Button -> unwrap (leaves children, typically a )
+ content = C.convertButtonToMarkdown(content);
+
+ // 14n. Link -> [text](href). Run AFTER Button so unwrapped children render.
+ content = C.convertLinkToMarkdown(content);
+
+ // 14o. Drop components with no useful markdown representation
+ content = C.dropSilentComponents(content);
+ // -------------------------------------------------------------------
+
// 15. Convert details/summary components to readable markdown (preserve content)
content = convertDetailsToMarkdown(content);
@@ -624,6 +677,19 @@ async function copyImageDirectories(docsDir, buildDir) {
}
module.exports = function markdownSourcePlugin(context, options) {
+ const docsDir = path.join(context.siteDir, 'content');
+
+ // Resolve a `.md` URL path back to a source file under content/.
+ // Returns the absolute path or null when no source exists.
+ function resolveSourcePath(urlPath) {
+ const stripped = urlPath.replace(/^\//, '').replace(/\.md$/, '');
+ const mdxCandidate = path.join(docsDir, `${stripped}.mdx`);
+ if (fs.existsSync(mdxCandidate)) return mdxCandidate;
+ const mdCandidate = path.join(docsDir, `${stripped}.md`);
+ if (fs.existsSync(mdCandidate)) return mdCandidate;
+ return null;
+ }
+
return {
name: 'markdown-source-plugin',
@@ -632,6 +698,42 @@ module.exports = function markdownSourcePlugin(context, options) {
return path.resolve(__dirname, './theme');
},
+ // Dev-mode middleware: postBuild doesn't run during `docusaurus start`,
+ // so without this the Copy/View as Markdown buttons hit the SPA fallback
+ // (HTML shell + 404). Intercept `.md` requests and produce the same
+ // cleaned output the production build would.
+ configureWebpack(_config, isServer) {
+ if (isServer) return {};
+ return {
+ devServer: {
+ setupMiddlewares: (middlewares, devServer) => {
+ devServer.app.get(/\.md$/, (req, res, next) => {
+ try {
+ const sourcePath = resolveSourcePath(req.path);
+ if (!sourcePath) return next();
+ const content = fs.readFileSync(sourcePath, 'utf8');
+ const relPath = path.relative(docsDir, sourcePath);
+ const cleaned = cleanMarkdownForDisplay(
+ content,
+ relPath,
+ context.siteDir,
+ docsDir
+ );
+ res.setHeader(
+ 'Content-Type',
+ 'text/markdown; charset=utf-8'
+ );
+ res.send(cleaned);
+ } catch (err) {
+ next(err);
+ }
+ });
+ return middlewares;
+ },
+ },
+ };
+ },
+
async postBuild({ outDir }) {
const docsDir = path.join(context.siteDir, 'content');
const buildDir = outDir;
diff --git a/apps/docs/src/theme/MDXComponents/index.tsx b/apps/docs/src/theme/MDXComponents/index.tsx
index 5598eb6ad..5a1c1a656 100644
--- a/apps/docs/src/theme/MDXComponents/index.tsx
+++ b/apps/docs/src/theme/MDXComponents/index.tsx
@@ -9,6 +9,7 @@ import MDXDetails from './Details';
import DocCard from '@theme/DocCard';
import DocCardList from '@theme/DocCardList';
import ExpandableTable from '@site/src/components/ExpandableTable';
+import AsciiGraph from '@site/src/components/AsciiGraph';
const components = {
// Re-use the default mapping
@@ -25,6 +26,7 @@ const components = {
DocCardList,
Note,
ExpandableTable,
+ AsciiGraph,
};
export default components;
\ No newline at end of file
diff --git a/apps/docs/static/fonts/JetBrainsMono-Regular.woff2 b/apps/docs/static/fonts/JetBrainsMono-Regular.woff2
new file mode 100644
index 000000000..66c54672c
Binary files /dev/null and b/apps/docs/static/fonts/JetBrainsMono-Regular.woff2 differ
diff --git a/apps/docs/static/img/landscape/aider.png b/apps/docs/static/img/landscape/aider.png
new file mode 100644
index 000000000..0a921307c
Binary files /dev/null and b/apps/docs/static/img/landscape/aider.png differ
diff --git a/apps/docs/static/img/landscape/anthropic.ico b/apps/docs/static/img/landscape/anthropic.ico
new file mode 100644
index 000000000..ec917df6e
Binary files /dev/null and b/apps/docs/static/img/landscape/anthropic.ico differ
diff --git a/apps/docs/static/img/landscape/aws.png b/apps/docs/static/img/landscape/aws.png
new file mode 100644
index 000000000..80944f5d6
Binary files /dev/null and b/apps/docs/static/img/landscape/aws.png differ
diff --git a/apps/docs/static/img/landscape/bolt.png b/apps/docs/static/img/landscape/bolt.png
new file mode 100644
index 000000000..53806753b
Binary files /dev/null and b/apps/docs/static/img/landscape/bolt.png differ
diff --git a/apps/docs/static/img/landscape/claude.png b/apps/docs/static/img/landscape/claude.png
new file mode 100644
index 000000000..505717358
Binary files /dev/null and b/apps/docs/static/img/landscape/claude.png differ
diff --git a/apps/docs/static/img/landscape/cline.png b/apps/docs/static/img/landscape/cline.png
new file mode 100644
index 000000000..19d1a41c4
Binary files /dev/null and b/apps/docs/static/img/landscape/cline.png differ
diff --git a/apps/docs/static/img/landscape/cloudflare.png b/apps/docs/static/img/landscape/cloudflare.png
new file mode 100644
index 000000000..a000261dc
Binary files /dev/null and b/apps/docs/static/img/landscape/cloudflare.png differ
diff --git a/apps/docs/static/img/landscape/coder.svg b/apps/docs/static/img/landscape/coder.svg
new file mode 100644
index 000000000..41e19b928
--- /dev/null
+++ b/apps/docs/static/img/landscape/coder.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/landscape/codesandbox.svg b/apps/docs/static/img/landscape/codesandbox.svg
new file mode 100644
index 000000000..453e07354
--- /dev/null
+++ b/apps/docs/static/img/landscape/codesandbox.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/landscape/cursor.png b/apps/docs/static/img/landscape/cursor.png
new file mode 100644
index 000000000..86fe0427b
Binary files /dev/null and b/apps/docs/static/img/landscape/cursor.png differ
diff --git a/apps/docs/static/img/landscape/daytona.ico b/apps/docs/static/img/landscape/daytona.ico
new file mode 100644
index 000000000..602d9e3e4
Binary files /dev/null and b/apps/docs/static/img/landscape/daytona.ico differ
diff --git a/apps/docs/static/img/landscape/devin.ico b/apps/docs/static/img/landscape/devin.ico
new file mode 100644
index 000000000..dd0ead691
Binary files /dev/null and b/apps/docs/static/img/landscape/devin.ico differ
diff --git a/apps/docs/static/img/landscape/digitalocean.png b/apps/docs/static/img/landscape/digitalocean.png
new file mode 100644
index 000000000..b71812af4
Binary files /dev/null and b/apps/docs/static/img/landscape/digitalocean.png differ
diff --git a/apps/docs/static/img/landscape/e2b.ico b/apps/docs/static/img/landscape/e2b.ico
new file mode 100644
index 000000000..0e138eb9e
Binary files /dev/null and b/apps/docs/static/img/landscape/e2b.ico differ
diff --git a/apps/docs/static/img/landscape/fly.png b/apps/docs/static/img/landscape/fly.png
new file mode 100644
index 000000000..f891620de
Binary files /dev/null and b/apps/docs/static/img/landscape/fly.png differ
diff --git a/apps/docs/static/img/landscape/github.png b/apps/docs/static/img/landscape/github.png
new file mode 100644
index 000000000..fbaa2a6ff
Binary files /dev/null and b/apps/docs/static/img/landscape/github.png differ
diff --git a/apps/docs/static/img/landscape/gitpod.ico b/apps/docs/static/img/landscape/gitpod.ico
new file mode 100644
index 000000000..6c92eda0d
Binary files /dev/null and b/apps/docs/static/img/landscape/gitpod.ico differ
diff --git a/apps/docs/static/img/landscape/hetzner.ico b/apps/docs/static/img/landscape/hetzner.ico
new file mode 100644
index 000000000..882f0c0dd
Binary files /dev/null and b/apps/docs/static/img/landscape/hetzner.ico differ
diff --git a/apps/docs/static/img/landscape/linode.png b/apps/docs/static/img/landscape/linode.png
new file mode 100644
index 000000000..d3b37b14d
Binary files /dev/null and b/apps/docs/static/img/landscape/linode.png differ
diff --git a/apps/docs/static/img/landscape/lovable.png b/apps/docs/static/img/landscape/lovable.png
new file mode 100644
index 000000000..09b6a1fa7
Binary files /dev/null and b/apps/docs/static/img/landscape/lovable.png differ
diff --git a/apps/docs/static/img/landscape/mastra.png b/apps/docs/static/img/landscape/mastra.png
new file mode 100644
index 000000000..ccd648bfc
Binary files /dev/null and b/apps/docs/static/img/landscape/mastra.png differ
diff --git a/apps/docs/static/img/landscape/modal.png b/apps/docs/static/img/landscape/modal.png
new file mode 100644
index 000000000..05f51a49a
Binary files /dev/null and b/apps/docs/static/img/landscape/modal.png differ
diff --git a/apps/docs/static/img/landscape/openhands.png b/apps/docs/static/img/landscape/openhands.png
new file mode 100644
index 000000000..cb10e2510
Binary files /dev/null and b/apps/docs/static/img/landscape/openhands.png differ
diff --git a/apps/docs/static/img/landscape/railway.png b/apps/docs/static/img/landscape/railway.png
new file mode 100644
index 000000000..db788283b
Binary files /dev/null and b/apps/docs/static/img/landscape/railway.png differ
diff --git a/apps/docs/static/img/landscape/render.svg b/apps/docs/static/img/landscape/render.svg
new file mode 100644
index 000000000..6a0f238ca
--- /dev/null
+++ b/apps/docs/static/img/landscape/render.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/landscape/replit.png b/apps/docs/static/img/landscape/replit.png
new file mode 100644
index 000000000..93dd74230
Binary files /dev/null and b/apps/docs/static/img/landscape/replit.png differ
diff --git a/apps/docs/static/img/landscape/v0.png b/apps/docs/static/img/landscape/v0.png
new file mode 100644
index 000000000..f94547534
Binary files /dev/null and b/apps/docs/static/img/landscape/v0.png differ
diff --git a/apps/docs/static/img/landscape/vercel.ico b/apps/docs/static/img/landscape/vercel.ico
new file mode 100644
index 000000000..40cc5977d
Binary files /dev/null and b/apps/docs/static/img/landscape/vercel.ico differ
diff --git a/apps/docs/static/img/landscape/vultr.png b/apps/docs/static/img/landscape/vultr.png
new file mode 100644
index 000000000..2d0ee6bf2
Binary files /dev/null and b/apps/docs/static/img/landscape/vultr.png differ
diff --git a/apps/docs/static/img/landscape/windsurf.png b/apps/docs/static/img/landscape/windsurf.png
new file mode 100644
index 000000000..545a64fae
Binary files /dev/null and b/apps/docs/static/img/landscape/windsurf.png differ
diff --git a/apps/docs/static/img/landscape/zed.png b/apps/docs/static/img/landscape/zed.png
new file mode 100644
index 000000000..3f56a5d48
Binary files /dev/null and b/apps/docs/static/img/landscape/zed.png differ
diff --git a/apps/docs/static/img/recipes/astro.svg b/apps/docs/static/img/recipes/astro.svg
new file mode 100644
index 000000000..911c59f05
--- /dev/null
+++ b/apps/docs/static/img/recipes/astro.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/claude.png b/apps/docs/static/img/recipes/claude.png
new file mode 100644
index 000000000..505717358
Binary files /dev/null and b/apps/docs/static/img/recipes/claude.png differ
diff --git a/apps/docs/static/img/recipes/codex.svg b/apps/docs/static/img/recipes/codex.svg
new file mode 100644
index 000000000..ebbdab0ec
--- /dev/null
+++ b/apps/docs/static/img/recipes/codex.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/django.svg b/apps/docs/static/img/recipes/django.svg
new file mode 100644
index 000000000..2ab6f7636
--- /dev/null
+++ b/apps/docs/static/img/recipes/django.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/dotnet.svg b/apps/docs/static/img/recipes/dotnet.svg
new file mode 100644
index 000000000..c4b482ecc
--- /dev/null
+++ b/apps/docs/static/img/recipes/dotnet.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/express.svg b/apps/docs/static/img/recipes/express.svg
new file mode 100644
index 000000000..96c2be8f0
--- /dev/null
+++ b/apps/docs/static/img/recipes/express.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/fastapi.svg b/apps/docs/static/img/recipes/fastapi.svg
new file mode 100644
index 000000000..6bab9e10c
--- /dev/null
+++ b/apps/docs/static/img/recipes/fastapi.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/flask.svg b/apps/docs/static/img/recipes/flask.svg
new file mode 100644
index 000000000..4c32ea9a8
--- /dev/null
+++ b/apps/docs/static/img/recipes/flask.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/gemini.svg b/apps/docs/static/img/recipes/gemini.svg
new file mode 100644
index 000000000..e15e53ce0
--- /dev/null
+++ b/apps/docs/static/img/recipes/gemini.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/go.svg b/apps/docs/static/img/recipes/go.svg
new file mode 100644
index 000000000..51990bd01
--- /dev/null
+++ b/apps/docs/static/img/recipes/go.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/laravel.svg b/apps/docs/static/img/recipes/laravel.svg
new file mode 100644
index 000000000..36f0035a9
--- /dev/null
+++ b/apps/docs/static/img/recipes/laravel.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/nestjs.svg b/apps/docs/static/img/recipes/nestjs.svg
new file mode 100644
index 000000000..61770a794
--- /dev/null
+++ b/apps/docs/static/img/recipes/nestjs.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/nextjs.svg b/apps/docs/static/img/recipes/nextjs.svg
new file mode 100644
index 000000000..42e365b4d
--- /dev/null
+++ b/apps/docs/static/img/recipes/nextjs.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/nodejs.svg b/apps/docs/static/img/recipes/nodejs.svg
new file mode 100644
index 000000000..3cc5893e0
--- /dev/null
+++ b/apps/docs/static/img/recipes/nodejs.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/nuxt.svg b/apps/docs/static/img/recipes/nuxt.svg
new file mode 100644
index 000000000..024d2464c
--- /dev/null
+++ b/apps/docs/static/img/recipes/nuxt.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/opencode.png b/apps/docs/static/img/recipes/opencode.png
new file mode 100644
index 000000000..70fd01b0e
Binary files /dev/null and b/apps/docs/static/img/recipes/opencode.png differ
diff --git a/apps/docs/static/img/recipes/php.svg b/apps/docs/static/img/recipes/php.svg
new file mode 100644
index 000000000..92bdc7de4
--- /dev/null
+++ b/apps/docs/static/img/recipes/php.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/python.svg b/apps/docs/static/img/recipes/python.svg
new file mode 100644
index 000000000..e1b14ec64
--- /dev/null
+++ b/apps/docs/static/img/recipes/python.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/rails.svg b/apps/docs/static/img/recipes/rails.svg
new file mode 100644
index 000000000..172cb977e
--- /dev/null
+++ b/apps/docs/static/img/recipes/rails.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/remix.svg b/apps/docs/static/img/recipes/remix.svg
new file mode 100644
index 000000000..31169d9a3
--- /dev/null
+++ b/apps/docs/static/img/recipes/remix.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/rust.svg b/apps/docs/static/img/recipes/rust.svg
new file mode 100644
index 000000000..faa8c3a34
--- /dev/null
+++ b/apps/docs/static/img/recipes/rust.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/spring.svg b/apps/docs/static/img/recipes/spring.svg
new file mode 100644
index 000000000..11a2af992
--- /dev/null
+++ b/apps/docs/static/img/recipes/spring.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/svelte.svg b/apps/docs/static/img/recipes/svelte.svg
new file mode 100644
index 000000000..a3f86d5b8
--- /dev/null
+++ b/apps/docs/static/img/recipes/svelte.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/symfony.svg b/apps/docs/static/img/recipes/symfony.svg
new file mode 100644
index 000000000..4cc586fcf
--- /dev/null
+++ b/apps/docs/static/img/recipes/symfony.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/zerops/analog.svg b/apps/docs/static/img/recipes/zerops/analog.svg
new file mode 100644
index 000000000..21f9e11d0
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/analog.svg
@@ -0,0 +1,28 @@
+
diff --git a/apps/docs/static/img/recipes/zerops/angular.png b/apps/docs/static/img/recipes/zerops/angular.png
new file mode 100644
index 000000000..4c7e8f0c5
Binary files /dev/null and b/apps/docs/static/img/recipes/zerops/angular.png differ
diff --git a/apps/docs/static/img/recipes/zerops/astro.svg b/apps/docs/static/img/recipes/zerops/astro.svg
new file mode 100644
index 000000000..9ccc83d3e
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/astro.svg
@@ -0,0 +1,3 @@
+
diff --git a/apps/docs/static/img/recipes/zerops/bun.svg b/apps/docs/static/img/recipes/zerops/bun.svg
new file mode 100644
index 000000000..e883b1642
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/bun.svg
@@ -0,0 +1 @@
+
diff --git a/apps/docs/static/img/recipes/zerops/deno.svg b/apps/docs/static/img/recipes/zerops/deno.svg
new file mode 100644
index 000000000..c7f7189e2
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/deno.svg
@@ -0,0 +1 @@
+
diff --git a/apps/docs/static/img/recipes/zerops/dotnet.svg b/apps/docs/static/img/recipes/zerops/dotnet.svg
new file mode 100644
index 000000000..d9e61fda5
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/dotnet.svg
@@ -0,0 +1 @@
+
diff --git a/apps/docs/static/img/recipes/zerops/gleam.svg b/apps/docs/static/img/recipes/zerops/gleam.svg
new file mode 100644
index 000000000..2e0a9fe1a
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/gleam.svg
@@ -0,0 +1,7 @@
+
diff --git a/apps/docs/static/img/recipes/zerops/golang.svg b/apps/docs/static/img/recipes/zerops/golang.svg
new file mode 100644
index 000000000..64e962077
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/golang.svg
@@ -0,0 +1,60 @@
+
+
+
diff --git a/apps/docs/static/img/recipes/zerops/java.svg b/apps/docs/static/img/recipes/zerops/java.svg
new file mode 100644
index 000000000..bd9542c51
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/java.svg
@@ -0,0 +1 @@
+
diff --git a/apps/docs/static/img/recipes/zerops/laravel.svg b/apps/docs/static/img/recipes/zerops/laravel.svg
new file mode 100644
index 000000000..e1309dd21
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/laravel.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/zerops/nestjs.svg b/apps/docs/static/img/recipes/zerops/nestjs.svg
new file mode 100644
index 000000000..69830240c
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/nestjs.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/zerops/nextjs.svg b/apps/docs/static/img/recipes/zerops/nextjs.svg
new file mode 100644
index 000000000..50ccbbd18
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/nextjs.svg
@@ -0,0 +1,8 @@
+
+
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/zerops/nodejs.svg b/apps/docs/static/img/recipes/zerops/nodejs.svg
new file mode 100644
index 000000000..4d140b28e
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/nodejs.svg
@@ -0,0 +1 @@
+
diff --git a/apps/docs/static/img/recipes/zerops/nuxt.svg b/apps/docs/static/img/recipes/zerops/nuxt.svg
new file mode 100644
index 000000000..ead151fc7
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/nuxt.svg
@@ -0,0 +1,3 @@
+
diff --git a/apps/docs/static/img/recipes/zerops/php.svg b/apps/docs/static/img/recipes/zerops/php.svg
new file mode 100644
index 000000000..d2f28cb59
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/php.svg
@@ -0,0 +1,7 @@
+
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/zerops/python.svg b/apps/docs/static/img/recipes/zerops/python.svg
new file mode 100644
index 000000000..44915a4d5
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/python.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/zerops/qwik.svg b/apps/docs/static/img/recipes/zerops/qwik.svg
new file mode 100644
index 000000000..9ad975e7c
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/qwik.svg
@@ -0,0 +1,27 @@
+
+
diff --git a/apps/docs/static/img/recipes/zerops/react.svg b/apps/docs/static/img/recipes/zerops/react.svg
new file mode 100644
index 000000000..ea77a618d
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/react.svg
@@ -0,0 +1,9 @@
+
diff --git a/apps/docs/static/img/recipes/zerops/ruby.svg b/apps/docs/static/img/recipes/zerops/ruby.svg
new file mode 100644
index 000000000..59cf324fe
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/ruby.svg
@@ -0,0 +1,948 @@
+
+
+
+
\ No newline at end of file
diff --git a/apps/docs/static/img/recipes/zerops/rust.svg b/apps/docs/static/img/recipes/zerops/rust.svg
new file mode 100644
index 000000000..aa49a54ac
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/rust.svg
@@ -0,0 +1,4 @@
+
diff --git a/apps/docs/static/img/recipes/zerops/solid.svg b/apps/docs/static/img/recipes/zerops/solid.svg
new file mode 100644
index 000000000..e233e84c7
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/solid.svg
@@ -0,0 +1 @@
+
diff --git a/apps/docs/static/img/recipes/zerops/svelte.svg b/apps/docs/static/img/recipes/zerops/svelte.svg
new file mode 100644
index 000000000..4bf279659
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/svelte.svg
@@ -0,0 +1,20 @@
+
+
+
diff --git a/apps/docs/static/img/recipes/zerops/vue.svg b/apps/docs/static/img/recipes/zerops/vue.svg
new file mode 100644
index 000000000..a1d285eb2
--- /dev/null
+++ b/apps/docs/static/img/recipes/zerops/vue.svg
@@ -0,0 +1,2 @@
+
+
diff --git a/apps/docs/static/img/zcp/quickstart-cloud-ide-claude-code.jpg b/apps/docs/static/img/zcp/quickstart-cloud-ide-claude-code.jpg
new file mode 100644
index 000000000..038b66f7d
Binary files /dev/null and b/apps/docs/static/img/zcp/quickstart-cloud-ide-claude-code.jpg differ
diff --git a/apps/docs/static/img/zcp/quickstart-laravel-ai-agent-recipe.png b/apps/docs/static/img/zcp/quickstart-laravel-ai-agent-recipe.png
new file mode 100644
index 000000000..df9e15849
Binary files /dev/null and b/apps/docs/static/img/zcp/quickstart-laravel-ai-agent-recipe.png differ
diff --git a/apps/docs/static/img/zcp/quickstart-zcp-service-ready.png b/apps/docs/static/img/zcp/quickstart-zcp-service-ready.png
new file mode 100644
index 000000000..e3c641382
Binary files /dev/null and b/apps/docs/static/img/zcp/quickstart-zcp-service-ready.png differ
diff --git a/apps/docs/static/img/zcp/remote-setup-claude-code.jpg b/apps/docs/static/img/zcp/remote-setup-claude-code.jpg
new file mode 100644
index 000000000..3b6adf75f
Binary files /dev/null and b/apps/docs/static/img/zcp/remote-setup-claude-code.jpg differ
diff --git a/apps/docs/static/llms-full.txt b/apps/docs/static/llms-full.txt
index 5bebd6c4a..5bb32a4af 100644
--- a/apps/docs/static/llms-full.txt
+++ b/apps/docs/static/llms-full.txt
@@ -2,9 +2,13 @@
# Alpine > How To > Build Pipeline
+
Zerops provides a customizable build and runtime environment for your Alpine application.
+
## Add zerops.yaml to your repository
+
Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:
+
```yaml
zerops:
# define hostname of your service
@@ -13,45 +17,58 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: alpine@3.20
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
prepareCommands:
- sudo apk add --no-cache something
- curl something else
+
# OPTIONAL. Build your application
buildCommands:
- -
+ -
+
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles: app
+
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: some_file
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: alpine@3.20
+
# OPTIONAL. Sets the internal port(s) your app listens on:
ports:
# port number
- port: 8080
+
# OPTIONAL. Customize the runtime Alpine environment by installing additional
# dependencies to the base Alpine runtime environment.
prepareCommands:
- sudo apk add --no-cache something
- curl something else
+
# OPTIONAL. Run one or more commands each time a new runtime container
# is started or restarted. These commands are triggered before
# your Alpine application is started.
initCommands:
- rm -rf ./cache
+
# OPTIONAL. Your Alpine application start command
start: ./app
```
+
The top-level element is always `zerops`.
+
### Setup
+
The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:
+
```yaml
zerops:
# definition for app service
@@ -62,6 +79,7 @@ zerops:
deploy: ...
# required
run: ...
+
# definition for api service
- setup: api
# optional
@@ -71,11 +89,25 @@ zerops:
# required
run: ...
```
+
Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.
+
## Build pipeline configuration
+
### base
+
_REQUIRED._ Sets the base technology for the build environment.
+
Following options are available for Alpine builds:
+
+- `alpine@3.23`, `alpine@latest`
+- `alpine@3.22`
+- `alpine@3.21`
+- `alpine@3.20`
+- `alpine@3.19`
+- `alpine@3.18`
+- `alpine@3.17`
+
```yaml
zerops:
# hostname of your service
@@ -86,11 +118,17 @@ zerops:
base: alpine@3.20
...
```
- The base build environment contains {data.alpine.default}, Zerops command line tool, `git` and `wget`.
+
+
+ The base build environment contains {data.alpine.default}, [Zerops command line tool](/references/cli), `git` and `wget`.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -104,18 +142,27 @@ zerops:
- zsc add nodejs@latest
...
```
+
See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).
+
To customize your build environment use the [prepareCommands](#preparecommands) attribute.
+
:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::
+
### prepareCommands
+
_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.
+
The base build environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- [Zerops command line tool](/references/cli)
- `git` and `wget`
+
To install additional packages or tools add one or more prepare commands:
+
```yaml
zerops:
# hostname of your service
@@ -124,6 +171,7 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: alpine@3.20
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
prepareCommands:
@@ -131,20 +179,31 @@ zerops:
- curl something else
...
```
+
When the first build is triggered, Zerops will
+
1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order
+
The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.
+
:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/alpine/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### buildCommands
+
_OPTIONAL._ Defines build commands.
+
```yaml
zerops:
# hostname of your service
@@ -153,93 +212,136 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: alpine@3.20
+
# OPTIONAL. Build your application
buildCommands:
- -
+ -
...
```
+
Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.
+
Before the build commands are triggered the build container contains:
+
1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code
+
For detailed information about build commands, refer to the documentation for your specific technology (e.g., [Node.js](/nodejs/how-to/build-pipeline), [Go](/go/how-to/build-pipeline), [Python](/python/how-to/build-pipeline), etc.).
+
#### Run build commands as a single shell instance
+
Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.
+
```yaml
buildCommands:
- |
cd src
./build.sh
```
+
#### Run build commands as separate shell instances
+
When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.
+
```yaml
buildCommands:
- cd src
- ./build.sh
```
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/alpine/how-to/logs#build-log) to troubleshoot the error.
+
If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.
+
### deployFiles
-_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use `.deployignore` file.
+
+_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.
+
```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- app
```
+
Determines files or folders produced by your build, which should be deployed to your runtime service containers.
+
The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.
+
The files/folders will be placed into `/var/www` folder in runtime, e.g. `./src/assets/fonts` would result in `/var/www/src/assets/fonts`.
+
#### Examples
+
Deploys a folder, and a file from the project root directory:
+
```yaml
deployFiles:
- app
- file.txt
```
+
Deploys the whole content of the build container:
+
```yaml
deployFiles: .
```
+
Deploys a folder, and a file in a defined path:
+
```yaml
deployFiles:
- ./path/to/file.txt
- ./path/to/dir/
```
+
#### How to use a wildcard in the path
+
Zerops supports the `~` character as a wildcard for one or more folders in the path.
+
Deploys all `file.txt` files that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/file.txt
```
+
Deploys all folders that are located in any path that begins with `/path/to/`
+
```yaml
deployFiles: ./path/to/~/
```
+
Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/
```
+
:::note Example
By default, `./src/assets/fonts` deploys to `/var/www/src/assets/fonts`, keeping the full path. Adding `~`, like `./src/assets/~fonts`, shortens it to `/var/www/fonts`
:::
+
#### .deployignore
-Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as `.gitignore`.
+
+Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as [`.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format).
+
To ignore a specific file or directory path, start the pattern with a forward slash (`/`). Without the leading slash, the pattern will match files with that name in any directory.
+
:::tip
For consistency, it's recommended to configure both your `.gitignore` and `.deployignore` files with the same patterns.
:::
+
Examples:
+
```yaml title="zerops.yaml"
zerops:
- setup: app
build:
deployFiles: ./
```
+
```text title=".deployignore"
/src/file.txt
```
@@ -251,22 +353,33 @@ This example above ignores `file.txt` in ANY directory named `src`, such as:
- `/src/file.txt`
- `/folder2/folder3/src/file.txt`
- `/src/src/file.txt`
+
:::note
-`.deployignore` file also works with `zcli service deploy` command.
+`.deployignore` file also works with [`zcli service deploy`](/references/zcli/commands#deploy) command.
:::
+
### cache
+
_OPTIONAL._ Defines which files or folders will be cached for the next build.
+
```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```
+
The cache attribute helps optimize build times by preserving specified files between builds.
+
The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).
+
Learn more about the [build cache system](/features/build-cache) in Zerops.
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the build environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -275,6 +388,7 @@ zerops:
build:
base: alpine@3.20
…
+
# OPTIONAL. Defines the env variables for the build environment:
envVariables:
MODE: production
@@ -283,12 +397,26 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/alpine/how-to/env-variables) in Zerops.
+
## Runtime configuration
+
### base
+
_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Alpine version for your runtime.
+
Following options are available for Alpine builds:
+
+- `alpine@3.23`, `alpine@latest`
+- `alpine@3.22`
+- `alpine@3.21`
+- `alpine@3.20`
+- `alpine@3.19`
+- `alpine@3.18`
+- `alpine@3.17`
+
```yaml
zerops:
# hostname of your service
@@ -298,17 +426,24 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: alpine@3.20
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: alpine@3.20
...
```
+
+
The base runtime environment contains {data.alpine.default}, Zerops command line tool, `git` and `wget`.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -318,6 +453,7 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: alpine@3.20
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
@@ -327,29 +463,52 @@ zerops:
- zsc add nodejs@latest
...
```
+
See the full list of supported [run base environments](/zerops-yaml/base-list).
+
To customise your build environment use the `prepareCommands` attribute.
+
### ports
+
_OPTIONAL._ Specifies one or more internal ports on which your application will listen.
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
For example, to connect to an Alpine service with hostname = "app" and port = 8080 from another service of the same project, simply use `app:8080`. Read more about [how to access an Alpine service](/references/networking/internal-access#basic-service-communication).
+
Each port has following attributes:
-
- Parameter
- Description
-
- port
- Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
-
- protocol
- Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
-
- httpSupport
- Optional. httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of public access. httpSupport = true is available only in combination with the TCP protocol.
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
+
+
+
protocol
+
Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
+
+
+
httpSupport
+
Optional.httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). httpSupport = true is available only in combination with the TCP protocol.
+
+
+
+
### prepareCommands
+
_OPTIONAL._ Customises the Alpine runtime environment by installing additional dependencies or tools to the runtime base environment.
- The base Alpine environment contains {data.alpine.default}, Zerops command line tool and `git` and `wget`. To install additional packages or tools add one or more prepare commands:
+
+
+ The base Alpine environment contains {data.alpine.default}, [Zerops command line tool](/references/cli) and `git` and `wget`. To install additional packages or tools add one or more prepare commands:
+
+
```yaml
zerops:
# hostname of your service
@@ -357,6 +516,7 @@ zerops:
# ==== how to build your application ====
build:
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -366,26 +526,44 @@ zerops:
- curl something else
...
```
+
When the first deploy with a defined prepare attribute is triggered, Zerops will
+
1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order
+
:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/alpine/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.
+
#### Cache of your custom runtime environment
+
Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:
+
1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.
+
To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.
+
When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### Copy folders or files from your build container
- The prepare runtime container contains {data.alpine.default}, Zerops command line tool and `git` and `wget`.
+
+
+ The prepare runtime container contains {data.alpine.default}, [Zerops command line tool](/references/cli) and `git` and `wget`.
+
+
The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).
+
```yaml
zerops:
# hostname of your service
@@ -394,6 +572,7 @@ zerops:
build:
...
addToRunPrepare: ./runtime-config.yaml
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -403,15 +582,20 @@ zerops:
- curl something else
...
```
+
In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.
+
### initCommands
+
_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Run one or more commands each time a new runtime container
@@ -420,22 +604,35 @@ zerops:
initCommands:
- rm -rf ./cache
```
+
These commands are triggered in the runtime container before your Alpine application is started via the [start command](#start).
+
:::note
`run.initCommands` run in the `/var/www` directory.
:::
+
Use init commands to clean or initialise your application cache or similar operations.
+
:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/alpine/how-to/scaling) or when a runtime container is restarted).
+
Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::
+
#### Command exit code
+
If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/alpine/how-to/logs#runtime-log) to troubleshoot the error.
+
#### Single or separated shell instances
+
You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the runtime environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -450,56 +647,82 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/alpine/how-to/env-variables) in Zerops.
+
### start
+
_OPTIONAL._ Defines the start command for your Alpine application.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Your Alpine application start command
start: ./app
```
+
### health check
+
_OPTIONAL._ Defines a health check.
+
`healthCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the health check to request a local URL using a HTTP GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Your Alpine application start command
start: ./app
+
# OPTIONAL. Define a health check with a HTTP GET request option.
# Configures the check on http://127.0.0.1:80/status
healthCheck:
@@ -507,30 +730,47 @@ zerops:
port: 80
path: /status
```
+
#### exec
+
Configures the health check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
Defines a local command to be run.
- The command has access to the same environment variables as your Alpine application.
+
+ The command has access to the same [environment variables](/alpine/how-to/create#set-secret-environment-variables) as your Alpine application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Alpine application start command
start: ./app
+
# OPTIONAL. Define a health check with a shell command.
healthCheck:
exec:
@@ -539,13 +779,18 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
### crontab
+
_OPTIONAL._ Defines cron jobs.
+
Setup cron jobs in the following format:
+
```yaml
zerops:
# define hostname of your service
- setup: app
+
# ==== how to run your application ====
run:
crontab:
@@ -554,40 +799,62 @@ zerops:
# REQUIRED. Sets the interval time to execute:
timing: "0 * * * *"
```
+
Read more about setting up [cron](/zerops-yaml/cron) in Zerops.
+
## Deploy configuration
+
### readiness check
+
_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/alpine/how-to/deploy-process#readiness-checks) in Zerops.
+
`readinessCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the readiness check to request a local URL using a http GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -596,30 +863,48 @@ zerops:
httpGet:
port: 80
path: /status
+
# ==== how to run your application ====
run: ...
```
+
Read more about how the [readiness check works](/alpine/how-to/deploy-process#readiness-checks) in Zerops.
+
#### exec
+
Configures the readiness check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
Defines a local command to be run.
- The command has access to the same environment variables as your Alpine application.
+
+ The command has access to the same [environment variables](/alpine/how-to/create#set-secret-environment-variables) as your Alpine application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -631,80 +916,123 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
Read more about how the [readiness check works](/alpine/how-to/deploy-process#readiness-checks) in Zerops.
----------------------------------------
# Alpine > How To > Build Process
-
+
## Build process overview
+
Zerops starts a temporary build container and performs the following actions:
+
1. **Installs the build environment** - Sets up base system and runtime
2. **Downloads your application source code** - From [GitHub ↗](https://www.github.com), [GitLab ↗](https://www.gitlab.com) or via [Zerops CLI](/references/cli)
3. **Optionally customizes the build environment** - Runs prepare commands if configured
4. **Runs the build commands** - Executes your build process
5. **Uploads the application artifact** - Stores build output to internal Zerops storage
6. **Caches selected files** - Preserves specified files for faster future builds
+
The build container is automatically deleted after the build has finished or failed.
+
## Build configuration
-Configure your build process in your `zerops.yaml` file according to the full build & deploy pipeline guide.
+
+Configure your build process in your `zerops.yaml` file according to the pipeline guide.
+
## Build environment
+
### Default build environment
+
The default build environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- [zCLI](/references/cli), Zerops command line tool
--
+-
+
### Customize build environment
-To install additional packages or tools, add one or more build.prepareCommands to your `zerops.yaml`.
+
+To install additional packages or tools, add one or more to your `zerops.yaml`.
+
:::info
The application code is available in the `/build/source` folder in your build container before the prepare commands are triggered. This allows you to use any file from your application code in your prepare commands (e.g. a configuration file).
:::
+
### Build hardware resources
+
All runtime services use the same hardware resources for build containers:
-
- HW resource
- Minimum
- Maximum
-
- CPU cores
- 1
- 5
-
- RAM
- 8 GB
- 8 GB
-
- Disk
- 1 GB
- 100 GB
-
+
+
+
+
+
HW resource
+
Minimum
+
Maximum
+
+
+
+
+
CPU cores
+
1
+
5
+
+
+
RAM
+
8 GB
+
8 GB
+
+
+
Disk
+
1 GB
+
100 GB
+
+
+
+
Build containers start with minimum resources and scale vertically up to maximum capacity as needed.
+
### Build time limit
+
The time limit for the whole build pipeline is **1 hour**. After 1 hour, Zerops will terminate the build pipeline and delete the build container.
+
:::info
Build container resources are not charged separately. Limited build time is included in your [project core plan](/company/pricing#project-core-plans), with additional build time available if needed.
:::
+
## Troubleshooting builds
+
:::tip Advanced troubleshooting
For complex build issues that require investigation, you can enable [debug mode](/features/debug-mode) to pause the build process at specific points and inspect the build container state interactively.
:::
+
### Build and prepare command failures
-If any build command or prepare command fails (returns non-zero exit code), the build is canceled. Check the build log to troubleshoot the error.
+
+If any or fails (returns non-zero exit code), the build is canceled. Check the to troubleshoot the error.
+
### Build cache issues
+
If you encounter unexpected build behavior or dependency issues, the problem might be related to cached build data. While Zerops maintains the build cache to speed up deployments, sometimes you may need to start fresh.
+
To invalidate the build cache:
+
1. Go to your service detail in Zerops GUI
2. Choose **Pipelines & CI/CD Settings** from the left menu
3. Click on the **Invalidate build cache** button
+
This will force Zerops to run the next build clean, including all prepare commands.
+
Learn more about [build cache behavior](/features/build-cache).
+
## More resources
+
For more details about the build and deploy pipeline, including how to cancel builds and manage application versions, see the [general pipeline documentation](/features/pipeline).
+
## Next steps
-- Understand the deployment process
-- Learn how to customize the runtime environment
-- Explore build and runtime logs
+
+- Understand the
+- Learn how to
+- Explore
----------------------------------------
@@ -716,35 +1044,60 @@ For more details about the build and deploy pipeline, including how to cancel bu
# Alpine > How To > Create
+
Zerops provides a Alpine runtime service with extensive build support. Alpine runtime is highly scalable and customisable to suit both development and production.
+
## Create Alpine service using Zerops GUI
+
First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Alpine service:
+
+[Video: /vids/services/golang.webm](/vids/services/golang.webm)
+
### Choose Alpine version
+
Following Alpine versions are currently supported:
+
:::info
You can [change](/alpine/how-to/upgrade) the major version at any time later.
:::
+
### Set a hostname
+
Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.
+
#### Limitations:
+
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::
+
### Set secret environment variables
+
Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.
+
Setting the secret environment variables is optional. You can set them later in Zerops GUI.
+
Read more about [different types of env variables](/alpine/how-to/env-variables#service-env-variables) in Zerops.
+
## Create Alpine service using zCLI
+
zCLI is the Zerops command-line tool. To create a new Alpine service via the command-line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/alpine/how-to/create#create-a-project-description-file)
3. [Create a project with a Alpine and PostgreSQL service](#full-example)
+
### Create a project description file
+
Zerops uses a yaml format to describe the project infrastructure.
+
#### Basic example:
+
Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -765,13 +1118,18 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes your future project infrastructure. The project will contain one Alpine service with default [auto scaling](/alpine/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/alpine/how-to/build-pipeline#ports). Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
#### Full example:
+
Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:
+
```yaml
# basic project data
project:
@@ -816,98 +1174,143 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain an Alpine service and a [PostgreSQL](/postgresql/overview) service.
+
Alpine service with "app" hostname, the internal port(s) the service listens on will be defined later in the zerops.yaml. Alpine service will run with a custom vertical and horizontal scaling. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
hostname
+
The unique service identifier.
-
+
The hostname of the new database will be set to the `hostname` value.
-
- Limitations:
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+ Limitations:
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
type
+
Specifies the service type and version.
-
+
See what [Alpine service types](/references/import-yaml/type-list#runtime-services) are currently supported.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto scaling parameters.
-
+
+
+
+
verticalAutoscaling
+
+ Optional. Defines [custom vertical auto scaling parameters](/alpine/how-to/create#set-auto-scaling-configuration).
+
All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
- minContainers
-
- Optional. Default = 1. Defines the minimum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
- cpuMode
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
- minCpu/maxCpu
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
- minRam/maxRam
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
- minDisk/maxDisk
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
minContainers
+
+ Optional. Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/alpine/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- maxContainers
-
- Defines the maximum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
maxContainers
+
+ Defines the maximum number of containers for [horizontal autoscaling](/alpine/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- envSecrets
-
- Optional. Defines one or more secret env variables as a key value map. See env variable restrictions.
-
+
+
+
+
envSecrets
+
+ Optional. Defines one or more secret env variables as a key value map. See env variable [restrictions](/alpine/how-to/env-variables#env-variable-restrictions).
+
+
+
+
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add Alpine service to an existing project
+
#### Example:
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -928,65 +1331,90 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Alpine service version 1 with default [auto scaling](/alpine/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the import.yaml file is 100 kB.
+
----------------------------------------
# Alpine > How To > Customize Runtime
-System packages: Install any packages you need via apk, such as imagemagick, ffmpeg, or chromium',
- 'Specific language versions: Install versions of Go, Node.js, PHP, Python, or other runtimes that are not available as dedicated Zerops services (e.g., older or cutting-edge versions)',
- 'Custom binaries: Add compiled binaries or tools not available in the default repositories',
- 'Development tools: Include debugging tools, profilers, or other utilities',
- 'Specific libraries: Install dependencies required by your application'
-]} />
+
## Build Custom Runtime Images
+
Zerops allows you to build custom runtime images (CRI) when the default base runtime images don't meet your application's requirements. This is an optional phase in the [build and deploy pipeline](/features/pipeline#runtime-prepare-phase-optional).
+
Alpine is a versatile base for running anything not explicitly offered as a dedicated Zerops runtime. You can install any packages and tools you need, treating it as a clean OS to customize however you want.
+
It is also a great option when you need a specific version of a technology (like Go, Node.js, or PHP) that Zerops doesn't support by default—whether it's an older version for legacy projects or a newer release not yet available.
+
## Configuration
+
### Default Runtime Environment
+
The default runtime environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- [zCLI](/references/cli)
--
+-
+
### When You Need a Custom Runtime Image
+
Since Alpine serves as a general-purpose base, you'll likely want to customize it for your specific use case. Common scenarios include:
+
:::important
You should not include your application code in the custom runtime image, as your built/packaged code is deployed automatically into fresh containers.
:::
+
Here are examples of configuring custom runtime images in your `zerops.yml`:
+
### Basic Setup
+
### Using Build Files in Runtime Preparation
+
For complete configuration details, see the [runtime prepare phase configuration guide](/features/pipeline#configuration).
+
## Process and Caching
+
### How Runtime Prepare Works
The runtime prepare process follows the same steps for all runtimes. See [how runtime prepare works](/features/pipeline#how-it-works) for the complete process details.
+
### Caching Behavior
Zerops caches custom runtime images to optimize deployment times. Learn about [custom runtime image caching](/features/pipeline#custom-runtime-image-caching) including when images are cached and reused.
+
### Build Management
For information about managing builds and deployments, see [managing builds and deployments](/features/pipeline#manage-builds-and-deployments).
+
:::warning
Shared storage mounts are not available during the runtime prepare phase.
:::
+
## Troubleshooting
-If your `prepareCommands` fail, check the prepare runtime log for specific error messages.
+
+If your `prepareCommands` fail, check the for specific error messages.
----------------------------------------
@@ -1040,26 +1468,54 @@ If your `prepareCommands` fail, check the prepare runtime log for specific error
# Alpine > Overview
+
[Alpine Linux ↗](https://alpinelinux.org/) is a lightweight, security-oriented Linux distribution based on musl libc and busybox, known for its small footprint and efficiency.
+
Alpine services in Zerops provide a minimal base environment for running applications built with technologies that aren't officially supported by Zerops, or for custom setups requiring full control over the runtime environment while keeping resource usage low.
+
:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::
+
## Feature Highlights
+
+- [Create Alpine service](/alpine/how-to/create) — Start with creating an Alpine service using GUI or zCLI.
+- [zerops.yaml](/alpine/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to configure your own app.
+- [Scaling configuration](/alpine/how-to/scaling) — Set up scaling of your Alpine service so that it runs smoothly while using only necessary resources.
+
{" "}
+
+- [Customize build environment](/alpine/how-to/build-process#customize-build-environment)
+- [Customize runtime environment](/alpine/how-to/customize-runtime)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you built something that others might find useful? Don't hesitate to share your knowledge!
+
+- [FAQ](/alpine/faq) — Most common questions in one place.
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Bun > How To > Build Pipeline
+
Zerops provides a customizable build and runtime environment for your Bun application.
+
## Add zerops.yaml to your repository
+
Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:
+
```yaml
zerops:
# define hostname of your service
@@ -1068,51 +1524,65 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: bun@latest
+
# OPTIONAL. Set the operating system for the build environment.
# os: ubuntu
+
# OPTIONAL. Customise the build environment by installing additional packages
# or tools to the base build environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Build your application
buildCommands:
- bun i
- bun run build
+
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- dist
- package.json
- node_modules
+
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: node_modules
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: bun@latest
+
# OPTIONAL. Sets the internal port(s) your app listens on:
ports:
# port number
- port: 3000
+
# OPTIONAL. Customise the runtime Bun environment by installing additional
# dependencies to the base Bun runtime environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Run one or more commands each time a new runtime container
# is started or restarted. These commands are triggered before
# your Bun application is started.
# initCommands:
# - rm -rf ./cache
+
# REQUIRED. Your Bun application start command
start: bun start
```
+
The top-level element is always `zerops`.
+
### Setup
+
The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:
+
```yaml
zerops:
# definition for app service
@@ -1123,6 +1593,7 @@ zerops:
deploy: ...
# required
run: ...
+
# definition for api service
- setup: api
# optional
@@ -1132,11 +1603,23 @@ zerops:
# required
run: ...
```
+
Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.
+
## Build pipeline configuration
+
### base
+
_REQUIRED._ Sets the base technology for the build environment.
+
Following options are available for Bun builds:
+
+- `bun@1.3.9`, `bun@1.3`, `bun@latest`
+- `bun@1.2.2`, `bun@1.2`
+- `bun@nightly`
+- `bun@canary`
+- `bun@1.1.34`, `bun@1.1(Ubuntu only)`
+
```yaml
zerops:
# hostname of your service
@@ -1147,14 +1630,20 @@ zerops:
base: bun@latest
...
```
+
+
The base build environment contains {data.alpine.default}, the selected
major version of Bun,
- Zerops command line tool, `npm`,
+ [Zerops command line tool](/references/cli), `npm`,
`yarn`, `git` and `npx` tools.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -1168,34 +1657,52 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).
+
To customise your build environment use the [prepareCommands](build-pipeline#preparecommands) attribute.
+
:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::
+
### os
+
_OPTIONAL._ Sets the operating system for the build environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customised.
:::
+
:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::
+
### prepareCommands
+
_OPTIONAL._ Customises the build environment by installing additional dependencies or tools to the base build environment.
+
The base build environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- selected version of Bun defined in the [base](build-pipeline#base) attribute
- [Zerops command line tool](/references/cli)
- `npm`, `yarn`, `git` and `npx` tools
+
To install additional packages or tools add one or more prepare commands:
+
```yaml
zerops:
# hostname of your service
@@ -1204,6 +1711,7 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: bun@latest
+
# OPTIONAL. Customise the build environment by installing additional packages
# or tools to the base build environment.
prepareCommands:
@@ -1211,20 +1719,31 @@ zerops:
- curl something else
...
```
+
When the first build is triggered, Zerops will
+
1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order
+
The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.
+
:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### buildCommands
+
_OPTIONAL._ Defines build commands.
+
```yaml
zerops:
# hostname of your service
@@ -1233,42 +1752,59 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: bun@latest
+
# OPTIONAL. Build your application
buildCommands:
- bun i
- bun run build
...
```
+
Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.
+
Before the build commands are triggered the build container contains:
+
1. base environment defined by the [base](build-pipeline#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](build-pipeline#preparecommands) attribute
3. your application code
+
#### Run build commands as a single shell instance
+
Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.
+
```yaml
buildCommands:
- |
bun i
bun run build
```
+
#### Run build commands as a separate shell instances
+
When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.
+
```yaml
buildCommands:
- bun i
- bun run build
```
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.
+
```yaml
buildCommands:
- bun i --verbose
- bun run build
```
+
If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.
+
### deployFiles
-_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use `.deployignore` file.
+
+_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.
+
```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
@@ -1277,56 +1813,81 @@ deployFiles:
- package.json
- node_modules
```
+
Determines files or folders produced by your build, which should be deployed to your runtime service containers.
+
The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.
+
The files/folders will be placed into `/var/www` folder in runtime, e.g. `./src/assets/fonts` would result in `/var/www/src/assets/fonts`.
+
#### Examples
+
Deploys a folder, and a file from the project root directory:
+
```yaml
deployFiles:
- dist
- package.json
```
+
Deploys the whole content of the build container:
+
```yaml
deployFiles: .
```
+
Deploys a folder, and a file in a defined path:
+
```yaml
deployFiles:
- ./path/to/file.txt
- ./path/to/dir/
```
+
#### How to use a wildcard in the path
+
Zerops supports the `~` character as a wildcard for one or more folders in the path.
+
Deploys all `file.txt` files that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/file.txt
```
+
Deploys all folders that are located in any path that begins with `/path/to/`
+
```yaml
deployFiles: ./path/to/~/
```
+
Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/
```
+
:::note Example
By default, `./src/assets/fonts` deploys to `/var/www/src/assets/fonts`, keeping the full path. Adding `~`, like `./src/assets/~fonts`, shortens it to `/var/www/fonts`
:::
#### .deployignore
-Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as `.gitignore`.
+
+Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as [`.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format).
+
To ignore a specific file or directory path, start the pattern with a forward slash (`/`). Without the leading slash, the pattern will match files with that name in any directory.
+
:::tip
For consistency, it's recommended to configure both your `.gitignore` and `.deployignore` files with the same patterns.
:::
+
Examples:
+
```yaml title="zerops.yaml"
zerops:
- setup: app
build:
deployFiles: ./
```
+
```text title=".deployignore"
/src/file.txt
```
@@ -1338,22 +1899,33 @@ This example above ignores `file.txt` in ANY directory named `src`, such as:
- `/src/file.txt`
- `/folder2/folder3/src/file.txt`
- `/src/src/file.txt`
+
:::note
-`.deployignore` file also works with `zcli service deploy` command.
+`.deployignore` file also works with [`zcli service deploy`](/references/zcli/commands#deploy) command.
:::
+
### cache
+
_OPTIONAL._ Defines which files or folders will be cached for the next build.
+
```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```
+
The cache attribute helps optimize build times by preserving specified files between builds.
+
The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).
+
Learn more about the [build cache system](/features/build-cache) in Zerops.
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the build environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -1362,6 +1934,7 @@ zerops:
build:
base: bun@latest
…
+
# OPTIONAL. Defines the env variables for the build environment:
envVariables:
NODE_ENV: production
@@ -1370,12 +1943,24 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](env-variables) in Zerops.
+
## Runtime configuration
+
### base
+
_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Bun version for your runtime.
+
Following options are available for Bun runtimes:
+
+- `bun@1.3.9`, `bun@1.3`, `bun@latest`
+- `bun@1.2.2`, `bun@1.2`
+- `bun@nightly`
+- `bun@canary`
+- `bun@1.1.34`, `bun@1.1(Ubuntu only)`
+
```yaml
zerops:
# hostname of your service
@@ -1385,18 +1970,25 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: bun@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: bun@latest
...
```
+
+
The base runtime environment contains {data.alpine.default}, the
selected major version of Bun, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -1406,6 +1998,7 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: bun@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
@@ -1415,36 +2008,58 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [run base environments](/zerops-yaml/base-list).
+
To customise your build environment use the `prepareCommands` attribute.
+
### os
+
_OPTIONAL._ Sets the operating system for the runtime environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customised.
:::
+
### ports
+
_OPTIONAL._ Specifies one or more internal ports on which your application will listen.
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
For example, to connect to a Bun service with hostname = "app" and port = 3000 from another service of the same project, simply use `app:3000`. Read more about [how to access a Bun service](/features/access).
+
Each port has following attributes:
+
| parameter | description |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| port | Defines the port number. You can set any port number between _10_ and _65435_. Ports outside this interval are reserved for internal Zerops systems. |
| protocol | **Optional.** Defines the protocol. Allowed values are `TCP` or `UDP`. Default value is `TCP`. |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |
+
### prepareCommands
+
_OPTIONAL._ Customises the Bun runtime environment by installing additional dependencies or tools to the runtime base environment.
+
+
The base Bun environment contains {data.alpine.default} the selected
- major version of Bun, Zerops command line tool and `npm`, `yarn`, `git` and `npx` tools. To install
+ major version of Bun, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools. To install
additional packages or tools add one or more prepare commands:
+
+
```yaml
zerops:
# hostname of your service
@@ -1452,6 +2067,7 @@ zerops:
# ==== how to build your application ====
build:
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -1461,27 +2077,45 @@ zerops:
- curl something else
...
```
+
When the first deploy with a defined prepare attribute is triggered, Zerops will
+
1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](build-pipeline#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order
+
:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.
+
#### Cache of your custom runtime environment
+
Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:
+
1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.
+
To invalidate the custom runtime cache go to `yyy`
+
When the custom runtime cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### Copy folders or files from your build container
- The prepare runtime container contains {data.alpine.default}, the selected major version of Bun, Zerops command line tool and `npm`,
+
+
+ The prepare runtime container contains {data.alpine.default}, the selected major version of Bun, [Zerops command line tool](/references/cli) and `npm`,
`yarn`, `git` and `npx` tools.
+
+
The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).
+
```yaml
zerops:
# hostname of your service
@@ -1490,6 +2124,7 @@ zerops:
build:
...
addToRunPrepare: ./runtime-config.yaml
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -1499,15 +2134,20 @@ zerops:
- curl something else
...
```
+
In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.
+
### initCommands
+
_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Run one or more commands each time a new runtime container
@@ -1516,22 +2156,35 @@ zerops:
initCommands:
- rm -rf ./cache
```
+
These commands are triggered in the runtime container before your Bun application is started via the [start command](build-pipeline#start).
+
:::note
`run.initCommands` run in the `/var/www` directory.
:::
+
Use init commands to clean or initialise your application cache or similar operations.
+
:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the [horizontal scaling](scaling) or when a runtime container is restarted).
+
Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](build-pipeline#preparecommands-1) attribute instead.
:::
+
#### Command exit code
+
If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](logs#runtime-log) to troubleshoot the error.
+
#### Single or separated shell instances
+
You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the runtime environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -1546,57 +2199,84 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](env-variables) in Zerops.
+
### start
+
_REQUIRED._ Defines the start command for your Bun application.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Bun application start command
start: bun start
```
+
We recommend starting your Bun application using `bun start`.
+
### health check
+
_OPTIONAL._ Defines a health check.
+
`healthCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the health check to request a local URL using a HTTP GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Bun application start command
start: bun start
+
# OPTIONAL. Define a health check with a HTTP GET request option.
# Configures the check on http://127.0.0.1:80/status
healthCheck:
@@ -1604,25 +2284,32 @@ zerops:
port: 80
path: /status
```
+
#### exec
+
Configures the health check to run a local command.
Following attributes are available:
+
| Parameter | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](create#set-secret-environment-variables) as your Bun application.
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below. |
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Bun application start command
start: bun start
+
# OPTIONAL. Define a health check with a shell command.
healthCheck:
exec:
@@ -1631,13 +2318,18 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
### crontab
+
_OPTIONAL._ Defines cron jobs.
+
Setup cron jobs in the following format:
+
```yaml
zerops:
# define hostname of your service
- setup: app
+
# ==== how to run your application ====
run:
crontab:
@@ -1646,14 +2338,23 @@ zerops:
# REQUIRED. Sets the interval time to execute:
timing: "0 * * * *"
```
+
Read more about setting up [cron](/zerops-yaml/cron) in Zerops.
+
## Deploy configuration
+
### readiness check
+
_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](deploy-process#readiness-checks) in Zerops.
+
`readinessCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the readiness check to request a local URL using a http GET method.
+
Following attributes are available:
+
@@ -1683,13 +2384,16 @@ If your application requires a https request, set scheme: https
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -1698,25 +2402,33 @@ zerops:
httpGet:
port: 80
path: /status
+
# ==== how to run your application ====
run: ...
```
+
Read more about how the [readiness check works](deploy-process#readiness-checks) in Zerops.
+
#### exec
+
Configures the readiness check to run a local command.
Following attributes are available:
+
| Parameter | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](create#set-secret-environment-variables) as your Bun application.
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below. |
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -1728,8 +2440,10 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
Read more about how the [readiness check works](deploy-process#readiness-checks) in Zerops.
+
----------------------------------------
# Bun > How To > Build Process
@@ -1746,34 +2460,58 @@ Read more about how the [readiness check works](deploy-process#readiness-checks)
# Bun > How To > Create
+
Zerops provides a powerful Bun runtime service with extensive build support. The Bun runtime is highly scalable and customizable to suit your development and production needs. With just a few clicks or commands, you can have a production-ready Bun environment up and running in no time.
+
## Create a Bun service using Zerops GUI
+
First, set up a project in the Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu under the **Services** section. From there, you can add a new Bun service:
+
+[Video: /vids/services/bun.webm](/vids/services/bun.webm)
+
### Choose a Bun version
+
Zerops supports the following Bun versions:
+
:::info
You can easily [upgrade](upgrade) the major version at any time later.
:::
+
### Set a hostname
+
Enter a unique service identifier like "app", "cache", "gui", etc. Duplicate services with the same name within the same project are not allowed.
+
#### Limitations:
+
- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::
+
### Set secret environment variables
+
Add environment variables with sensitive data, such as passwords, tokens, salts, certificates, etc. These will be securely saved inside Zerops and added to your runtime service upon start.
+
Setting secret environment variables is optional. You can always set them later in the Zerops GUI.
+
Read more about the [different types of environment variables](env-variables#service-env-variables) in Zerops.
+
## Create a Bun service using zCLI
+
zCLI is the Zerops command-line tool. To create a new Bun service via the command line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](create#create-a-project-description-file)
3. [Create a project with a Bun and PostgreSQL service](#full-example)
+
### Create a project description file
+
Zerops uses a YAML format to describe the project infrastructure.
+
#### Basic example:
+
Create a directory called `my-project`. Inside the `my-project` directory, create a `description.yaml` file with the following content:
```yaml
# basic project data
@@ -1795,13 +2533,18 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes your future project infrastructure. The project will contain one Bun service with default [auto scaling](scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](build-pipeline#ports). Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
#### Full example:
+
Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:
+
```yaml
# basic project data
project:
@@ -1846,102 +2589,170 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain a Bun service and a [PostgreSQL](/postgresql/overview) service.
+
Bun service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](build-pipeline#ports). Bun service will run with custom vertical and horizontal scaling. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
+
| Parameter | Description | Limitations |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **name** | The name of the new project. Duplicates are allowed. | |
| **description** | **Optional.** Description of the new project. | Maximum 255 characters. |
| **tags** | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |
| **tags** | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |
+
At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Bun and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
+ hostname
+
+
The unique service identifier.
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
+ type
+
+
Specifies the service type and version.
-
+
See what [Bun service types](/references/import-yaml/type-list#runtime-services) are currently supported.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto scaling parameters.
+
+
+
+
+ verticalAutoscaling
+
+
+ Optional. Defines [custom vertical auto scaling parameters](/bun/how-to/scaling#configure-scaling).
+
All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
- minContainers
-
- Optional. Default = 1. Defines the minimum number of containers
- for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
+ - cpuMode
+
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
+ - minCpu/maxCpu
+
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
+ - minRam/maxRam
+
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
+ - minDisk/maxDisk
+
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
+ minContainers
+
+
+ Optional. Default = 1. Defines the minimum number of containers
+ for [horizontal autoscaling](/bun/how-to/scaling#configure-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- maxContainers
-
- Defines the maximum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
+ maxContainers
+
+
+ Defines the maximum number of containers for [horizontal autoscaling](/bun/how-to/scaling#configure-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- envSecrets
-
- Optional. Defines one or more secret env variables as a key value
- map. See env variable restrictions.
-
+
+
+
+
+ envSecrets
+
+
+ Optional. Defines one or more secret env variables as a key value
+ map. See env variable [restrictions](env-variables#env-variable-restrictions).
+
+
+
+
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add Bun service to an existing project
+
#### Example:
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -1962,33 +2773,37 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Bun service with default [auto scaling](scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the import.yaml file is 100 kB.
----------------------------------------
# Bun > How To > Customize Runtime
-System packages for processing: When your app processes images, videos, or files (requiring packages like sudo apk add imagemagick)',
- 'Global Bun tools: When you need CLI tools or utilities available system-wide',
- 'Native dependencies: When your Bun packages require system libraries that aren\'t in the default environment',
- 'Different base OS: When you need Ubuntu instead of Alpine for specific compatibility requirements'
-]} />
+
----------------------------------------
@@ -2042,78 +2857,140 @@ System packages for processing: When your app processes images, videos, or files
# Bun > Overview
+
[Bun ↗](https:/bun.org/en) is an asynchronous event-driven JavaScript runtime, which is designed to build scalable network applications.
+
As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-bun), a **_recipe_**, containing the most simple Bun web application. The repo will be used as a source from which the app will be built.
- This is the most bare-bones example of Bun app running in Zerops — as few libraries as possible,
+
+### 🚀 Feel free to deploy the recipe yourself
+
+This is the most bare-bones example of Bun app running in Zerops — as few libraries as possible,
just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.
-
+
+ [Deploy "bun" recipe on Zerops](https://app.zerops.io/recipe/?lf=bun)
+
1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
+
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-bun/blob/main/zerops-project-import.yaml)):
+
```yaml
project:
name: recipe-bun
tags:
- zerops-recipe
+
services:
- hostname: api
type: bun@1.1
enableSubdomainAccess: true
buildFromGit: https://github.com/zeropsio/recipe-bun
+
- hostname: db
type: postgresql@16
mode: NON_HA
priority: 1
```
+
3. Click on **Import project** and wait until all pipelines have finished.
+
**That's it, your application is now up and running! :star: Let's check it works:**
+
1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://api-806-3000.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see
+
```
{"message":"This is a simple, basic Bun application running in Zerops.io,\n each request adds an entry to the PostgreSQL database and returns a count.\n See the source repository (https://github.com/zeropsio/recipe-bun) for more information.","newEntry":"dfd1e873-bfc8-4f36-af07-e32561820b93","count":"1"}
```
+
:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::
+
## How to start
+
It doesn't matter whether it's your first curious introduction to Zerops, you have already mastered the basics and are looking for a tiny detail or inspiration. Below, choose a section that fits your needs:
+
+- [Care for details?](/bun/how-to/create) — Dive in all Zerops has to offer for your Bun application.
+- [Bun recipes](https://github.com/zeropsio?q=Bun&type=all&language=&sort=) — Get inspired by already existing repositories, ready to be imported to Zerops.
+
## Feature Highlights
+
+- [Create Bun service](/bun/how-to/create) — Start with creating a Bun service using GUI or zCLI.
+- [Zerops.yaml](/bun/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
+- [Scaling configuration](/bun/how-to/scaling) — Set up scaling of your Bun application so that it runs smoothly while using only necessary resources.
+
{" "}
+
+- [Customize build environment](/bun/how-to/build-process#customize-build-environment)
+- [Customize runtime environment](/bun/how-to/customize-runtime)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Clickhouse > Overview
+
Zerops provides a fully managed [ClickHouse](https://clickhouse.com/) columnar database optimized for blazing-fast analytical queries on massive datasets, making it ideal for data warehousing and real-time analytics applications.
+
## Supported Versions
+
Currently supported ClickHouse version:
+
Import configuration version:
+
+- `clickhouse@25.3`
+
## Service Configuration
+
Our ClickHouse implementation features optimized default settings designed for analytical workloads and data warehousing use cases.
+
### Resource Allocation
+
Zerops automatically allocates resources to your ClickHouse service based on demand within the limits defined in your [automatic scaling configuration](/features/scaling).
+
## High Availability and Deployment Modes
+
:::important
Deployment mode is selected during service creation and cannot be changed later.
:::
+
### High-Availability (HA) Setup
+
The recommended solution for production workloads and mission-critical analytics:
+
* **3 data nodes** with automatic monitoring, repairs, and replication factor of 3
* **Default cluster name:** `zerops` (currently 1 shard with 3 replicas)
+
#### Replication Configuration
+
The `Replicated` database engine handles replication automatically, but there are specific requirements you need to follow:
+
**For Database Operations**
Use this configuration when creating/managing databases:
+
```sql
CREATE DATABASE uk ON CLUSTER '{cluster}'
ENGINE = Replicated('/clickhouse/databases/{uuid}', '{shard}', '{replica}');
```
+
**For Table Operations**
Use `ENGINE = ReplicatedMergeTree` when creating tables (without the `ON CLUSTER '{cluster}'` clause):
+
```sql
CREATE TABLE uk.uk_price_paid
(
@@ -2133,11 +3010,14 @@ CREATE TABLE uk.uk_price_paid
county LowCardinality(String)
) ENGINE = ReplicatedMergeTree ORDER BY (postcode1, postcode2, addr1, addr2);
```
+
For more details see:
- https://clickhouse.com/docs/engines/database-engines/replicated
- https://clickhouse.com/docs/engines/table-engines/mergetree-family/replication
- https://clickhouse.com/docs/sql-reference/distributed-ddl
+
You can use other `Replicated*` engines from the MergeTree family. Replication is only supported for tables in the MergeTree family:
+
* `ReplicatedMergeTree`
* `ReplicatedSummingMergeTree`
* `ReplicatedReplacingMergeTree`
@@ -2145,102 +3025,153 @@ You can use other `Replicated*` engines from the MergeTree family. Replication i
* `ReplicatedCollapsingMergeTree`
* `ReplicatedVersionedCollapsingMergeTree`
* `ReplicatedGraphiteMergeTree`
+
User management (users, grants, etc.) is replicated by Keeper by default. The `ON CLUSTER '{cluster}'` clause is not needed when creating/deleting users or changing grants.
-The default `` database follows these practices. If you don't follow these recommendations, it is possible you will face issues in case of fail and repair scenario.
+
+The default `` database follows these practices. If you don't follow these recommendations, it is possible you will face issues in case of fail and repair scenario.
+
### Single Container Installation
+
Suitable for development and testing environments:
+
* Consists of 1 ClickHouse node
* Lower resource requirements
* No automatic replication
+
:::warning
Use for development purposes or non-critical data only. **Make sure to have backups enabled** if using in production, as you can lose your data due to container volatility.
:::
+
## Network Access & Protocols
+
Zerops automatically configures secure authentication for your ClickHouse service.
+
### Default Database
-Zerops creates a default database with the same name as your service hostname (``) during service creation.
+Zerops creates a default database with the same name as your service hostname (``) during service creation.
+
### Default Users
+
#### `zerops` User
* Created automatically upon service creation
* Has privileges for the default database
* Password available as environment variable `password`
+
#### `super` User
* Administrative user for cluster management
* Can create new databases, users, and manage permissions
* Password available as environment variable `superUserPassword`
+
### Access Methods
+
Services within the same project can access ClickHouse directly using:
```
-:
+:
```
+
For HA cluster setups, you can also access specific data nodes:
```
-node-stable-.db..zerops:
+node-stable-<1..3>.db..zerops:
```
+
For external access, use `zcli` VPN to connect using the same connection strings.
+
ClickHouse offers multiple interfaces for different use cases:
+
#### Native TCP Protocol
**Port:** `9000` (Environment variable: `port` or `portNative`)
+
Optimal for high-performance applications and ClickHouse-native clients.
+
More about it in [official ClickHouse docs](https://clickhouse.com/docs/interfaces/tcp).
+
#### HTTP/HTTPS Interface
**Port:** `8123` (Environment variable: `portHttp`)
+
Ideal for web applications and REST API integrations.
+
It is also possible to setup HTTPS domain access or enable subdomain for access from outside the project. Then you can access the database using following URL:
- `https://clickhouse.my-awesome-domain.tld`
- JDBC connection string example (use `ssl=true&sslmode=NONE` options):
`jdbc:clickhouse:https://clickhouse.my-awesome-domain.tld:443/?ssl=true&sslmode=NONE`
+
More about it in [official ClickHouse docs](https://clickhouse.com/docs/interfaces/http).
+
#### MySQL Protocol
**Port:** `9004` (Environment variable: `portMysql`)
+
Enables connectivity from MySQL-compatible tools and applications.
+
More about it in [official ClickHouse docs](https://clickhouse.com/docs/interfaces/mysql).
+
#### PostgreSQL Protocol
**Port:** `9005` (Environment variable: `portPostgresql`)
+
Allows integration with PostgreSQL-compatible clients and ORMs.
+
More about it in [official ClickHouse docs](https://clickhouse.com/docs/interfaces/postgresql).
+
## Backup and Recovery
+
Zerops provides comprehensive backup functionality using ClickHouse's native backup capabilities.
+
### Backup Process
+
* Backups are performed using ClickHouse SQL command `BACKUP ALL ...` with `super` user permissions
* All databases are backed up (excluding system databases)
* Backup files are stored as `tar.gz` archives
* Contains the complete folder structure produced by the SQL backup command
+
### Restore Options
+
#### Option 1: Custom S3 Bucket Restore
+
1. Download backup from Zerops GUI or via API
2. Extract the tar.gz archive and upload to your S3 bucket
3. Restore using ClickHouse SQL commands:
+
```sql
-- Restore specific table
RESTORE TABLE mydb.mytable AS mydb.mytable2
FROM S3('https://storage-prg1.zerops.io/mybucket/path/to/dir/with/untarred/backup',
'my-access-key-id', 'my-secret-key');
+
-- Restore all data
RESTORE ALL FROM S3('https://storage-prg1.zerops.io/mybucket/path/to/backup',
'my-access-key-id', 'my-secret-key');
+
-- see https://clickhouse.com/docs/operations/backup#configuring-backuprestore-to-use-an-s3-endpoint
```
+
#### Option 2: Support-Assisted Restore
+
Contact Zerops support on Discord, and we'll place the backup on the container's filesystem for restoration using the `File` driver (see [ClickHouse documentation](https://clickhouse.com/docs/operations/backup) for further info).
+
:::note
A simple GUI/API action for backup restoration is on our roadmap for future releases.
:::
+
## Troubleshooting
+
### Common Issues
+
#### Connection Problems
* Verify you're using the correct port for your chosen protocol
* Check that your service is running and healthy in the Zerops dashboard
* For HA clusters, try connecting to specific nodes if the main endpoint fails
* Ensure authentication credentials are correct
+
#### Replication Issues
* Verify you're using `ON CLUSTER '{cluster}'` for database operations
* Confirm tables use `ReplicatedMergeTree` engines
+
## Learn More
+
- [Official ClickHouse Documentation](https://clickhouse.com/docs) - Comprehensive guide to ClickHouse features and SQL syntax
- [ClickHouse Replication Guide](https://clickhouse.com/docs/engines/table-engines/mergetree-family/replication) - Detailed replication concepts
- [Distributed DDL Reference](https://clickhouse.com/docs/sql-reference/distributed-ddl) - Cluster operations documentation
+
## Support
+
For advanced configurations or custom requirements:
- Join our [Discord community](https://discord.gg/zerops)
- Contact support via [email](mailto:support@zerops.io)
@@ -2249,21 +3180,33 @@ For advanced configurations or custom requirements:
# Company > About
+
## Our Story
+
Zerops, originally founded in 2018, began as an internal project at [vshosting.eu](https://vshosting.eu), one of the largest providers of managed hosting solutions in Central Europe. In June 2024, after a period when the project had been shut down following corporate restructuring, Zerops was re-launched as an independent startup. Now headed by the original development team and backed by strong partners, Zerops continues its mission with renewed focus and independence.
+
## Technology & Infrastructure
+
Zerops runs on bare metal, with the platform built from the ground up using Golang and [Incus](https://linuxcontainers.org/incus/) containerization. Our servers are currently located in Prague, Czech Republic, leveraging vshosting's state-of-the-art datacenter facilities.
+
## Financial Backing & Partners
+
Zerops is financially backed by established venture capital firms:
- [Presto Ventures](https://www.prestoventures.com/) - A leading Central European venture capital firm
- [Gi21 Capital](https://gi21capital.com/) - A technology-focused investment firm
+
Our primary infrastructure partner is [vshosting.eu](https://vshosting.eu), which itself is part of [Contabo](https://contabo.com/en/), owned by global investment firm [KKR](https://www.kkr.com/). This strategic partnership provides Zerops with enterprise-grade infrastructure stability.
+
## Looking Ahead
+
We're committed to continually improving the Zerops platform with a focus on:
+
- **Multiregional Deployment**: Beginning with built-in CDN capabilities, followed by the ability to run entire projects in different regions
- **Enhanced Performance**: Ongoing optimization of our container orchestration and resource management
- **Developer Experience**: Continuous improvement of our UI, CLI, and API interfaces
+
## Connect With Us
+
- [Discord](https://discord.com/invite/WDvCZ54)
- [X.com](https://x.com/zeropsio)
- [LinkedIn](https://www.linkedin.com/company/zerops)
@@ -2273,76 +3216,117 @@ We're committed to continually improving the Zerops platform with a focus on:
# Company > Branding
+
# Zerops Brand Assets
+
Here you can find and download our official logos and badges in various formats. Please follow our brand guidelines when using these assets.
+
## Download Assets
+
Below you'll find our official assets available in various formats. Click the download buttons to get the assets in your preferred format.
+
## Brand Guidelines
+
When using Zerops brand assets, please:
+
- Don't modify the logos or badges in any way
- Maintain adequate spacing around the assets
- Use the provided color versions (light/dark) as appropriate
- Don't use the Zerops logo or badges in a way that suggests partnership or endorsement without permission
- Don't use the assets as your own branding or as part of your logo
+
----------------------------------------
# Company > Payment
+
Zerops provides a transparent credit-based payment system that makes managing your account finances straightforward. You can easily add funds to your account through manual or automatic top-ups, track all your transactions, and download invoices for your records.
+
This page explains how to manage your account balance, set up payment preferences, and access your complete billing history to help you maintain uninterrupted service while keeping your finances organized.
+
## Manual Top-up
+
Manual top-ups give you direct control over your account funding. To add credits to your account immediately:
+
1. Navigate to **Credit & Spend Overview** in the Organization section of the main menu
2. Click on **Top up credit** and fill in the [billing information](#billing-information)
3. Enter your desired top-up amount (minimum $10 VAT excl.)
3. Complete payment using your saved or new payment method
+
## Automatic Top-ups
+
:::caution Beta version
Available only for customers who have previously made a manual top-up, have a saved payment method, and have provided billing information.
:::
+
Automatic top-up ensures your projects continue running without interruption by replenishing your credits when they run low.
+
### How Automatic Top-ups Work
+
When enabled, Zerops monitors your credit balance and consumption rate to determine when and how much to top up, always respecting your configured limits.
Zerops initiates an automatic payment when:
+
- Your remaining credits are sufficient for **less than 10 days** of operation at your **current consumption rate**
- You have automatic top-ups enabled
- Your [settings](#billing-information) allow for the payment amount
+
:::note Important notes
- The charge amount is estimated based on your actual usage patterns, not maximum possible amounts
- Negative balances are included in the next auto top-up (within your maximum charge limit)
- The system checks your balance immediately after enabling auto top-ups, potentially triggering an immediate payment
- Auto top-up limits don't affect manual payments — add any amount manually regardless of automatic settings
:::
+
### Configuration Options
+
#### Period
The timeframe for which the maximum configured auto-charge amount is checked. Can be set to either:
+
- **Weekly**: Maximum charge amount applies to a 7-day rolling window
- **Monthly**: Maximum charge amount applies to a 30-day rolling window
+
#### Maximum Charge Amount
The maximum amount that can be auto-charged in the given period. This serves as a safeguard against unexpected costs due to traffic spikes or other unforeseen circumstances.
+
- Minimum setting: $10 (matches the minimum manual payment)
+
+#### Real-World Example
+
**Scenario:** Application with $20 weekly operating costs and initial manual top-up of $100
+
**Your Settings:**
- Period = Weekly
- Maximum charge amount = $150
+
**Expected behavior:**
- System adds approximately $20-30 when less than 10 days of credits remain (around day 35)
- Payments continue in small increments aligned with your usage patterns
- During traffic spikes, payments adjust to match higher consumption (up to $150 weekly limit)
- Payment amounts return to normal when usage decreases
+
## Billing Information
+
You are required to enter billing details for all transactions (manual and automatic top-ups), with one exception:
+
- EU-based users who are not VAT payers with transactions under $350
+
You can save your billing details by navigating to **Invoices & Billing Settings** in the Organization section of the main menu.
+
## Invoices
+
Zerops provides easy access to all invoices generated for manual and automatic top-ups within your organization.
+
To view and manage your invoices navigate to **Invoices & Billing Settings** in the Organization section of the main menu.
+
## Export Credit Consumption Records
+
Zerops allows you to download monthly reports of your credit consumption history for analysis and record-keeping.
+
1. Navigate to **Credit & Spend Overview** in the Organization section
2. Find the **Export Credit Consumption Records** section
3. Click on any month button to download that period's report
+
Reports are available for the past 12 months in TXT format and include:
- Client information and reporting period
- Starting and ending balances
@@ -2354,99 +3338,154 @@ Reports are available for the past 12 months in TXT format and include:
# Company > Pricing
+
Zerops provides a straightforward pricing structure based on your project type and resource usage.
+
The total cost of deploying an application includes your project's **core package cost** + the **cost of the resources** of the services inside a project. Additional charges may apply for optional features such as dedicated IPv4, extra egress, object storage, extra backup space and extra build time.
+
:::note Fair Billing Model
Resources are allocated per service and billed by the minute, though credit is deducted hourly based on actual usage. You're only charged for what you use, calculated down to the minute.
:::
+
Need to add credits to your account? Visit our [Top-up & Billing page](/company/payment) for instructions.
+
## Project Core Plans
+
Zerops offers two core types to match different needs and budgets. For detailed information on both core types, visit our [Project & Services Structure](/features/infrastructure) page.
+
### Lightweight Core - Free
Best for development, testing, and smaller workloads with limited redundancy.
+
**Included resources:**
- **Build Time**: 15 hours per month
- **Backup Storage**: 5 GB
- **Egress Traffic**: 100 GB per month
+
### Serious Core - $10 / 30 days
Optimized for production workloads with high availability and comprehensive failover protection.
+
**Included resources:**
- **Build Time**: 150 hours per month
- **Backup Storage**: 25 GB
- **Egress Traffic**: 3 TB per month
+
:::note Storage Limits
All projects have a technical maximum backup storage limit of **1 TiB**. Usage beyond the free tier allocation (5GB or 25GB) is billed according to the [overage costs](#overage-costs) below.
:::
+
## Resource Pricing
+
Services in Zerops require computing resources that are billed separately from your project core. These resources are allocated per service and billed by the minute based on actual usage, with credits deducted hourly.
-
- Resource
- Price
- Description
-
- Shared CPU
- $0.60 per CPU / 30 days
- Economical option for most workloads with good performance
-
- Dedicated CPU
- $6.00 per CPU / 30 days
- Reserved CPU cores for predictable performance
-
- RAM
- $0.75 per 0.25 GB / 30 days
- Memory allocated to your services
-
- Disk Space
- $0.05 per 0.5 GB / 30 days
- Storage space for your applications and data
-
+
+
+
+
+
Resource
+
Price
+
Description
+
+
+
+
+
Shared CPU
+
$0.60 per CPU / 30 days
+
Economical option for most workloads with good performance
+
+
+
Dedicated CPU
+
$6.00 per CPU / 30 days
+
Reserved CPU cores for predictable performance
+
+
+
RAM
+
$0.75 per 0.25 GB / 30 days
+
Memory allocated to your services
+
+
+
Disk Space
+
$0.05 per 0.5 GB / 30 days
+
Storage space for your applications and data
+
+
+
+
:::note Daily Spending Control
You can set daily spending limits in GUI for your project to control costs and avoid unexpected charges. This provides an alternative to configuring automatic resource scaling ranges while keeping your services running optimally.
:::
+
## Additional Services
+
Enhance your deployment with these optional services to meet specific requirements for networking, storage, and data transfer.
-
- Service
- Price
- Description
-
- Dedicated IPv4
- $3.00 per 30 days
- Exclusive IPv4 address for your project (instead of shared)
-
- Object Storage
- $0.01 per GB / 30 days
- Scalable storage for files, backups, and static assets
-
+
+
+
+
+
Service
+
Price
+
Description
+
+
+
+
+
Dedicated IPv4
+
$3.00 per 30 days
+
Exclusive IPv4 address for your project (instead of shared)
+
+
+
Object Storage
+
$0.01 per GB / 30 days
+
Scalable storage for files, backups, and static assets
+
+
+
+
## Overage Costs
+
When you exceed the resources included in your project core plan, the following charges apply:
-
- Item
- Price
- Description
-
- Extra Egress
- $0.02 per GB
- Data transfer out of your project beyond plan limits
-
- Extra Backup Space
- $0.50 per 5 GB
- Additional storage for automatic, encrypted backups
-
- Extra Build Time
- $0.50 per 15 hours
- Additional time for building and deploying applications
-
+
+
+
+
+
Item
+
Price
+
Description
+
+
+
+
+
Extra Egress
+
$0.02 per GB
+
Data transfer out of your project beyond plan limits
+
+
+
Extra Backup Space
+
$0.50 per 5 GB
+
Additional storage for automatic, encrypted backups
+
+
+
Extra Build Time
+
$0.50 per 15 hours
+
Additional time for building and deploying applications
+
+
+
+
## Pricing Calculator
+
Use our pricing calculator to estimate your monthly costs based on your specific needs:
+
----------------------------------------
# Deno > How To > Build Pipeline
+
Zerops provides a customizable build and runtime environment for your Deno application.
+
## Add zerops.yaml to your repository
+
Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:
+
```yaml
zerops:
# define hostname of your service
@@ -2455,49 +3494,63 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: deno@latest
+
# OPTIONAL. Set the operating system for the build environment.
# os: ubuntu
+
# OPTIONAL. Customise the build environment by installing additional packages
# or tools to the base build environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Build your application
buildCommands:
- deno task build
+
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- dist
- deno.jsonc
+
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
# cache: directory
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: deno@latest
+
# OPTIONAL. Sets the internal port(s) your app listens on:
ports:
# port number
- port: 3000
+
# OPTIONAL. Customise the runtime Deno environment by installing additional
# dependencies to the base Deno runtime environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Run one or more commands each time a new runtime container
# is started or restarted. These commands are triggered before
# your Deno application is started.
# initCommands:
# - rm -rf ./cache
+
# REQUIRED. Your Deno application start command
start: deno task start
```
+
The top-level element is always `zerops`.
+
### Setup
+
The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:
+
```yaml
zerops:
# definition for app service
@@ -2508,6 +3561,7 @@ zerops:
deploy: ...
# required
run: ...
+
# definition for api service
- setup: api
# optional
@@ -2517,11 +3571,20 @@ zerops:
# required
run: ...
```
+
Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.
+
## Build pipeline configuration
+
### base
+
_REQUIRED._ Sets the base technology for the build environment.
+
Following options are available for Deno builds:
+
+- `deno@2.0.0`, `deno@2`, `deno@latest`
+- `deno@1.45.5`, `deno@1`
+
```yaml
zerops:
# hostname of your service
@@ -2532,12 +3595,18 @@ zerops:
base: deno@latest
...
```
+
+
The base build environment contains {data.alpine.default}, the selected
- major version of Deno, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
+ major version of Deno, [Zerops command line tool](/references/cli), `npm`, `yarn`, `git` and `npx` tools.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -2551,34 +3620,52 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).
+
To customise your build environment use the [prepareCommands](#preparecommands) attribute.
+
:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::
+
### os
+
_OPTIONAL._ Sets the operating system for the build environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customised.
:::
+
:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::
+
### prepareCommands
+
_OPTIONAL._ Customises the build environment by installing additional dependencies or tools to the base build environment.
+
The base build environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- selected version of Deno defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `npm`, `yarn`, `git` and `npx` tools
+
To install additional packages or tools add one or more prepare commands:
+
```yaml
zerops:
# hostname of your service
@@ -2587,6 +3674,7 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: deno@latest
+
# OPTIONAL. Customise the build environment by installing additional packages
# or tools to the base build environment.
prepareCommands:
@@ -2594,20 +3682,31 @@ zerops:
- curl something else
...
```
+
When the first build is triggered, Zerops will
+
1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order
+
The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.
+
:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/deno/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### buildCommands
+
_OPTIONAL._ Defines build commands.
+
```yaml
zerops:
# hostname of your service
@@ -2616,40 +3715,57 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: deno@latest
+
# OPTIONAL. Build your application
buildCommands:
- deno task build
...
```
+
Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.
+
Before the build commands are triggered the build container contains:
+
1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code
+
#### Run build commands as a single shell instance
+
Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.
+
```yaml
buildCommands:
- |
deno test
deno task build
```
+
#### Run build commands as a separate shell instances
+
When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.
+
```yaml
buildCommands:
- deno task build
```
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/deno/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.
+
```yaml
buildCommands:
- npm i --verbose
- npm run build
```
+
If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.
+
### deployFiles
-_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use `.deployignore` file.
+
+_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.
+
```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
@@ -2658,56 +3774,81 @@ deployFiles:
- package.json
- node_modules
```
+
Determines files or folders produced by your build, which should be deployed to your runtime service containers.
+
The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.
+
The files/folders will be placed into `/var/www` folder in runtime, e.g. `./src/assets/fonts` would result in `/var/www/src/assets/fonts`.
+
#### Examples
+
Deploys a folder, and a file from the project root directory:
+
```yaml
deployFiles:
- dist
- package.json
```
+
Deploys the whole content of the build container:
+
```yaml
deployFiles: .
```
+
Deploys a folder, and a file in a defined path:
+
```yaml
deployFiles:
- ./path/to/file.txt
- ./path/to/dir/
```
+
#### How to use a wildcard in the path
+
Zerops supports the `~` character as a wildcard for one or more folders in the path.
+
Deploys all `file.txt` files that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/file.txt
```
+
Deploys all folders that are located in any path that begins with `/path/to/`
+
```yaml
deployFiles: ./path/to/~/
```
+
Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/
```
+
:::note Example
By default, `./src/assets/fonts` deploys to `/var/www/src/assets/fonts`, keeping the full path. Adding `~`, like `./src/assets/~fonts`, shortens it to `/var/www/fonts`
:::
#### .deployignore
-Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as `.gitignore`.
+
+Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as [`.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format).
+
To ignore a specific file or directory path, start the pattern with a forward slash (`/`). Without the leading slash, the pattern will match files with that name in any directory.
+
:::tip
For consistency, it's recommended to configure both your `.gitignore` and `.deployignore` files with the same patterns.
:::
+
Examples:
+
```yaml title="zerops.yaml"
zerops:
- setup: app
build:
deployFiles: ./
```
+
```text title=".deployignore"
/src/file.txt
```
@@ -2719,22 +3860,33 @@ This example above ignores `file.txt` in ANY directory named `src`, such as:
- `/src/file.txt`
- `/folder2/folder3/src/file.txt`
- `/src/src/file.txt`
+
:::note
-`.deployignore` file also works with `zcli service deploy` command.
+`.deployignore` file also works with [`zcli service deploy`](/references/zcli/commands#deploy) command.
:::
+
### cache
+
_OPTIONAL._ Defines which files or folders will be cached for the next build.
+
```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```
+
The cache attribute helps optimize build times by preserving specified files between builds.
+
The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).
+
Learn more about the [build cache system](/features/build-cache) in Zerops.
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the build environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -2743,6 +3895,7 @@ zerops:
build:
base: deno@latest
…
+
# OPTIONAL. Defines the env variables for the build environment:
envVariables:
NODE_ENV: production
@@ -2751,12 +3904,21 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/deno/how-to/env-variables) in Zerops.
+
## Runtime configuration
+
### base
+
_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Deno version for your runtime.
+
Following options are available for Deno builds:
+
+- `2.0`
+- `1.45`
+
```yaml
zerops:
# hostname of your service
@@ -2766,18 +3928,25 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: deno@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: deno@latest
...
```
+
+
The base runtime environment contains {data.alpine.default}, the
selected major version of Deno, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -2787,6 +3956,7 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: deno@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
@@ -2796,36 +3966,58 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [run base environments](/zerops-yaml/base-list).
+
To customise your build environment use the `prepareCommands` attribute.
+
### os
+
_OPTIONAL._ Sets the operating system for the runtime environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customised.
:::
+
### ports
+
_OPTIONAL._ Specifies one or more internal ports on which your application will listen.
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
For example, to connect to a Deno service with hostname = "app" and port = 3000 from another service of the same project, simply use `app:3000`. Read more about [how to access a Deno service](/references/networking/internal-access#basic-service-communication).
+
Each port has following attributes:
+
| parameter | description |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| port | Defines the port number. You can set any port number between _10_ and _65435_. Ports outside this interval are reserved for internal Zerops systems. |
| protocol | **Optional.** Defines the protocol. Allowed values are `TCP` or `UDP`. Default value is `TCP`. |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |
+
### prepareCommands
+
_OPTIONAL._ Customises the Deno runtime environment by installing additional dependencies or tools to the runtime base environment.
+
+
The base Deno environment contains {data.alpine.default} the selected
- major version of Deno, Zerops command line tool and `npm`, `yarn`, `git` and `npx` tools. To install
+ major version of Deno, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools. To install
additional packages or tools add one or more prepare commands:
+
+
```yaml
zerops:
# hostname of your service
@@ -2833,6 +4025,7 @@ zerops:
# ==== how to build your application ====
build:
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -2842,27 +4035,45 @@ zerops:
- curl something else
...
```
+
When the first deploy with a defined prepare attribute is triggered, Zerops will
+
1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order
+
:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/deno/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.
+
#### Cache of your custom runtime environment
+
Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:
+
1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.
+
To invalidate the custom runtime cache go to `yyy`
+
When the custom runtime cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### Copy folders or files from your build container
+
+
The prepare runtime container contains {data.alpine.default}, the
- selected major version of Deno, Zerops command line tool and `npm`, `yarn`, `git` and `npx` tools.
+ selected major version of Deno, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools.
+
+
The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).
+
```yaml
zerops:
# hostname of your service
@@ -2871,6 +4082,7 @@ zerops:
build:
...
addToRunPrepare: ./runtime-config.yaml
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -2880,15 +4092,20 @@ zerops:
- curl something else
...
```
+
In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.
+
### initCommands
+
_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Run one or more commands each time a new runtime container
@@ -2897,22 +4114,35 @@ zerops:
initCommands:
- rm -rf ./cache
```
+
These commands are triggered in the runtime container before your Deno application is started via the [start command](#start).
+
:::note
`run.initCommands` run in the `/var/www` directory.
:::
+
Use init commands to clean or initialise your application cache or similar operations.
+
:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/deno/how-to/scaling) or when a runtime container is restarted).
+
Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::
+
#### Command exit code
+
If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/deno/how-to/logs#runtime-log) to troubleshoot the error.
+
#### Single or separated shell instances
+
You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the runtime environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -2927,57 +4157,84 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/deno/how-to/env-variables) in Zerops.
+
### start
+
_REQUIRED._ Defines the start command for your Deno application.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Deno application start command
start: deno task start
```
+
We recommend starting your Deno application using `deno task start`.
+
### health check
+
_OPTIONAL._ Defines a health check.
+
`healthCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the health check to request a local URL using a HTTP GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
-**Example:**
-```yaml
-zerops:
- # hostname of your service
- - setup: app
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
+**Example:**
+
+```yaml
+zerops:
+ # hostname of your service
+ - setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Deno application start command
start: deno task start
+
# OPTIONAL. Define a health check with a HTTP GET request option.
# Configures the check on http://127.0.0.1:80/status
healthCheck:
@@ -2985,25 +4242,32 @@ zerops:
port: 80
path: /status
```
+
#### exec
+
Configures the health check to run a local command.
Following attributes are available:
+
| Parameter | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/deno/how-to/create#set-secret-environment-variables) as your Deno application.
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below. |
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Deno application start command
start: deno task start
+
# OPTIONAL. Define a health check with a shell command.
healthCheck:
exec:
@@ -3012,13 +4276,18 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
### crontab
+
_OPTIONAL._ Defines cron jobs.
+
Setup cron jobs in the following format:
+
```yaml
zerops:
# define hostname of your service
- setup: app
+
# ==== how to run your application ====
run:
crontab:
@@ -3027,14 +4296,23 @@ zerops:
# REQUIRED. Sets the interval time to execute:
timing: "0 * * * *"
```
+
Read more about setting up [cron](/zerops-yaml/cron) in Zerops.
+
## Deploy configuration
+
### readiness check
+
_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/deno/how-to/deploy-process#readiness-checks) in Zerops.
+
`readinessCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the readiness check to request a local URL using a http GET method.
+
Following attributes are available:
+
@@ -3064,13 +4342,16 @@ If your application requires a https request, set scheme: https
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -3079,25 +4360,33 @@ zerops:
httpGet:
port: 80
path: /status
+
# ==== how to run your application ====
run: ...
```
+
Read more about how the [readiness check works](/deno/how-to/deploy-process#readiness-checks) in Zerops.
+
#### exec
+
Configures the readiness check to run a local command.
Following attributes are available:
+
| Parameter | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/deno/how-to/create#set-secret-environment-variables) as your Deno application.
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below. |
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -3109,88 +4398,136 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
Read more about how the [readiness check works](/deno/how-to/deploy-process#readiness-checks) in Zerops.
+
----------------------------------------
# Deno > How To > Build Process
-
+
## Build process overview
+
Zerops starts a temporary build container and performs the following actions:
+
1. **Installs the build environment** - Sets up base system and Deno runtime
2. **Downloads your application source code** - From [GitHub ↗](https://www.github.com), [GitLab ↗](https://www.gitlab.com) or via [Zerops CLI](/references/cli)
3. **Optionally customizes the build environment** - Runs prepare commands if configured
4. **Runs the build commands** - Executes your build process
5. **Uploads the application artifact** - Stores build output to internal Zerops storage
6. **Caches selected files** - Preserves specified files for faster future builds
+
The build container is automatically deleted after the build has finished or failed.
+
## Build configuration
+
Configure your Deno build process in your `zerops.yaml` file according to the [full build & deploy Deno pipeline guide](/deno/how-to/build-pipeline).
+
## Build environment
+
### Default Deno build environment
+
The default Deno build environment contains:
-- {data.ubuntu.default}
+
+- {data.ubuntu.default}
- Selected version of Deno defined in `zerops.yaml` [build.base](/deno/how-to/build-pipeline#base) parameter
- [zCLI](/references/cli), Zerops command line tool
- Deno and Git
+
### Customize build environment
+
To install additional packages or tools, add one or more [build.prepareCommands](/deno/how-to/build-pipeline#preparecommands) to your `zerops.yaml`.
+
:::info
The application code is available in the `/build/source` folder in your build container before the prepare commands are triggered. This allows you to use any file from your application code in your prepare commands (e.g. a configuration file).
:::
+
### Build hardware resources
+
All runtime services use the same hardware resources for build containers:
-
- HW resource
- Minimum
- Maximum
-
- CPU cores
- 1
- 5
-
- RAM
- 8 GB
- 8 GB
-
- Disk
- 1 GB
- 100 GB
-
+
+
+
+
+
HW resource
+
Minimum
+
Maximum
+
+
+
+
+
CPU cores
+
1
+
5
+
+
+
RAM
+
8 GB
+
8 GB
+
+
+
Disk
+
1 GB
+
100 GB
+
+
+
+
Build containers start with minimum resources and scale vertically up to maximum capacity as needed.
+
:::info
Build container resources are not charged separately. Limited build time is included in your [project core plan](/company/pricing#project-core-plans), with additional build time available if needed.
:::
+
### Build time limit
+
The time limit for the whole build pipeline is **1 hour**. After 1 hour, Zerops will terminate the build pipeline and delete the build container.
+
## Troubleshooting Deno builds
+
### Build command failures
+
If any [build command](/deno/how-to/build-pipeline#buildcommands) fails (returns non-zero exit code), the build is canceled. Check the [build log](/deno/how-to/logs#build-log) to troubleshoot the error.
+
For Deno, if the error log doesn't contain specific error messages, try running your build with verbose output:
+
```yaml
buildCommands:
- deno cache main.ts
- deno compile --allow-net --allow-read main.ts
```
+
### Prepare command failures
+
If any [prepare command](/deno/how-to/build-pipeline#preparecommands) fails, check the [build log](/deno/how-to/logs#build-log) for specific error messages. Common issues include:
+
- Missing permissions in Deno commands (add --allow-net, --allow-read, etc.)
- Ubuntu package installation failures (use sudo apt-get update first)
- Deno cache directory permissions
+
### Build cache issues
+
If you encounter unexpected build behavior or dependency issues, the problem might be related to [cached build data](/features/build-cache). While Zerops maintains the build cache to speed up deployments, sometimes you may need to start fresh.
+
To invalidate the build cache:
+
1. Go to your service detail in Zerops GUI
2. Choose **Pipelines & CI/CD Settings** from the left menu
3. Click on the **Invalidate build cache** button
+
This will force Zerops to run the next build clean, including all prepare commands. Learn more about [build cache behavior](/features/build-cache).
+
:::tip Advanced troubleshooting
For complex build issues that require investigation, you can enable [debug mode](/features/debug-mode) to pause the build process at specific points and inspect the build container state interactively.
:::
+
## More resources
+
For more details about the build and deploy pipeline, including how to cancel builds and manage application versions, see the [general pipeline documentation](/features/pipeline).
+
## Next steps
+
- Understand the [deployment process](/deno/how-to/deploy-process)
- Learn how to [customize the runtime environment](/deno/how-to/customize-runtime)
- Explore [build and runtime logs](/deno/how-to/logs)
@@ -3205,34 +4542,58 @@ For more details about the build and deploy pipeline, including how to cancel bu
# Deno > How To > Create
+
Zerops provides a powerful Deno runtime service with extensive build support. The Deno runtime is highly scalable and customizable to suit your development and production needs. With just a few clicks or commands, you can have a production-ready Deno environment up and running in no time.
+
## Create a Deno service using Zerops GUI
+
First, set up a project in the Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu under the **Services** section. From there, you can add a new Deno service:
+
+[Video: /vids/services/deno.webm](/vids/services/deno.webm)
+
### Choose a Deno version
+
Zerops supports the following Deno versions:
+
:::info
You can easily [upgrade](/deno/how-to/upgrade) the major version at any time later.
:::
+
### Set a hostname
+
Enter a unique service identifier like "app", "cache", "gui", etc. Duplicate services with the same name within the same project are not allowed.
+
#### Limitations:
+
- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::
+
### Set secret environment variables
+
Add environment variables with sensitive data, such as passwords, tokens, salts, certificates, etc. These will be securely saved inside Zerops and added to your runtime service upon start.
+
Setting secret environment variables is optional. You can always set them later in the Zerops GUI.
+
Read more about the [different types of environment variables](/deno/how-to/env-variables#service-env-variables) in Zerops.
+
## Create a Deno service using zCLI
+
zCLI is the Zerops command-line tool. To create a new Deno service via the command line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/deno/how-to/create#create-a-project-description-file)
3. [Create a project with a Deno and PostgreSQL service](#full-example)
+
### Create a project description file
+
Zerops uses a YAML format to describe the project infrastructure.
+
#### Basic example:
+
Create a directory called `my-project`. Inside the `my-project` directory, create a `description.yaml` file with the following content:
```yaml
# basic project data
@@ -3254,13 +4615,18 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes your future project infrastructure. The project will contain one Deno version 20 service with default [auto scaling](/deno/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/deno/how-to/build-pipeline#ports). Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
#### Full example:
+
Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:
+
```yaml
# basic project data
project:
@@ -3305,103 +4671,171 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain a Deno service and a [PostgreSQL](/postgresql/overview) service.
+
Deno service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/deno/how-to/build-pipeline#ports). Deno service will run on version 20 with a custom vertical and horizontal scaling. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
+
| Parameter | Description | Limitations |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **name** | The name of the new project. Duplicates are allowed. | |
| **description** | **Optional.** Description of the new project. | Maximum 255 characters. |
| **tags** | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |
| **tags** | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |
+
At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Deno and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
+ hostname
+
+
The unique service identifier.
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
+ type
+
+
Specifies the service type and version.
-
+
See what [Deno service types](/references/import-yaml/type-list#runtime-services) are currently supported.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto scaling parameters.
+
+
+
+
+ verticalAutoscaling
+
+
+ Optional. Defines [custom vertical auto scaling parameters](/deno/how-to/create#set-auto-scaling-configuration).
+
All verticalAutoscaling attributes are optional. Not specified
attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
- minContainers
-
- Optional. Default = 1. Defines the minimum number of containers
- for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
+ - cpuMode
+
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
+ - minCpu/maxCpu
+
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
+ - minRam/maxRam
+
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
+ - minDisk/maxDisk
+
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
+ minContainers
+
+
+ Optional. Default = 1. Defines the minimum number of containers
+ for [horizontal autoscaling](/deno/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- maxContainers
-
- Defines the maximum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
+ maxContainers
+
+
+ Defines the maximum number of containers for [horizontal autoscaling](/deno/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- envSecrets
-
- Optional. Defines one or more secret env variables as a key value
- map. See env variable restrictions.
-
+
+
+
+
+ envSecrets
+
+
+ Optional. Defines one or more secret env variables as a key value
+ map. See env variable [restrictions](/deno/how-to/env-variables#env-variable-restrictions).
+
+
+
+
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add Deno service to an existing project
+
#### Example:
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -3422,49 +4856,71 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Deno service version 20 with default [auto scaling](/deno/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the import.yaml file is 100 kB.
+
----------------------------------------
# Deno > How To > Customize Runtime
+
## Build Custom Runtime Images
+
Zerops allows you to build custom runtime images (CRI) when the default base runtime images don't meet your Deno application's requirements. This is an optional phase in the [build and deploy pipeline](/features/pipeline#runtime-prepare-phase-optional).
+
:::important
You should not include your application code in the custom runtime image, as your built/packaged code is deployed automatically into fresh containers.
:::
+
## Configuration
+
### Default Deno Runtime Environment
+
The default Deno runtime environment contains:
-- {data.ubuntu.default}
+
+- {data.ubuntu.default}
- Selected version of Deno when the runtime service was created
- [zCLI](/references/cli)
- Deno and Git
+
### When You Need a Custom Runtime Image
+
If your Deno application needs more than what's included in the default environment, you'll need to build a custom runtime image. Common scenarios include:
+
- **System packages for processing**: When your app processes images, videos, or files (requiring packages like `sudo apt-get install -y imagemagick`)
- **Global Deno tools**: When you need CLI tools or utilities available system-wide
- **Native dependencies**: When your Deno modules require system libraries that aren't in the default environment
+
Here are Deno-specific examples of configuring custom runtime images in your `zerops.yml`:
+
### Basic Deno Setup
-
+
### Using Build Files in Runtime Preparation
+
```yaml
build:
addToRunPrepare:
@@ -3476,18 +4932,26 @@ run:
- sudo apt-get install -y imagemagick
- deno cache deps.ts
```
+
For complete configuration details, see the [runtime prepare phase configuration guide](/features/pipeline#configuration).
+
## Process and Caching
+
### How Runtime Prepare Works
The runtime prepare process follows the same steps for all runtimes. See [how runtime prepare works](/features/pipeline#how-it-works) for the complete process details.
+
### Caching Behavior
Zerops caches custom runtime images to optimize deployment times. Learn about [custom runtime image caching](/features/pipeline#custom-runtime-image-caching) including when images are cached and reused.
+
### Build Management
For information about managing builds and deployments, see [managing builds and deployments](/features/pipeline#manage-builds-and-deployments).
+
:::warning
Shared storage mounts are not available during the runtime prepare phase.
:::
+
## Troubleshooting
+
If your `prepareCommands` fail, check the [prepare runtime log](/deno/how-to/logs#prepare-runtime-log) for specific error messages.
----------------------------------------
@@ -3542,62 +5006,112 @@ If your `prepareCommands` fail, check the [prepare runtime log](/deno/how-to/log
# Deno > Overview
+
[Deno ↗](https://deno.org/en) is an asynchronous event-driven JavaScript runtime, which is designed to build scalable network applications.
+
:::tip
Have you got any additional question? Join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::
+
As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-deno), a **_recipe_**, containing the most simple Deno web application. The repo will be used as a source from which the app will be built.
- This is the most bare-bones example of Deno app running in Zerops — as few libraries as possible,
+
+### 🚀 No Fuss, Just Deploy with Speed!
+
+This is the most bare-bones example of Deno app running in Zerops — as few libraries as possible,
just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.
-
+
+ [Deploy "deno" recipe on Zerops](https://app.zerops.io/recipe/?lf=deno)
+
1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
+
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-deno/blob/main/zerops-project-import.yaml)):
+
```yaml
project:
name: recipe-deno
tags:
- zerops-recipe
+
services:
- hostname: api
type: deno@1
buildFromGit: https://github.com/zeropsio/recipe-deno
enableSubdomainAccess: true
+
- hostname: db
type: postgresql@16
mode: NON_HA
priority: 1
```
+
3. Click on **Import project** and wait until all pipelines have finished.
+
**That's it, your application is now up and running! :star: Let's check it works:**
+
1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://api-7f6-8000.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see
+
```
{"message":"This is a simple, basic Deno / Oak application running in Zerops.io,\n each request adds an entry to the PostgreSQL database and returns a count.\n See the source repository (https://github.com/zeropsio/recipe-deno) for more information.","newEntry":"274b0cc1-5b6d-4351-b8ec-53cf82bd9d0f","count":1}
```
+
:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::
+
## How to start
+
It doesn't matter whether it's your first curious introduction to Zerops, you have already mastered the basics and are looking for a tiny detail or inspiration. Below, choose a section that fits your needs:
+
+- [Care for details?](/deno/how-to/create) — Dive in all Zerops has to offer for your Deno application.
+- [Deno recipes](https://github.com/zeropsio?q=deno&type=all&language=&sort=) — Get inspired by already existing repositories, ready to be imported to Zerops.
+
## Feature Highlights
+
+- [Create Deno service](/deno/how-to/create) — Start with creating a Deno service using GUI or zCLI.
+- [Zerops.yaml](/deno/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
+- [Scaling configuration](/deno/how-to/scaling) — Set up scaling of your Deno application so that it runs smoothly while using only necessary resources.
+
{" "}
+
+- [Customize build environment](/deno/how-to/build-process#customize-build-environment)
+- [Customize runtime environment](/deno/how-to/customize-runtime)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Docker > Overview
+
Zerops provides Docker support through dedicated Virtual Machine (VM) environments, ensuring maximum compatibility and isolation while maintaining integration with the broader Zerops ecosystem. This guide explains how to effectively use Docker services in Zerops, including best practices and important considerations.
+
## Why VMs
+
While Zerops primarily uses native Linux containers for optimal performance, this VM-based approach allows you to run virtually any Docker container while maintaining Zerops' robust infrastructure management.
+
You can learn more about [differences](/features/container-vs-vm) between Containers and Virtual Machines in Zerops.
+
Before using Docker services, consider these important aspects:
+
### Virtual Machine Environment
+
Docker services in Zerops operate in a full VM environment, which has several implications:
+
- **Slower Boot Times**: VMs require more time to initialize due to full kernel boot
- **Higher Resource Usage**: VMs include additional system overhead compared to native containers
- **Scaling Limitations**:
@@ -3606,42 +5120,59 @@ Docker services in Zerops operate in a full VM environment, which has several im
- Zerops automatically restarts the VM when resource values are changed in UI
- **Storage Management**: Disk space can only be increased, not decreased without recreation
- **Build Phase Limitations**: Build phase runs in containers, not in the VM environment
+
### Advantages
+
Despite these limitations, Docker services offer some benefits:
+
- **Broad Compatibility**: Run almost any Docker container with minimal modification
- **Familiar Environment**: Standard Docker runtime environment
+
## Configuration Guide
+
### Supported Version
+
Currently supported Docker versions:
-Import configuration version:
+
### Basic Structure
+
Docker services in Zerops are configured through the `zerops.yaml` file. Here's a typical configuration pattern:
+
```yaml title="zerops.yaml"
zerops:
- setup: app
run:
base: docker@latest
prepareCommands:
- - docker image pull : # Always use specific version tags
- start: docker run --network=host :
+ - docker image pull : # Always use specific version tags
+ start: docker run --network=host :
ports:
- - port:
+ - port:
httpSupport: true
```
+
:::important
Always use specific version tags (like `1.0.0`) instead of `:latest`. Zerops caches the `prepareCommands` output, which means a new `:latest` image won't be automatically pulled on subsequent deployments unless the cache is manually cleared or the commands change.
:::
+
Refer to the [Docker recipe repository](https://github.com/zeropsio/recipe-docker) for an example configuration.
+
:::note
We are actively working on improving the speed of image caching after `run.prepareCommands` and reducing the startup time of runtime VMs. These improvements will be released in future updates.
:::
+
### Network Configuration
+
Docker services require the `--network=host` flag for proper integration with Zerops:
+
- **Direct Port Management**: Ports are managed through `zerops.yaml`
- **Simplified Configuration**: Avoids double port exposure in Docker and Zerops
- **Native Performance**: Direct access to host networking
+
### Docker Compose Support
+
For projects using Docker Compose, additional configuration is required:
+
1. **File Deployment**:
```yaml title="zerops.yaml"
build:
@@ -3649,6 +5180,7 @@ For projects using Docker Compose, additional configuration is required:
deployFiles: ./docker-compose.yaml
addToRunPrepare: ./docker-compose.yaml
```
+
2. **Network Mode**:
```yaml title="docker-compose.yaml"
services:
@@ -3656,15 +5188,21 @@ For projects using Docker Compose, additional configuration is required:
image: your-image:1.0.0
network_mode: host
```
+
3. **Start Command**:
```yaml title="zerops.yaml"
run:
start: docker compose up --force-recreate
```
+
### Environment Variables
+
When using Docker services, there's an additional layer to consider since environment variables defined in Zerops must be explicitly passed to your Docker containers.
+
#### 1. Defining Variables in Zerops
+
Define your environment variables in the `run.envVariables` section of your `zerops.yaml` (example uses [referenced](/features/env-variables#referencing-variables) variables):
+
```yaml title="zerops.yaml"
zerops:
- setup: app
@@ -3674,8 +5212,11 @@ zerops:
DB_HOST: ${db_hostname}
DB_PORT: ${db_port}
```
+
#### 2. Passing Variables to Docker Containers
+
For single containers, pass variables using the `-e` flag:
+
```yaml title="zerops.yaml"
run:
base: docker@latest
@@ -3683,10 +5224,13 @@ run:
- docker image pull my-application:1.0.0 # Use specific version tags, not :latest
start: docker run -e DB_HOST -e DB_PORT --network=host my-application:1.0.0
```
+
:::important
Always use specific version tags (like `1.0.0`) instead of `:latest`. Zerops caches the `prepareCommands` output, which means a new `:latest` image won't be automatically pulled on subsequent deployments unless the cache is manually cleared or the commands change.
:::
+
For Docker Compose setups, pass environment variables in your `docker-compose.yaml`:
+
```yaml title="docker-compose.yaml"
services:
api:
@@ -3696,8 +5240,11 @@ services:
- DB_HOST
- DB_PORT
```
+
## Implementation Examples
+
### Single Container
+
```yaml title="zerops.yaml"
zerops:
- setup: app
@@ -3710,10 +5257,13 @@ zerops:
- port: 8000
httpSupport: true
```
+
:::important
Always use specific version tags (like `1.0.0`) instead of `:latest`. Zerops caches the `prepareCommands` output, which means a new `:latest` image won't be automatically pulled on subsequent deployments unless the cache is manually cleared or the commands change.
:::
+
### Single Service with Docker Compose
+
```yaml title="zerops.yaml"
zerops:
- setup: api
@@ -3730,6 +5280,7 @@ zerops:
- port: 8000
httpSupport: true
```
+
```yaml title="docker-compose.yaml (excerpt)"
services:
api:
@@ -3737,7 +5288,9 @@ services:
network_mode: host
# other configuration...
```
+
### Multiple Services with Docker Compose
+
```yaml title="zerops.yaml"
zerops:
- setup: apps
@@ -3754,36 +5307,49 @@ zerops:
- port: 8000
httpSupport: true
```
+
```yaml title="docker-compose.yaml (excerpt)"
services:
web:
image: web-image:1.0.0
network_mode: host
# other configuration...
+
api:
image: api-image:1.0.0
network_mode: host
# other configuration...
```
+
## Best Practices
+
#### Image Management
- **Always use specific version tags** instead of `:latest` - This prevents caching issues as Zerops caches `prepareCommands` output
+
#### Resource Planning
- Account for VM overhead in resource allocation
- Plan for longer initialization times
- Consider the impact on scaling operations
+
#### Migration Consideration
- Evaluate if your workload could run on native containers
- Consider gradual migration for complex applications
- Balance development effort against operational benefits
+
## Limitations and Workarounds
+
### Build Phase
+
Since the build phase runs in containers rather than VMs:
+
- Use `run.prepareCommands` for Docker-specific build steps
- Consider external CI/CD for complex Docker builds
- Leverage pre-built images when possible
+
### Scaling Operations
+
Docker services in Zerops have specific scaling characteristics that differ from native containers:
+
#### Vertical Scaling
- Resources must be defined with **fixed** values instead of min-max ranges
- CPU, RAM, and disk are specified as single values:
@@ -3795,6 +5361,7 @@ Docker services in Zerops have specific scaling characteristics that differ from
```
- Any change to these values through the UI triggers an automatic VM restart
- Plan your resource allocation carefully to minimize scaling operations
+
#### Horizontal Scaling
- Still supports multiple containers through `minContainers` and `maxContainers`
- Consider breaking large services into smaller components
@@ -3805,9 +5372,13 @@ Docker services in Zerops have specific scaling characteristics that differ from
# Dotnet > How To > Build Pipeline
+
Zerops provides a customizable build and runtime environment for your .NET application.
+
## Add zerops.yaml to your repository
+
Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:
+
```yaml
zerops:
# define hostname of your service
@@ -3816,51 +5387,65 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: dotnet@6
+
# OPTIONAL. Set the operating system for the build environment.
# os: ubuntu
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Build your application
buildCommands:
- npm i
- npm run build
+
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- dist
- package.json
- node_modules
+
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: node_modules
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: dotnet@latest
+
# OPTIONAL. Sets the internal port(s) your app listens on:
ports:
# port number
- port: 5000
+
# OPTIONAL. Customize the runtime .NET environment by installing additional
# dependencies to the base .NET runtime environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Run one or more commands each time a new runtime container
# is started or restarted. These commands are triggered before
# your .NET application is started.
# initCommands:
# - rm -rf ./cache
+
# REQUIRED. Your .NET application start command
start: npm start
```
+
The top-level element is always `zerops`.
+
### Setup
+
The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:
+
```yaml
zerops:
# definition for app service
@@ -3871,6 +5456,7 @@ zerops:
deploy: ...
# required
run: ...
+
# definition for api service
- setup: api
# optional
@@ -3880,11 +5466,23 @@ zerops:
# required
run: ...
```
+
Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.
+
## Build pipeline configuration
+
### base
+
_REQUIRED._ Sets the base technology for the build environment.
+
Following options are available for .NET builds:
+
+- `dotnet@10`, `dotnet@latest`
+- `dotnet@9`
+- `dotnet@8`
+- `dotnet@7`
+- `dotnet@6`
+
```yaml
zerops:
# hostname of your service
@@ -3895,12 +5493,18 @@ zerops:
base: dotnet@6
...
```
+
+
The base build environment contains {data.alpine.default}, the selected
- major version of .NET, Zerops command line tool, `ASP .NET` and `git`.
+ major version of .NET, [Zerops command line tool](/references/cli), `ASP .NET` and `git`.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -3914,34 +5518,52 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).
+
To customize your build environment use the [prepareCommands](#preparecommands) attribute.
+
:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::
+
### os
+
_OPTIONAL._ Sets the operating system for the build environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customized.
:::
+
:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::
+
### prepareCommands
+
_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.
+
The base build environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- selected version of .NET defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `ASP .NET` and `git`
+
To install additional packages or tools add one or more prepare commands:
+
```yaml
zerops:
# hostname of your service
@@ -3950,6 +5572,7 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: dotnet@6
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
prepareCommands:
@@ -3957,20 +5580,31 @@ zerops:
- curl something else
...
```
+
When the first build is triggered, Zerops will
+
1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order
+
The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.
+
:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/dotnet/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### buildCommands
+
_OPTIONAL._ Defines build commands.
+
```yaml
zerops:
# hostname of your service
@@ -3979,96 +5613,138 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: dotnet@6
+
# OPTIONAL. Build your application
buildCommands:
- dotnet build -o app
...
```
+
Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.
+
Before the build commands are triggered the build container contains:
+
1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code
+
#### Run build commands as a single shell instance
+
Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.
+
```yaml
buildCommands:
- |
sudo apt-get -y install dotnet-runtime-6.0 aspnetcore-runtime-6.0 dotnet-sdk-6.0 # already installed for .NET service
dotnet build -o app
```
+
#### Run build commands as a separate shell instances
+
When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.
+
```yaml
buildCommands:
- sudo apt-get -y install dotnet-runtime-6.0 aspnetcore-runtime-6.0 dotnet-sdk-6.0 # already installed for .NET service
- dotnet build -o app
```
+
#### Command exit code
-If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/dotnet/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the `--verbosity ` option.
+
+If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/dotnet/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the `--verbosity ` option.
+
```yaml
buildCommands:
- dotnet build --verbosity detailed
```
+
If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.
+
### deployFiles
-_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use `.deployignore` file.
+
+_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.
+
```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- app
```
+
Determines files or folders produced by your build, which should be deployed to your runtime service containers.
+
The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.
+
The files/folders will be placed into `/var/www` folder in runtime, e.g. `./src/assets/fonts` would result in `/var/www/src/assets/fonts`.
+
#### Examples
+
Deploys a folder, and a file from the project root directory:
+
```yaml
deployFiles:
- app
- file.txt
```
+
Deploys the whole content of the build container:
+
```yaml
deployFiles: .
```
+
Deploys a folder, and a file in a defined path:
+
```yaml
deployFiles:
- ./path/to/file.txt
- ./path/to/dir/
```
+
#### How to use a wildcard in the path
+
Zerops supports the `~` character as a wildcard for one or more folders in the path.
+
Deploys all `file.txt` files that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/file.txt
```
+
Deploys all folders that are located in any path that begins with `/path/to/`
+
```yaml
deployFiles: ./path/to/~/
```
+
Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/
```
+
:::note Example
By default, `./src/assets/fonts` deploys to `/var/www/src/assets/fonts`, keeping the full path. Adding `~`, like `./src/assets/~fonts`, shortens it to `/var/www/fonts`
:::
#### .deployignore
-Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as `.gitignore`.
+
+Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as [`.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format).
+
To ignore a specific file or directory path, start the pattern with a forward slash (`/`). Without the leading slash, the pattern will match files with that name in any directory.
+
:::tip
For consistency, it's recommended to configure both your `.gitignore` and `.deployignore` files with the same patterns.
:::
+
Examples:
+
```yaml title="zerops.yaml"
zerops:
- setup: app
build:
deployFiles: ./
```
+
```text title=".deployignore"
/src/file.txt
```
@@ -4080,22 +5756,33 @@ This example above ignores `file.txt` in ANY directory named `src`, such as:
- `/src/file.txt`
- `/folder2/folder3/src/file.txt`
- `/src/src/file.txt`
+
:::note
-`.deployignore` file also works with `zcli service deploy` command.
+`.deployignore` file also works with [`zcli service deploy`](/references/zcli/commands#deploy) command.
:::
+
### cache
+
_OPTIONAL._ Defines which files or folders will be cached for the next build.
+
```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```
+
The cache attribute helps optimize build times by preserving specified files between builds.
+
The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).
+
Learn more about the [build cache system](/features/build-cache) in Zerops.
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the build environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -4104,6 +5791,7 @@ zerops:
build:
base: dotnet@6
…
+
# OPTIONAL. Defines the env variables for the build environment:
envVariables:
DOTNET_ENV: production
@@ -4112,12 +5800,24 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/dotnet/how-to/env-variables) in Zerops.
+
## Runtime configuration
+
### base
+
_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current .NET version for your runtime.
+
Following options are available for .NET builds:
+
+- `dotnet@10`, `dotnet@latest`
+- `dotnet@9`
+- `dotnet@8`
+- `dotnet@7`
+- `dotnet@6`
+
```yaml
zerops:
# hostname of your service
@@ -4127,18 +5827,25 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: dotnet@6
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: dotnet@6
...
```
+
+
The base runtime environment contains {data.alpine.default}, the
- selected major version of .NET, Zerops command line tool and `ASP .NET` and `git`.
+ selected major version of .NET, [Zerops command line tool](/references/cli) and `ASP .NET` and `git`.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -4148,6 +5855,7 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: dotnet@6
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
@@ -4157,43 +5865,74 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [run base environments](/zerops-yaml/base-list).
+
To customise your build environment use the `prepareCommands` attribute.
+
### os
+
_OPTIONAL._ Sets the operating system for the runtime environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customised.
:::
+
### ports
+
_OPTIONAL._ Specifies one or more internal ports on which your application will listen.
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
For example, to connect to a .NET service with hostname = "app" and port = 5000 from another service of the same project, simply use `app:5000`. Read more about [how to access a .NET service](/references/networking/internal-access#basic-service-communication).
+
Each port has following attributes:
-
- Parameter
- Description
-
- port
- Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
-
- protocol
- Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
-
- httpSupport
- Optional. httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of public access. httpSupport = true is available only in combination with the TCP protocol.
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
+
+
+
protocol
+
Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
+
+
+
httpSupport
+
Optional.httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). httpSupport = true is available only in combination with the TCP protocol.
+
+
+
+
### prepareCommands
+
_OPTIONAL._ Customises the .NET runtime environment by installing additional dependencies or tools to the runtime base environment.
+
+
The base .NET environment contains {data.alpine.default}, the selected
- major version of .NET, Zerops command line tool and `ASP .NET` and `git`. To install additional packages
+ major version of .NET, [Zerops command line tool](/references/cli) and `ASP .NET` and `git`. To install additional packages
or tools add one or more prepare commands:
+
+
```yaml
zerops:
# hostname of your service
@@ -4201,6 +5940,7 @@ zerops:
# ==== how to build your application ====
build:
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -4210,29 +5950,47 @@ zerops:
- curl something else
...
```
+
When the first deploy with a defined prepare attribute is triggered, Zerops will
+
1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order
+
:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/dotnet/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.
+
#### Cache of your custom runtime environment
+
Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:
+
1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.
+
To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.
+
When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### Copy folders or files from your build container
+
+
The prepare runtime container contains {data.alpine.default}, the
selected major version of .NET,
- Zerops command line tool and
+ [Zerops command line tool](/references/cli) and
`ASP .NET` and `git`.
+
+
The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).
+
```yaml
zerops:
# hostname of your service
@@ -4241,6 +5999,7 @@ zerops:
build:
...
addToRunPrepare: ./runtime-config.yaml
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -4250,15 +6009,20 @@ zerops:
- curl something else
...
```
+
In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.
+
### initCommands
+
_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Run one or more commands each time a new runtime container
@@ -4267,22 +6031,35 @@ zerops:
initCommands:
- rm -rf ./cache
```
+
These commands are triggered in the runtime container before your .NET application is started via the [start command](#start).
+
:::note
`run.initCommands` run in the `/var/www` directory.
:::
+
Use init commands to clean or initialise your application cache or similar operations.
+
:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/dotnet/how-to/scaling) or when a runtime container is restarted).
+
Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::
+
#### Command exit code
+
If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/dotnet/how-to/logs#runtime-log) to troubleshoot the error.
+
#### Single or separated shell instances
+
You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the runtime environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -4297,56 +6074,82 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/dotnet/how-to/env-variables) in Zerops.
+
### start
+
_REQUIRED._ Defines the start command for your .NET application.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your .NET application start command
start: cd app && dotnet dnet.dll
```
+
### health check
+
_OPTIONAL._ Defines a health check.
+
`healthCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the health check to request a local URL using a HTTP GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your .NET application start command
start: cd app && dotnet dnet.dll
+
# OPTIONAL. Define a health check with a HTTP GET request option.
# Configures the check on http://127.0.0.1:80/status
healthCheck:
@@ -4354,30 +6157,47 @@ zerops:
port: 80
path: /status
```
+
#### exec
+
Configures the health check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
Defines a local command to be run.
- The command has access to the same environment variables as your .NET application.
+
+ The command has access to the same [environment variables](/dotnet/how-to/create#set-secret-environment-variables) as your .NET application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your .NET application start command
start: cd app && dotnet dnet.dll
+
# OPTIONAL. Define a health check with a shell command.
healthCheck:
exec:
@@ -4386,13 +6206,18 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
### crontab
+
_OPTIONAL._ Defines cron jobs.
+
Setup cron jobs in the following format:
+
```yaml
zerops:
# define hostname of your service
- setup: app
+
# ==== how to run your application ====
run:
crontab:
@@ -4401,40 +6226,62 @@ zerops:
# REQUIRED. Sets the interval time to execute:
timing: "0 * * * *"
```
+
Read more about setting up [cron](/zerops-yaml/cron) in Zerops.
+
## Deploy configuration
+
### readiness check
+
_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/dotnet/how-to/deploy-process#readiness-checks) in Zerops.
+
`readinessCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the readiness check to request a local URL using a http GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -4443,30 +6290,48 @@ zerops:
httpGet:
port: 80
path: /status
+
# ==== how to run your application ====
run: ...
```
+
Read more about how the [readiness check works](/dotnet/how-to/deploy-process#readiness-checks) in Zerops.
+
#### exec
+
Configures the readiness check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
Defines a local command to be run.
- The command has access to the same environment variables as your .NET application.
+
+ The command has access to the same [environment variables](/dotnet/how-to/create#set-secret-environment-variables) as your .NET application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -4478,8 +6343,10 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
Read more about how the [readiness check works](/dotnet/how-to/deploy-process#readiness-checks) in Zerops.
+
----------------------------------------
# Dotnet > How To > Build Process
@@ -4496,35 +6363,60 @@ Read more about how the [readiness check works](/dotnet/how-to/deploy-process#re
# Dotnet > How To > Create
+
Zerops provides a .NET runtime service with extensive build support. .NET runtime is highly scalable and customisable to suit both development and production.
+
## Create .NET service using Zerops GUI
+
First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new .NET service:
+
+[Video: /vids/services/dotnet.webm](/vids/services/dotnet.webm)
+
### Choose .NET version
+
Following .NET versions are currently supported:
+
:::info
You can [change](/dotnet/how-to/upgrade) the major version at any time later.
:::
+
### Set a hostname
+
Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.
+
#### Limitations:
+
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::
+
### Set secret environment variables
+
Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.
+
Setting the secret environment variables is optional. You can set them later in Zerops GUI.
+
Read more about [different types of env variables](/dotnet/how-to/env-variables#service-env-variables) in Zerops.
+
## Create .NET service using zCLI
+
zCLI is the Zerops command-line tool. To create a new .NET service via the command-line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/dotnet/how-to/create#create-a-project-description-file)
3. [Create a project with a .NET and PostgreSQL service](#full-example)
+
### Create a project description file
+
Zerops uses a yaml format to describe the project infrastructure.
+
#### Basic example:
+
Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -4545,13 +6437,18 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes your future project infrastructure. The project will contain one .NET version 6 service with default [auto scaling](/dotnet/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/dotnet/how-to/build-pipeline#ports). Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
#### Full example:
+
Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:
+
```yaml
# basic project data
project:
@@ -4596,113 +6493,172 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain a .NET service and a [PostgreSQL](/postgresql/overview) service.
+
.NET service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/dotnet/how-to/build-pipeline#ports). .NET service will run on version 6 with a custom vertical and horizontal scaling. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
-
- Parameter
- Description
- Limitations
-
- name
- The name of the new project. Duplicates are allowed.
-
- description
- Optional. Description of the new project.
- Maximum 255 characters.
-
- tags
- Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
-
+
+
+
+
+
Parameter
+
Description
+
Limitations
+
+
+
+
+
name
+
The name of the new project. Duplicates are allowed.
+
+
+
+
description
+
Optional. Description of the new project.
+
Maximum 255 characters.
+
+
+
tags
+
Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
+
+
+
+
+
At least one service in `services:` section is required. You can create a project with multiple services. The example above contains .NET and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
hostname
+
The unique service identifier.
-
+
The hostname of the new database will be set to the `hostname` value.
-
- Limitations:
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+ Limitations:
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
type
+
Specifies the service type and version.
+
See what [.NET service types](/references/import-yaml/type-list#runtime-services) are currently supported.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto scaling parameters.
-
+
+
+
+
verticalAutoscaling
+
+ Optional. Defines [custom vertical auto scaling parameters](/dotnet/how-to/create#set-auto-scaling-configuration).
+
All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
- minContainers
-
- Optional. Default = 1. Defines the minimum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
- cpuMode
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
- minCpu/maxCpu
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
- minRam/maxRam
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
- minDisk/maxDisk
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
minContainers
+
+ Optional. Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/dotnet/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- maxContainers
-
- Defines the maximum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
maxContainers
+
+ Defines the maximum number of containers for [horizontal autoscaling](/dotnet/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- envSecrets
-
- Optional. Defines one or more secret env variables as a key value map. See env variable restrictions.
-
+
+
+
+
envSecrets
+
+ Optional. Defines one or more secret env variables as a key value map. See env variable [restrictions](/dotnet/how-to/env-variables#env-variable-restrictions).
+
+
+
+
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add .NET service to an existing project
+
#### Example:
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -4723,33 +6679,38 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one .NET service version 6 with default [auto scaling](/dotnet/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the import.yaml file is 100 kB.
+
----------------------------------------
# Dotnet > How To > Customize Runtime
-System packages for processing: When your app processes images, videos, or files (requiring packages like sudo apk add imagemagick)',
- 'Native libraries: When your .NET packages require system libraries that aren\'t in the default environment',
- 'Development tools: When you need additional debugging or profiling tools',
- 'Different base OS: When you need Ubuntu instead of Alpine for specific compatibility requirements'
-]} />
+
----------------------------------------
@@ -4803,13 +6764,21 @@ System packages for processing: When your app processes images, videos, or files
# Dotnet > Overview
+
[.NET ↗](https://dotnet.microsoft.com/en-us/) is the free, open-source, cross-platform framework for building modern apps and powerful cloud services..
+
As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-dotnet-hello-world), a **_recipe_**, containing the most simple .NET web application. The repo will be used as a source from which the app will be built.
- This is the most bare-bones example of .NET running in Zerops — as few libraries as possible,
+
+### 🚀 Feel free to deploy the recipe yourself
+
+This is the most bare-bones example of .NET running in Zerops — as few libraries as possible,
just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.
-
+
+ [Deploy "dotnet" recipe on Zerops](https://app.zerops.io/recipe/?lf=dotnet)
+
1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-dotnet-hello-world/blob/main/import-project/description.yaml)):
+
```yaml
project:
name: my-first-project
@@ -4821,86 +6790,145 @@ services:
buildFromGit: https://github.com/zeropsio/recipe-dotnet-hello-world@main
enableSubdomainAccess: true
```
+
3. Click on **Import project** and wait until all pipelines have finished.
+
**That's it, your application is now up and running! :star: Let's check it works:**
+
1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://helloworld-24-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see
+
```
Hello, World!
```
+
:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::
+
## How to start
+
+- [Care for details?](/dotnet/how-to/create) — Dive in all Zerops has to offer for your .NET application.
+
## Feature Highlights
+
+- [Create .NET service](/dotnet/how-to/create) — Start with creating a .NET service using GUI or zCLI.
+- [zerops.yaml](/dotnet/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
+- [Scaling configuration](/dotnet/how-to/scaling) — Set up scaling of your .NET application so that it runs smoothly while using only necessary resources.
+
{" "}
+
+- [Customize build environment](/dotnet/how-to/build-process#customize-build-environment)
+- [Customize runtime environment](/dotnet/how-to/customize-runtime)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+
+- [FAQ](/dotnet/faq) — Most common questions in one place.
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Elasticsearch > Overview
+
Deploy [Elasticsearch](https://www.elastic.co/elasticsearch/) instances in Zerops with flexible scaling options, from standalone nodes to highly available clusters.
+
## Supported Versions
+
Currently supported Elasticsearch versions:
+
Import configuration version:
+
+- `elasticsearch@9.2`
+- `elasticsearch@8.16`
+
## Connection Details
+
- **Port**: 9200
- **Protocol**: HTTP only
- **Internal Access**: `http://{hostname}:9200`
- **Basic auth security**
- **User**: `elastic`
- **Password**: randomly generated during service creation, find under **Access Details** in service detail
+
#### Example
```sh
curl -u elastic:generatedpassword http://elasticsearch:9200
```
+
## Configuration Options
+
### Plugin Management
+
You can configure Elasticsearch plugins using a comma-separated list in your environment secrets:
+
```yaml
envSecrets:
PLUGINS: "analysis-icu,ingest-attachment"
```
+
**Plugin Configuration Details:**
- Defines plugins to install at service startup
- **Format**: `plugin1,plugin2,...`
- Service automatically installs specified plugins during initialization
- Removing a plugin from this list triggers uninstallation on service restart
+
### JVM Heap Allocation
+
Control the JVM heap size as a percentage of container memory:
+
```yaml
envSecrets:
HEAP_PERCENT: "75"
```
+
**Heap Configuration Details:**
- Value represents the percentage of container memory allocated to JVM heap
- **Default**: 50% of available container memory
- **Valid range**: 1-100
- To increase available memory, adjust the service's RAM allocation in scaling configuration
+
:::note Requires Restart
Changes to HEAP_PERCENT require a service restart to take effect.
:::
+
## Backup
+
Elasticsearch backups are created using `elasticdump`:
+
- **Format**: `.gz` (per index/component dump)
- **Tooling**: `elasticdump`
- **Compression**: Gzip compressed JSON data
+
For backup configuration, scheduling, retention policies, and management options, see the [Zerops Backups](/features/backup) documentation.
+
### Restoring Backups
+
To restore an Elasticsearch backup:
+
1. **Download** the backup file (`.gz`) from the Zerops UI
2. **Extract** the compressed files to access the JSON data
3. **Prepare** your target environment (clean existing indices or use a new instance)
4. **Restore** using either:
- **elasticdump tool**: Use the same tool that created the backup for restoration via Zerops VPN or during deployment
- **Elasticsearch API**: Import the data through REST API [calls](https://www.elastic.co/docs/deploy-manage/tools/snapshot-and-restore/restore-snapshot)
+
For assistance with the restoration process, contact Zerops support.
+
## Example Configuration
+
```yaml
services:
- hostname: elasticsearch
@@ -4910,7 +6938,9 @@ services:
PLUGINS: "analysis-icu,ingest-attachment"
HEAP_PERCENT: "75"
```
+
## Related Resources
+
- [Elasticsearch Official Documentation](https://www.elastic.co/guide/index.html)
- [Available Elasticsearch Plugins](https://www.elastic.co/guide/en/elasticsearch/plugins/current/index.html)
@@ -4918,9 +6948,13 @@ services:
# Elixir > How To > Build Pipeline
+
Zerops provides a customizable build and runtime environment for your Elixir application.
+
## Add zerops.yaml to your repository
+
Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:
+
```yaml
zerops:
# define hostname of your service
@@ -4929,49 +6963,63 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: elixir@latest
+
# OPTIONAL. Set the operating system for the build environment.
# os: ubuntu
+
# OPTIONAL. Customise the build environment by installing additional packages
# or tools to the base build environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Build your application
buildCommands:
- mix deps.get --only prod
- mix compile
- mix release
+
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles: _build/prod/rel/app/
+
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: node_modules
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: elixir@latest
+
# OPTIONAL. Sets the internal port(s) your app listens on:
ports:
# port number
- port: 3000
+
# OPTIONAL. Customise the runtime Elixir environment by installing additional
# dependencies to the base Elixir runtime environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Run one or more commands each time a new runtime container
# is started or restarted. These commands are triggered before
# your Elixir application is started.
# initCommands:
# - rm -rf ./cache
+
# REQUIRED. Your Elixir application start command
start: npm start
```
+
The top-level element is always `zerops`.
+
### Setup
+
The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:
+
```yaml
zerops:
# definition for app service
@@ -4982,6 +7030,7 @@ zerops:
deploy: ...
# required
run: ...
+
# definition for api service
- setup: api
# optional
@@ -4991,11 +7040,19 @@ zerops:
# required
run: ...
```
+
Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.
+
## Build pipeline configuration
+
### base
+
_REQUIRED._ Sets the base technology for the build environment.
+
Following options are available for Elixir builds:
+
+- `1.16`
+
```yaml
zerops:
# hostname of your service
@@ -5006,12 +7063,18 @@ zerops:
base: elixir@latest
...
```
+
+
The base build environment contains {data.alpine.default}, the selected
- major version of Elixir, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
+ major version of Elixir, [Zerops command line tool](/references/cli), `npm`, `yarn`, `git` and `npx` tools.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -5025,34 +7088,52 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).
+
To customise your build environment use the [prepareCommands](#preparecommands) attribute.
+
:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::
+
### os
+
_OPTIONAL._ Sets the operating system for the build environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customised.
:::
+
:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::
+
### prepareCommands
+
_OPTIONAL._ Customises the build environment by installing additional dependencies or tools to the base build environment.
+
The base build environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- selected version of Elixir defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `npm`, `yarn`, `git` and `npx` tools
+
To install additional packages or tools add one or more prepare commands:
+
```yaml
zerops:
# hostname of your service
@@ -5061,6 +7142,7 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: elixir@latest
+
# OPTIONAL. Customise the build environment by installing additional packages
# or tools to the base build environment.
prepareCommands:
@@ -5068,20 +7150,31 @@ zerops:
- curl something else
...
```
+
When the first build is triggered, Zerops will
+
1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order
+
The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.
+
:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/elixir/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### buildCommands
+
_OPTIONAL._ Defines build commands.
+
```yaml
zerops:
# hostname of your service
@@ -5090,42 +7183,59 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: elixir@latest
+
# OPTIONAL. Build your application
buildCommands:
- npm i
- npm run build
...
```
+
Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.
+
Before the build commands are triggered the build container contains:
+
1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code
+
#### Run build commands as a single shell instance
+
Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.
+
```yaml
buildCommands:
- |
npm i
npm run build
```
+
#### Run build commands as a separate shell instances
+
When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.
+
```yaml
buildCommands:
- npm i
- npm run build
```
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/elixir/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.
+
```yaml
buildCommands:
- npm i --verbose
- npm run build
```
+
If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.
+
### deployFiles
-_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use `.deployignore` file.
+
+_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.
+
```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
@@ -5134,56 +7244,81 @@ deployFiles:
- package.json
- node_modules
```
+
Determines files or folders produced by your build, which should be deployed to your runtime service containers.
+
The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.
+
The files/folders will be placed into `/var/www` folder in runtime, e.g. `./src/assets/fonts` would result in `/var/www/src/assets/fonts`.
+
#### Examples
+
Deploys a folder, and a file from the project root directory:
+
```yaml
deployFiles:
- dist
- package.json
```
+
Deploys the whole content of the build container:
+
```yaml
deployFiles: .
```
+
Deploys a folder, and a file in a defined path:
+
```yaml
deployFiles:
- ./path/to/file.txt
- ./path/to/dir/
```
+
#### How to use a wildcard in the path
+
Zerops supports the `~` character as a wildcard for one or more folders in the path.
+
Deploys all `file.txt` files that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/file.txt
```
+
Deploys all folders that are located in any path that begins with `/path/to/`
+
```yaml
deployFiles: ./path/to/~/
```
+
Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/
```
+
:::note Example
By default, `./src/assets/fonts` deploys to `/var/www/src/assets/fonts`, keeping the full path. Adding `~`, like `./src/assets/~fonts`, shortens it to `/var/www/fonts`
:::
#### .deployignore
-Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as `.gitignore`.
+
+Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as [`.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format).
+
To ignore a specific file or directory path, start the pattern with a forward slash (`/`). Without the leading slash, the pattern will match files with that name in any directory.
+
:::tip
For consistency, it's recommended to configure both your `.gitignore` and `.deployignore` files with the same patterns.
:::
+
Examples:
+
```yaml title="zerops.yaml"
zerops:
- setup: app
build:
deployFiles: ./
```
+
```text title=".deployignore"
/src/file.txt
```
@@ -5195,22 +7330,33 @@ This example above ignores `file.txt` in ANY directory named `src`, such as:
- `/src/file.txt`
- `/folder2/folder3/src/file.txt`
- `/src/src/file.txt`
+
:::note
-`.deployignore` file also works with `zcli service deploy` command.
+`.deployignore` file also works with [`zcli service deploy`](/references/zcli/commands#deploy) command.
:::
+
### cache
+
_OPTIONAL._ Defines which files or folders will be cached for the next build.
+
```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```
+
The cache attribute helps optimize build times by preserving specified files between builds.
+
The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).
+
Learn more about the [build cache system](/features/build-cache) in Zerops.
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the build environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -5219,6 +7365,7 @@ zerops:
build:
base: elixir@latest
…
+
# OPTIONAL. Defines the env variables for the build environment:
envVariables:
NODE_ENV: production
@@ -5227,12 +7374,20 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/elixir/how-to/env-variables) in Zerops.
+
## Runtime configuration
+
### base
+
_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Elixir version for your runtime.
+
Following options are available for Elixir builds:
+
+- `1.16`
+
```yaml
zerops:
# hostname of your service
@@ -5242,18 +7397,25 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: elixir@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: elixir@latest
...
```
+
+
The base runtime environment contains {data.alpine.default}, the
selected major version of Elixir, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -5263,6 +7425,7 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: elixir@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
@@ -5272,36 +7435,58 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [run base environments](/zerops-yaml/base-list).
+
To customise your build environment use the `prepareCommands` attribute.
+
### os
+
_OPTIONAL._ Sets the operating system for the runtime environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customised.
:::
+
### ports
+
_OPTIONAL._ Specifies one or more internal ports on which your application will listen.
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
For example, to connect to a Elixir service with hostname = "app" and port = 3000 from another service of the same project, simply use `app:3000`. Read more about [how to access a Elixir service](/references/networking/internal-access#basic-service-communication).
+
Each port has following attributes:
+
| parameter | description |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| port | Defines the port number. You can set any port number between _10_ and _65435_. Ports outside this interval are reserved for internal Zerops systems. |
| protocol | **Optional.** Defines the protocol. Allowed values are `TCP` or `UDP`. Default value is `TCP`. |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |
+
### prepareCommands
+
_OPTIONAL._ Customises the Elixir runtime environment by installing additional dependencies or tools to the runtime base environment.
+
+
The base Elixir environment contains {data.alpine.default} the selected
- major version of Elixir, Zerops command line tool and `npm`, `yarn`, `git` and `npx` tools. To install
+ major version of Elixir, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools. To install
additional packages or tools add one or more prepare commands:
+
+
```yaml
zerops:
# hostname of your service
@@ -5309,6 +7494,7 @@ zerops:
# ==== how to build your application ====
build:
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -5318,27 +7504,45 @@ zerops:
- curl something else
...
```
+
When the first deploy with a defined prepare attribute is triggered, Zerops will
+
1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order
+
:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/elixir/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.
+
#### Cache of your custom runtime environment
+
Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:
+
1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.
+
To invalidate the custom runtime cache go to `yyy`
+
When the custom runtime cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### Copy folders or files from your build container
+
+
The prepare runtime container contains {data.alpine.default}, the
- selected major version of Elixir, Zerops command line tool and `npm`, `yarn`, `git` and `npx` tools.
+ selected major version of Elixir, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools.
+
+
The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).
+
```yaml
zerops:
# hostname of your service
@@ -5347,6 +7551,7 @@ zerops:
build:
...
addToRunPrepare: ./runtime-config.yaml
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -5356,15 +7561,20 @@ zerops:
- curl something else
...
```
+
In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.
+
### initCommands
+
_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Run one or more commands each time a new runtime container
@@ -5373,22 +7583,35 @@ zerops:
initCommands:
- rm -rf ./cache
```
+
These commands are triggered in the runtime container before your Elixir application is started via the [start command](#start).
+
:::note
`run.initCommands` run in the `/var/www` directory.
:::
+
Use init commands to clean or initialise your application cache or similar operations.
+
:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/elixir/how-to/scaling) or when a runtime container is restarted).
+
Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::
+
#### Command exit code
+
If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/elixir/how-to/logs#runtime-log) to troubleshoot the error.
+
#### Single or separated shell instances
+
You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the runtime environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -5403,57 +7626,84 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/elixir/how-to/env-variables) in Zerops.
+
### start
+
_REQUIRED._ Defines the start command for your Elixir application.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Elixir application start command
start: npm start
```
+
We recommend starting your Elixir application using `npm start`.
+
### health check
+
_OPTIONAL._ Defines a health check.
+
`healthCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the health check to request a local URL using a HTTP GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Elixir application start command
start: npm start
+
# OPTIONAL. Define a health check with a HTTP GET request option.
# Configures the check on http://127.0.0.1:80/status
healthCheck:
@@ -5461,25 +7711,32 @@ zerops:
port: 80
path: /status
```
+
#### exec
+
Configures the health check to run a local command.
Following attributes are available:
+
| Parameter | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/elixir/how-to/create#set-secret-environment-variables) as your Elixir application.
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below. |
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Elixir application start command
start: npm start
+
# OPTIONAL. Define a health check with a shell command.
healthCheck:
exec:
@@ -5488,13 +7745,18 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
### crontab
+
_OPTIONAL._ Defines cron jobs.
+
Setup cron jobs in the following format:
+
```yaml
zerops:
# define hostname of your service
- setup: app
+
# ==== how to run your application ====
run:
crontab:
@@ -5503,14 +7765,23 @@ zerops:
# REQUIRED. Sets the interval time to execute:
timing: "0 * * * *"
```
+
Read more about setting up [cron](/zerops-yaml/cron) in Zerops.
+
## Deploy configuration
+
### readiness check
+
_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/elixir/how-to/deploy-process#readiness-checks) in Zerops.
+
`readinessCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the readiness check to request a local URL using a http GET method.
+
Following attributes are available:
+
@@ -5540,13 +7811,16 @@ If your application requires a https request, set scheme: https
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -5555,25 +7829,33 @@ zerops:
httpGet:
port: 80
path: /status
+
# ==== how to run your application ====
run: ...
```
+
Read more about how the [readiness check works](/elixir/how-to/deploy-process#readiness-checks) in Zerops.
+
#### exec
+
Configures the readiness check to run a local command.
Following attributes are available:
+
| Parameter | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/elixir/how-to/create#set-secret-environment-variables) as your Elixir application.
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below. |
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -5585,8 +7867,10 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
Read more about how the [readiness check works](/elixir/how-to/deploy-process#readiness-checks) in Zerops.
+
----------------------------------------
# Elixir > How To > Build Process
@@ -5603,34 +7887,58 @@ Read more about how the [readiness check works](/elixir/how-to/deploy-process#re
# Elixir > How To > Create
+
Zerops provides a powerful Elixir runtime service with extensive build support. The Elixir runtime is highly scalable and customizable to suit your development and production needs. With just a few clicks or commands, you can have a production-ready Elixir environment up and running in no time.
+
## Create a Elixir service using Zerops GUI
+
First, set up a project in the Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu under the **Services** section. From there, you can add a new Elixir service:
+
+[Video: /vids/services/elixir.webm](/vids/services/elixir.webm)
+
### Choose a Elixir version
+
Zerops supports the following Elixir versions:
+
:::info
You can easily [upgrade](/elixir/how-to/upgrade) the major version at any time later.
:::
+
### Set a hostname
+
Enter a unique service identifier like "app", "cache", "gui", etc. Duplicate services with the same name within the same project are not allowed.
+
#### Limitations:
+
- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::
+
### Set secret environment variables
+
Add environment variables with sensitive data, such as passwords, tokens, salts, certificates, etc. These will be securely saved inside Zerops and added to your runtime service upon start.
+
Setting secret environment variables is optional. You can always set them later in the Zerops GUI.
+
Read more about the [different types of environment variables](/elixir/how-to/env-variables#service-env-variables) in Zerops.
+
## Create a Elixir service using zCLI
+
zCLI is the Zerops command-line tool. To create a new Elixir service via the command line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/elixir/how-to/create#create-a-project-description-file)
3. [Create a project with a Elixir and PostgreSQL service](#full-example)
+
### Create a project description file
+
Zerops uses a YAML format to describe the project infrastructure.
+
#### Basic example:
+
Create a directory called `my-project`. Inside the `my-project` directory, create a `description.yaml` file with the following content:
```yaml
# basic project data
@@ -5652,13 +7960,18 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes your future project infrastructure. The project will contain one Elixir version 20 service with default [auto scaling](/elixir/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/elixir/how-to/build-pipeline#ports). Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
#### Full example:
+
Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:
+
```yaml
# basic project data
project:
@@ -5703,103 +8016,171 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain a Elixir service and a [PostgreSQL](/postgresql/overview) service.
+
Elixir service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/elixir/how-to/build-pipeline#ports). Elixir service will run on version 20 with a custom vertical and horizontal scaling. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
+
| Parameter | Description | Limitations |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **name** | The name of the new project. Duplicates are allowed. | |
| **description** | **Optional.** Description of the new project. | Maximum 255 characters. |
| **tags** | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |
| **tags** | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |
+
At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Elixir and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
+ hostname
+
+
The unique service identifier.
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
+ type
+
+
Specifies the service type and version.
-
+
See what [Elixir service types](/references/import-yaml/type-list#runtime-services) are currently supported.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto scaling parameters.
+
+
+
+
+ verticalAutoscaling
+
+
+ Optional. Defines [custom vertical auto scaling parameters](/elixir/how-to/create#set-auto-scaling-configuration).
+
All verticalAutoscaling attributes are optional. Not specified
attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
- minContainers
-
- Optional. Default = 1. Defines the minimum number of containers
- for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
+ - cpuMode
+
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
+ - minCpu/maxCpu
+
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
+ - minRam/maxRam
+
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
+ - minDisk/maxDisk
+
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
+ minContainers
+
+
+ Optional. Default = 1. Defines the minimum number of containers
+ for [horizontal autoscaling](/elixir/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- maxContainers
-
- Defines the maximum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
+ maxContainers
+
+
+ Defines the maximum number of containers for [horizontal autoscaling](/elixir/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- envSecrets
-
- Optional. Defines one or more secret env variables as a key value
- map. See env variable restrictions.
-
+
+
+
+
+ envSecrets
+
+
+ Optional. Defines one or more secret env variables as a key value
+ map. See env variable [restrictions](/elixir/how-to/env-variables#env-variable-restrictions).
+
+
+
+
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add Elixir service to an existing project
+
#### Example:
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -5820,33 +8201,38 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Elixir service version 20 with default [auto scaling](/elixir/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the import.yaml file is 100 kB.
+
----------------------------------------
# Elixir > How To > Customize Runtime
-System packages for processing: When your app processes images, videos, or files (requiring packages like sudo apk add imagemagick)',
- 'Erlang libraries: When you need additional Erlang libraries not included by default',
- 'Native dependencies: When your Mix dependencies require system libraries that aren\'t in the default environment',
- 'Different base OS: When you need Ubuntu instead of Alpine for specific compatibility requirements'
-]} />
+
----------------------------------------
@@ -5900,124 +8286,196 @@ System packages for processing: When your app processes images, videos, or files
# Elixir > Overview
+
[Elixir ↗](https://elixir.org/en) is an asynchronous event-driven JavaScript runtime, which is designed to build scalable network applications.
+
As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-elixir), a **_recipe_**, containing the most simple Elixir web application. The repo will be used as a source from which the app will be built.
- This is the most bare-bones example of Elixir app running in Zerops — as few libraries as possible,
+
+### 🚀 Feel free to deploy the recipe yourself
+
+This is the most bare-bones example of Elixir app running in Zerops — as few libraries as possible,
just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.
-
+
+ [Deploy "elixir" recipe on Zerops](https://app.zerops.io/recipe/?lf=elixir)
+
1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
+
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-elixir/blob/main/zerops-project-import.yaml)):
+
```yaml
project:
name: recipe-elixir
tags:
- zerops-recipe
+
services:
- hostname: api
type: elixir@1.16
enableSubdomainAccess: true
buildFromGit: https://github.com/zeropsio/recipe-elixir
+
- hostname: db
type: postgresql@16
mode: NON_HA
priority: 1
```
+
3. Click on **Import project** and wait until all pipelines have finished.
+
**That's it, your application is now up and running! :star: Let's check it works:**
+
1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://api-808-4000.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see
+
```
{"message":"This is a simple Elixir application running in Zerops.io, each request adds an entry to the PostgreSQL database and returns a count. See the source repository (https://github.com/zeropsio/recipe-elixir) for more information.","newEntry":"e64be640-d6c2-4be8-93ac-d1e40e56fa06","count":1}
```
+
:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::
+
## How to start
+
It doesn't matter whether it's your first curious introduction to Zerops, you have already mastered the basics and are looking for a tiny detail or inspiration. Below, choose a section that fits your needs:
+
+- [Care for details?](/elixir/how-to/create) — Dive in all Zerops has to offer for your Elixir application.
+- [Elixir recipes](https://github.com/zeropsio?q=elixir&type=all&language=&sort=) — Get inspired by already existing repositories, ready to be imported to Zerops.
+
## Feature Highlights
+
+- [Create Elixir service](/elixir/how-to/create) — Start with creating a Elixir service using GUI or zCLI.
+- [Zerops.yaml](/elixir/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
+- [Scaling configuration](/elixir/how-to/scaling) — Set up scaling of your Elixir application so that it runs smoothly while using only necessary resources.
+
{" "}
+
+- [Customize build environment](/elixir/how-to/build-process#customize-build-environment)
+- [Customize runtime environment](/elixir/how-to/customize-runtime)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+
+- [FAQ](/elixir/faq) — Most common questions in one place.
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Features > Access
+
Zerops provides multiple ways to access your services, whether you need internal communication between services, secure access from your development machine, or public access from the internet.
+
:::note
By default, your services are not publicly accessible until you configure external access. Internal communication between services within the same project works automatically.
:::
+
## How Zerops Networking Works
+
Every Zerops project includes a **shared networking infrastructure** that handles all access methods:
+
**Private Project Network:**
- All services within a project share a dedicated private network
- Services communicate directly using hostnames and internal ports
- Traffic stays isolated within your project
+
**Public Access Infrastructure:**
- **Core (L3) Balancer** manages IP addresses and direct port access
- **L7 HTTP Balancer** handles domain routing and SSL termination
- Can be extensively configured for advanced routing, performance optimization, and custom behaviors
- See the [L7 Balancer Configuration Guide](/references/networking/l7-balancer-config) for detailed options
- Both are shared across all services in your project
+
**Secure External Access:**
- **Built-in VPN** provides secure tunnel access to your project's private network
- Useful for development, debugging, and administration
+
## Internal Access
+
:::tip Complete Internal Access Setup
See the [Internal access reference guide](/references/networking/internal-access).
:::
+
Services within the same project can communicate directly using hostnames and internal ports. No additional configuration required.
+
**Example:** Connect to your `api` service on port 3000:
```
http://api:3000
```
+
**Key points:**
- Use service hostname as the address
- Use HTTP (not HTTPS) for internal communication
- Access internal ports defined in your service configuration
- Communication is automatically isolated from other projects
+
### Environment Variables
+
Zerops automatically creates environment variables to help with internal connections between services.
+
## VPN Access
:::tip Complete VPN Setup
See the [VPN reference guide](/references/networking/vpn).
:::
+
Connect securely to your project's internal network from your local machine:
+
```bash
# Connect to your project
-zcli vpn up
+zcli vpn up
+
# Access services using internal hostnames
curl http://api:3000/health
+
# Disconnect when done
zcli vpn down
```
+
## Public Access
+
:::tip Complete Public Access Setup
See the [Public access reference guide](/references/networking/public-access).
:::
+
Make your services accessible from the internet using one of three methods:
+
### Zerops Subdomain
**Best for:** Development and testing
+
- Quick setup with automatic `.zerops.app` subdomains
- Each service gets its own unique subdomain
- Automatic SSL certificate management
- Shared infrastructure (has limitations for production use)
+
### Custom Domain
**Best for:** Production deployments
+
- Use your own domain names
- Better performance with dedicated balancer
- Full control over SSL and routing
- Requires DNS configuration
+
### Direct Port Access
**Best for:** Non-HTTP protocols and specialized use cases
+
- Direct access to specific ports on your services
- Supports any protocol (TCP/UDP)
- Optional firewall configuration
- Uses your project's IP addresses
+
## Next Steps
+
- **Internal access setup:** [Internal Access Reference Guide](/references/networking/internal-access)
- **Public access configuration:** [Public Access Reference Guide](/references/networking/public-access)
- **VPN setup and troubleshooting:** [VPN Reference Guide](/references/networking/vpn)
@@ -6027,162 +8485,232 @@ Make your services accessible from the internet using one of three methods:
# Features > Backup
+
Zerops provides an automated, secure backup system for supported services. This guide covers how to configure, manage, and restore your backups.
+
## Supported Services
+
Zerops provides automated backup functionality for the following services. For specific backup format details and restore instructions, visit each service's documentation: [MariaDB](/mariadb/how-to/backup), [PostgreSQL](/postgresql/how-to/backup), [Qdrant](/qdrant/overview), [Elasticsearch](/elasticsearch/overview), [NATS](/nats/overview), [Meilisearch](/meilisearch/overview), and [Shared Storage](/shared-storage/how-to/backup).
+
## Managing Backups in the UI
+
By default, your data is backed up automatically **every day** between 00:00:00 UTC and 01:00:00 UTC, unless you update your settings.
+
To manage backups, go to the service detail and choose **Backups List & Configuration** in the left menu.
+
From this section, you can:
- Create a one-time backup
- Change the frequency/disable of automatic backups
- Configure retention policies and limits
-
+
### Backup Frequency Options
+
Available schedules:
- **No backups**: Disable automatic backups (not recommended)
- **Once a day**: Daily backups at a specified time
- **Once a week**: Weekly backups on a specific day and time
- **Once a month**: Monthly backups on a specific day and time
- **Custom CRON**: Define a custom schedule using CRON syntax
+
For the Custom CRON option, you can use the following syntax:
-
- Field name
- Allowed values
-
- Minute
- 0-59
-
- Hour
- 0-23
-
- Day
- 1-31
-
- Month
- 1-12
-
- Week Day
- 0–7; both 0 and 7 represent Sunday
-
-Examples:
-- `0 2 * * *` - Every day at 2:00 AM
-- `0 4 * * 0` - Every Sunday at 4:00 AM
-- `0 0 1 * *` - First day of every month at midnight
-- `0 */6 * * *` - Every 6 hours
-### Backup Tagging
-Zerops uses tags to categorize and manage backups:
-**Time-Based Tags** (assigned automatically):
-- `daily`: Every automatic backup
+
+
+
+
+
Field name
+
Allowed values
+
+
+
+
+
Minute
+
0-59
+
+
+
Hour
+
0-23
+
+
+
Day
+
1-31
+
+
+
Month
+
1-12
+
+
+
Week Day
+
0–7; both 0 and 7 represent Sunday
+
+
+
+
+Examples:
+- `0 2 * * *` - Every day at 2:00 AM
+- `0 4 * * 0` - Every Sunday at 4:00 AM
+- `0 0 1 * *` - First day of every month at midnight
+- `0 */6 * * *` - Every 6 hours
+
+### Backup Tagging
+
+Zerops uses tags to categorize and manage backups:
+
+**Time-Based Tags** (assigned automatically):
+- `daily`: Every automatic backup
- `weekly`: First backup of each week (Monday UTC)
- `monthly`: First backup of each month (1st UTC)
+
**User Tags** (custom labels you create):
- Used for organization and identification (e.g., `v2.1-release`, `before-migration`, `monthly-snapshot`)
- Add when creating manual backups - up to 24 characters (letters, numbers, `:-_`)
+
**Protected Tags** (configured in retention policy):
- Backups with these tag names are exempt from automatic deletion, regardless of storage limits
- Define in the backup retention configuration section of the UI and add when creating manual backups
+
:::important
Manual backups don't get automatic time-based tags. Always add a protected tag to preserve critical manual backups.
:::
+
### View and Manage Backup Files
+
In this section, you can:
- Create manual backups
- View all backups with their timestamps and sizes
- Download backups
- Delete backups
-
+
:::note
When creating manual backups via the UI, you'll see immediate feedback. If the backup takes longer than 10 seconds, the process continues in the background. You can verify completion by refreshing the backup list or checking service logs.
:::
+
## Storage and Limits
+
### Project Storage Quotas
+
Each Zerops project has a **technical maximum backup storage limit of 1 TiB**:
- Only full backups are stored
- If a backup would exceed the storage limit, it will not be stored
- This quota is shared across all service backups within the project
+
### Billing
- **Lightweight Project Core**: 5 GB backup storage and 100 GB egress included
- **Serious Project Core**: 25 GB backup storage and 3 TB egress included
+
When you exceed your plan's free limits, **additional charges apply** according to our [pricing](/company/pricing#overage-costs).
+
### Retention Policy and Configuration
+
Zerops manages which backups are kept using a retention policy that you can customize through the UI:
+
**Default Time-Based Retention** (minimums):
- At least 7 daily backups
- At least 4 weekly backups
- At least 3 monthly backups
+
**Default Resource Limits** (maximums):
- Max 50 total backups per service
- Storage limited to your project's 1 TiB technical maximum (with billing for usage beyond free tier)
+
**Customization Options:**
You can modify these defaults in the backup retention configuration interface:
- **Set Protected Tags**: Define tag names that prevent automatic deletion of backups
- **Configure Maximum Limits**: Adjust total number of backups and storage size limits per service
- **Customize Minimum Retention**: Change how many daily, weekly, and monthly backups to keep
- **Set Type-Specific Limits**: Control maximum backups for each type (0 means unlimited, subject to total limits)
+
:::important
Backups with [protected tags](#backup-tagging) and the minimum required time-based backups will always be kept, even if they exceed the limits above. This ensures your critical recovery points are preserved.
:::
+
If you need more storage space, contact our support team.
+
### When Deleting Services or Projects
+
Deleted services/projects have their backups kept for a 7-day grace period before final removal.
+
## Command Line Interface
+
You can also manage backups using the Zerops CLI (zCLI):
+
```bash
# Create a backup
zcli backup create myServiceName
+
# Create a backup with tags (including protection)
zcli backup create myServiceName --tags pre-deploy,protected
```
+
Check `zcli backup --help` for current commands.
+
:::note
zCLI currently focuses on creation; listing/deletion/tag management is primarily via UI.
:::
+
## Restoring Backups
+
Restoration involves downloading backups and using service-specific methods. Zerops facilitates the backup creation and download; the restore action uses service-specific tools and APIs.
+
1. **Download**: Find the backup in the UI (by date/tag) and download it
2. **Prepare**: Set up your target environment (clean existing data or use a new instance)
3. **Restore**: Use service-specific tools via Zerops VPN, run the restore during deployment, or use the service API if available. For service-specific restore instructions, see each service's documentation linked in the [Supported Services](#supported-services) section above.
+
:::info Continuous Improvement
We're working on enhancing the restore experience, potentially including more automated options in the future.
:::
+
For assistance with restoration, contact Zerops support.
+
## High Availability (HA)
+
For multi-node HA services:
- **Automatic Backups**: Run on a randomly selected healthy node
- **Manual Backups**: Typically run on the primary/designated node (check logs)
- **Cluster State**: Other nodes stay operational
+
## Security
+
Backups are protected with end-to-end encryption:
+
- **Unique Encryption**: Each project gets its own encryption key (X25519)
- **Secure Process**: Data is encrypted immediately as backups are created
- **Zero-Trust**: Even Zerops staff cannot access your raw backup data
- **Isolated Storage**: Backups are stored separately from your regular data
- **Secure Download**: Backups are only decrypted when you download them
+
:::important
When a project is deleted, the encryption key is permanently destroyed after 7 days, making the backup data unrecoverable.
:::
+
## Best Practices
+
1. **Create backups before major changes**:
- Always create a manual backup with a protected tag before database migrations, deployments, or large data operations
- Use descriptive tags like `pre-migration` or `pre-release-v2`
+
2. **Manage storage efficiently**:
- Regularly check usage in the Project Overview & Service Backup tabs to monitor free tier usage and stay within the 1 TiB technical limit
- Remove unnecessary backups, especially those with [protected tags](#backup-tagging)
- Adjust [retention policies](#retention-policy-and-configuration) based on your recovery needs
- Regularly review and clean up old backups to optimize storage usage and minimize overage costs
+
3. **Test your restore process** periodically in a non-production environment to ensure you can recover when needed
+
## Troubleshooting
+
### Storage Quota Issues
**Cause**: High backup frequency, long retention periods, or many protected tags can lead to exceeding free tier limits or approaching technical maximums.
+
**Solutions**:
1. **Review & Prune**: Delete unnecessary manual backups or remove protected status from older backups
2. **Adjust Retention Policy**: Reduce minimum retention counts if your recovery requirements allow
3. **Optimize Schedule**: Reduce backup frequency if daily backups aren't essential
4. **Monitor Costs**: Check usage against your free tier (5GB/25GB) to avoid unexpected overage charges
5. **Contact Support**: If you need assistance managing storage
+
### Backup Failures
**Cause**: Service health issues, resource exhaustion, or platform problems.
+
**Solutions**:
1. **Check Service Logs**: Look for error messages around the scheduled backup time
2. **Verify Service Health**: Ensure the service is running properly with adequate resources
@@ -6193,35 +8721,52 @@ When a project is deleted, the encryption key is permanently destroyed after 7 d
# Features > Build Cache
+
> Zerops implements a sophisticated two-layer caching strategy that optimizes build times while maintaining complete control over the build environment. This documentation explores the architecture, configuration patterns, and practical implementation of the build cache system.
+
## Architecture Overview
+
The build cache operates through two distinct layers:
+
1. **Base Layer**: Comprises the OS, installed dependencies, and prepare commands
2. **Build Layer**: Contains the state after executing build commands
+
The layers work together to create an efficient and predictable build environment, though they are currently coupled in their cache invalidation behavior (invalidating one layer affects the other).
+
### Cache Implementation
+
The caching mechanism is implemented through an efficient file movement strategy. This approach ensures near-instantaneous cache operations through simple directory relocation within the container, implementing the following characteristics:
+
- Files are moved between `/build/source` and `/build/cache` using container-level rename operations
- No packaging, compression, or network transfer is involved
- Cache preservation is achieved through simple directory relocation within the container
- Files maintain their original state and permissions throughout the process
+
:::note
See detailed [build process lifecycle](#build-process-lifecycle).
:::
+
## Configuration Guide
+
### Essential zerops.yaml Fields
+
The following fields in `zerops.yaml` affect build cache behavior:
+
**Direct Cache Configuration**:
- `build.cache`: Explicitly defines what should be cached through paths or patterns
+
**Cache Invalidation Triggers**:
These parameters trigger cache invalidation when modified:
- `build.os`: Base operating system selection
- `build.base`: Pre-installed software stacks and runtimes
- `build.prepareCommands`: System preparation and dependency installation
- `build.cache`: Changes to cache configuration
+
**Build Artifact Generation**:
- `build.buildCommands`: Generates the build artifact that will be deployed.
+
## Cache Configuration Patterns
+
### Pattern 1: System-Wide Cache Control
```yaml
build:
@@ -6229,20 +8774,25 @@ build:
# OR
cache: false # Intended to disable all caching
```
+
The boolean values provide system-wide cache control:
+
`cache: true`:
- Preserves the entire build container state
- Maintains system-level package installations
- Ideal for globally installed packages (Python/PHP packages, Go modules)
+
`cache: false`:
- Intended to disable all caching
- Currently, due to layer coupling, only files within `/build/source` are not cached
- Everything outside `/build/source` remains cached (see [Common Pitfalls: Layer Coupling](#current-pitfalls))
+
### Pattern 2: Path-Specific Caching
```yaml
# Single path
build:
cache: node_modules
+
# Multiple paths
build:
cache:
@@ -6250,16 +8800,21 @@ build:
- package-lock.json
- .build
```
+
Execution flow:
1. Source code extraction to `/build/source`
2. Build command execution
3. Specified path preservation in `/build/cache`
4. Cached content restoration (no-clobber mode - source files take precedence)
+
:::tip
Ideal for non-versioned dependencies in your working directory (e.g., `node_modules`, `vendor`, `.venv`).
:::
+
## Path Pattern Reference
+
Zerops supports [Go's filepath.Match](https://pkg.go.dev/path/filepath#Match) syntax. Consider this example structure:
+
```
├── node_modules/
├── package.json
@@ -6269,6 +8824,7 @@ Zerops supports [Go's filepath.Match](https://pkg.go.dev/path/filepath#Match) sy
├── file2.txt
└── file3.md
```
+
Pattern examples and matches:
```yaml
build:
@@ -6277,33 +8833,44 @@ build:
- "package*" # Matches: package.json, package-lock.json
- "node_modules" # Matches: entire node_modules directory recursively
```
+
:::note
All patterns resolve relative to `/build/source`. Path variations like `./node_modules`, `node_modules`, and `node_modules/` are treated identically.
:::
+
## Build Process Lifecycle
+
1. **Initialization Phase**
- Build container startup
- Builder process launch
- Source code loading into `/build/source`
+
2. **Cache Restoration Phase**
- Cached file movement to `/build/source` (no-clobber mode)
- Source file precedence handling
- Conflict logging (no build interruption)
- Cache directory cleanup
+
3. **Build Execution Phase**
- Build command processing
- Artifact packaging (`build.deployFiles`)
+
4. **Cache Preservation Phase**
- Specific cache files movement outside `/build/source`
- `/build/source` directory cleanup
- Container termination
+
## Cache Invalidation Reference
+
The build cache invalidates under these conditions:
+
1. **Manual Triggers**
- API call: `DELETE /service-stack/{id}/build-cache`
- GUI: Manual cache clear action
+
2. **Version Management**
- Backup app version activation via `PUT /app-version/{id}/deploy`
+
3. **Configuration Changes**
Any modifications to:
```yaml
@@ -6312,8 +8879,11 @@ The build cache invalidates under these conditions:
build.prepareCommands
build.cache
```
+
### Current Pitfalls
+
The current implementation has some important characteristics:
+
1. **Layer Coupling**
```yaml
build:
@@ -6326,6 +8896,7 @@ The current implementation has some important characteristics:
cache: false
```
Even with `cache: false`, Go modules outside `/build/source` remain cached.
+
2. **Cascade Invalidation**
```yaml
build:
@@ -6340,7 +8911,9 @@ The current implementation has some important characteristics:
- node_modules
```
Modifying `prepareCommands` invalidates both layers, including cached `node_modules`.
+
## Real-World Implementation Examples
+
### Node.js Project with TypeScript
```yaml
build:
@@ -6354,6 +8927,7 @@ build:
- .turbo
- package-lock.json
```
+
### Go Project with Multiple Dependencies
```yaml
build:
@@ -6365,6 +8939,7 @@ build:
- go build -o bin/app cmd/main.go
cache: true # Caches entire Go modules directory
```
+
### PHP/Laravel Project
```yaml
build:
@@ -6376,147 +8951,227 @@ build:
- vendor
- composer.lock
```
+
## Debugging and Monitoring
+
* **Build Logs**
- Cache operations are detailed in build logs
- File conflicts during restoration are logged
- Cache preservation status is visible
+
## Implementation Best Practices
+
### Cache Strategy Optimization
+
1. **Layer Management**
- Maintain stable `prepareCommands` to prevent cache invalidation
- Group related prepare commands logically
+
2. **Performance Optimization**:
- Cache package manager lock files alongside dependency directories
- Use system-wide caching (`cache: true`) for languages with global package managers
+
3. **Performance Tuning**
- Leverage system-wide caching for complex builds
- Monitor build logs for cache operations and potential conflicts
- Use explicit patterns for precise control
- Don't over-optimize – the system handles large caches efficiently
+
## Future Development
+
Planned system enhancements include:
- Layer independence implementation
- Granular cache control mechanisms
- Enhanced layer management capabilities
- Improved cache invalidation patterns
+
----------------------------------------
# Features > Cdn
+
Zerops CDN is a global content delivery network that brings your static content closer to your users, resulting in faster load times and improved user experience. Built on Nginx and Cloudflare geo-steering technology, our CDN automatically routes users to the nearest server location based on their DNS request.
+
## Key Benefits
+
- **Global Reach**: Serve content from strategic locations across the world
- **Reduced Latency**: Content is delivered from the server closest to your users
- **Simple Integration**: No complex configuration required
+
## Global CDN Infrastructure
+
Zerops CDN operates across **6 strategic regions** to ensure your content is always delivered from a location close to your users:
-
- Region
- Location
- Coverage Area
-
- EU
- CZ
- Prague, Czech Republic
- Primary European coverage + failover for all regions
-
- DE
- Falkenstein, Germany
-
- UK
- London, United Kingdom
- UK and surrounding areas
-
- AU
- Sydney, Australia
- Australia and Oceania
-
- SG
- Singapore, Singapore
- Southeast Asia
-
- CA
- Beauharnois, Canada
- North America
-
+
+
+
+
+
Region
+
Location
+
Coverage Area
+
+
+
+
+
EU
+
CZ
+
Prague, Czech Republic
+
Primary European coverage + failover for all regions
+
+
+
DE
+
Falkenstein, Germany
+
+
+
UK
+
London, United Kingdom
+
UK and surrounding areas
+
+
+
AU
+
Sydney, Australia
+
Australia and Oceania
+
+
+
SG
+
Singapore, Singapore
+
Southeast Asia
+
+
+
CA
+
Beauharnois, Canada
+
North America
+
+
+
+
### Geo-Steering Technology
Zerops CDN's geo-steering technology automatically routes users to the server location closest to them. Here's how it works:
+
* **Automatic routing**: Users are directed to the optimal CDN node based on their geographic location
* **Quick failover**: The DNS TTL is set to just 30 seconds, allowing fast recovery if a node fails
* **Redundancy**: If any node becomes unavailable, Cloudflare automatically redirects traffic to the next closest node
* **Reliable backup**: The EU region serves as the ultimate fallback - if all other nodes go down, EU will always be served in DNS
+
## CDN Modes and Implementation
+
Zerops CDN currently supports two distinct usage modes (with a third mode coming soon), each designed for specific content delivery needs.
+
### Object Storage Mode
+
Perfect for efficiently delivering media files, documents, and other static assets stored in Zerops [Object Storage](/object-storage/overview) to users across different geographical regions.
+
**Setup process:**
1. Create an Object Storage service or select an existing one
2. Enable the CDN option for this service
3. Set appropriate public read access policies for objects you want to serve via CDN
+
**Accessing content:**
```txt
https://storage.cdn.zerops.app/your-bucket/path/to/file
```
+
:::tip
Access the storage CDN URL via the `storageCdnUrl` **project** environment variable `${storageCdnUrl}/your-bucket/path/to/file`.
:::
+
### Static Mode
+
Ideal for caching and delivering static website assets like HTML, CSS, JavaScript, and images served from your custom domains.
+
**Setup process:**
1. Configure domain access for your service through the L7 HTTP Balancer section
2. Access domain settings via the **three dots menu** or **gear icon** next to your domain entry
3. In the "Project Domain Access Modification" dialog, enable the **"Enable CDN for static files"** toggle
4. Optionally enable "Automatically install SSL Certificates" if not already configured
+
**Accessing content:**
```txt
https://static.cdn.zerops.app/your-domain.com/path/to/file
```
+
:::tip
Access the static CDN URL via the `staticCdnUrl` **project** environment variable `${staticCdnUrl}/your-domain.com/path/to/file`.
:::
+
:::warning Wildcard Domains Not Supported
Static CDN cannot be activated for wildcard domains (e.g., *.example.com). You must use specific domain names.
:::
+
### API Mode *(Coming Soon)*
+
Designed for caching API responses to reduce load on your backend services and deliver faster responses to clients.
+
**Environment variable:** Once available, you'll be able to access the API CDN URL via the `apiCdnUrl` **project** environment variable.
+
:::warning
API Mode is currently under development and will be available in a future release.
:::
+
### HTML Implementation Examples
+
Here's how to integrate CDN URLs in your HTML code:
+
```html
+
+
+
+
+
+
+
+
+
+
+
+
+
```
+
### Testing Specific CDN Nodes
+
For testing or debugging purposes, you can bypass the automatic geo-steering and access a specific CDN node directly:
+
```
https://{region}-{mode}.cdn.zerops.app/path/to/content
```
+
Available region prefixes: `cz`, `de`, `au`, `sg`, `uk`, and `ca`
+
**Examples:**
- Test Australia node: `https://au-storage.cdn.zerops.app/my-bucket/test.jpg`
- Test UK node: `https://uk-static.cdn.zerops.app/my-domain.com/index.html`
+
## Managing CDN Content
+
### Cache Lifecycle
+
Content served through Zerops CDN follows this lifecycle:
+
1. **First Request**: When a user requests content not yet in the CDN cache, the request goes to the origin server (your Zerops service), and the response is cached at the CDN node
2. **Subsequent Requests**: Further requests for the same content are served directly from the CDN cache, reducing latency and origin server load
3. **Cache Expiration**: By default, content remains cached for 30 days unless explicitly purged
4. **Automatic Management**: When CDN storage reaches capacity, the least recently used content is automatically removed
+
:::note Important Cache Behavior
Zerops CDN implements a fixed 30-day TTL policy. Currently, HTTP caching headers such as `Cache-Control`, `Expires`, `Pragma`, etc. do not influence CDN caching behavior. To refresh content sooner than the 30-day period, use the [purge API](#api-reference).
+
Your `Cache-Control` headers will still affect browser caching behavior.
:::
+
### When to Purge Cache
+
You should consider purging cached content when:
+
- **Content Updates**: You've updated content but kept the same URL (e.g., updated images, CSS files)
- **Deployment Rollouts**: You've deployed a new version of your application
- **Emergency Removal**: You need to immediately remove content that was accidentally made public
- **Testing Changes**: You want to ensure users see the latest version during testing
+
### Purging Cached Content
+
Zerops provides multiple ways to manage and purge cached content before its normal expiration:
+
- **Command Line**: Use the `zsc cdn purge` [command](/references/zsc#cdn) available in all Zerops containers:
```sh
# Purge all content for a domain
@@ -6526,84 +9181,115 @@ Zerops provides multiple ways to manage and purge cached content before its norm
# Purge specific file
zsc cdn purge example.com "/path/to/my-file$"
```
+
:::important
- This command must be executed in any container within the project that has the CDN-enabled domain active
- Currently only works for [Static Mode](#static-mode) CDN
:::
+
- **API Endpoints**: For programmatic control, use the [API endpoints](#api-reference). Here are ready-to-use curl examples for quickly purging content in your scripts:
+
```sh
# Static mode: Purge all content for a domain
curl --location --request PUT "https://api.app-prg1.zerops.io/api/rest/public/project/$PROJECT_ID/purge-cdn/static/$DOMAIN/*" \
--header "Authorization: Bearer $USER_OR_ACCESS_TOKEN"
```
+
```sh
# Storage mode: Purge all content for object storage
curl --location --request PUT "https://api.app-prg1.zerops.io/api/rest/public/service-stack/$OBJECT_STORAGE_SERVICE_ID/purge-cdn/*" \
--header "Authorization: Bearer $USER_OR_ACCESS_TOKEN"
```
+
#### Purge Pattern Examples
-
- Pattern
- Description
- Example
-
- `/*`
- Purges all content
- Useful after major updates
-
- `/images/*`
- Purges all content in a directory
- Clear all cached images
-
- `/css/main.css$`
- Purges a specific file
- Update a single CSS file
-
- `/2023*`
- Purges content starting with pattern
- Clear content with date prefix
-
+
+
+
+
+
Pattern
+
Description
+
Example
+
+
+
+
+
`/*`
+
Purges all content
+
Useful after major updates
+
+
+
`/images/*`
+
Purges all content in a directory
+
Clear all cached images
+
+
+
`/css/main.css$`
+
Purges a specific file
+
Update a single CSS file
+
+
+
`/2023*`
+
Purges content starting with pattern
+
Clear content with date prefix
+
+
+
+
:::warning Pattern Rules
- Wildcards (`*`) must be at the end of the pattern
- Specific files must include `$` at the end
- Nested wildcards (e.g., `/dir/*.jpg`) are not supported
:::
+
## API Reference
+
Zerops provides a comprehensive set of API endpoints to manage your CDN configuration and content. For complete information about base URLs, authorization, and general API usage, please refer to our [API specification](/references/api).
+
The endpoint links below will take you to the Swagger documentation with detailed request/response schemas and examples:
+
### CDN Management API
+
- **[Enable CDN for Storage ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicServiceStack/EnableStorageCdn)** `PUT /api/rest/public/service-stack/{id}/cdn`
- **[Disable CDN for Storage ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicServiceStack/DisableStorageCdn)** `DELETE /api/rest/public/service-stack/{id}/cdn`
- **[Create Object Storage with CDN ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicServiceStackObjectStorage/CreateObjectStorageV1)** `POST /api/rest/public/service-stack/object_storage_v1`
- **[Create Domain Routing with CDN ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicPublicHttpRouting/CreatePublicHttpRouting)** `POST /api/public/public-http-routing`
- **[Update Domain Routing with CDN ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicPublicHttpRouting/UpdatePublicHttpRouting)** `PUT /api/public/public-http-routing/{id}`
+
### Cache Purge API
+
- **[Purge Storage Mode Cache ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicServiceStack/PurgeStorageCdn)** `PUT /api/rest/public/service-stack/{id}/purge-cdn/{path}`
- **[Purge Static Mode Cache ↗](https://api.app-prg1.zerops.io/api/rest/public/swagger/#/PublicProject/PurgeStaticCdn)** `PUT /api/rest/public/project/{id}/purge-cdn/static/{domain}/{path}`
-- **Purge Api Mode Cache *(Coming soon)***
+- **Purge Api Mode Cache *(Coming soon)***
+
## Troubleshooting
+
Having issues with your CDN? Here are solutions to the most common problems:
+
#### Content Not Updated After Changes
* **Issue:** You've updated content, but users still see the old version.
* **Possible Cause:** The CDN cache is continuing to serve the previously cached version.
* **Solution:**
- Use the [purge API](#api-reference) with the specific content path
- For immediate changes, use versioned file names (e.g., `style.v2.css` instead of just `style.css`)
+
#### Content Not Being Cached
* **Issue:** Your content isn't being cached by the CDN.
* **Possible Cause:** Missing public read permissions on objects.
* **Solution:**
- For object storage: Check bucket and object access policies
- Verify the object is accessible directly before attempting CDN access
+
:::note
Remember that only publicly accessible objects will be cached by the CDN. Private objects will always be fetched directly from the origin.
:::
+
#### Environment Variables Not Available
* **Issue:** You can't access the new CDN-related project level environment variables in your containers.
* **Possible Cause:** When new environment variables are created, existing services need to be restarted to access them. Services created before the CDN feature release require special handling.
* **Solution:**
- For services created after CDN release: Restart the service to apply the new environment variables
- For services created before CDN release: Add and then remove a dummy environment variable in the project settings adn restart the service
+
#### Unexpected 404 Errors
* **Issue:** Users receive 404 errors when accessing content via CDN.
* **Possible Cause:** Incorrect CDN URL formatting or missing content at origin.
@@ -6611,77 +9297,407 @@ Remember that only publicly accessible objects will be cached by the CDN. Privat
- Double-check your [URL structure](#) (pay attention to domain names and paths)
- Verify content exists at the origin before attempting CDN access
- Test accessing the content directly from origin first
+
**Correct URL patterns:**
- Object Storage: `https://storage.cdn.zerops.app/your-bucket/path/to/file`
- Static Mode: `https://static.cdn.zerops.app/your-domain.com/path/to/file`
+
---
+
*Need help implementing CDN in your project? Join our [Discord community](https://discord.gg/zeropsio) where our team and other Zerops users can assist you!*
----------------------------------------
-# Features > Container Vs Vm
+# Features > Coding Agents
-Ever wondered why container technologies like Docker took over the development world so quickly? Let's break down the real differences between traditional VMs and containers - and why you might want to use one over the other.
-## Key Distinctions
-**Containers** are like lightweight packages that contain just your app and what it needs to run, sharing resources with your main system.
-**Virtual Machines** are like having a whole computer inside your computer. Complete with its own operating system, memory, and everything else.
-### Why Developers Love Containers
-#### They're Fast
-- Start up in seconds (not minutes)
-- Take up way less space
-- You can run many more of them on the same hardware
-#### They're Consistent
-- Works on your machine? Will work on everyone's machine
-- No more "but it works locally" problems
-- Same environment from development to production
-#### They're Simple
-- Easy to share with your team
-- Quick to update and modify
-- Less configuration headaches
-### When VMs Still Make Sense
-Sometimes you actually want a full computer-within-a-computer:
-- You need to run a completely different operating system
-- You're dealing with legacy applications that need specific system configurations
+
+Zerops was built on the idea of **environment parity** — giving developers the full development lifecycle, from remote development to highly available production, with the observability and developer tools for maximum flexibility, and sensible defaults so the configs stay reasonable. Turns out that's **exactly what coding agents need** to produce and iterate on production-ready applications.
+
+## What is it
+
+An **[MCP server](/zcp/overview)** for your agents — with an optional remote cloud development environment container to run them in — that makes use of the flexibility and processes Zerops provides. There's no "Zerops system prompt" hogging your context window. The MCP server is a thin layer that makes **your agent a Zerops platform power user** — when needed — so it understands:
+
+- how networking, scaling, debugging, build & deployment, environment variables, and service provisioning work on the platform
+- the development loop: start a dev server → implement → deploy to stage → verify
+
+The depth of the platform underneath is what gives the agent room to actually work. A single agent can scaffold and iterate on projects with multiple runtimes (`app`, `api`, `worker`) backed by multiple [managed services](/features/infrastructure) (object storage `storage`, Postgres `db`, Elasticsearch `search`, NATS `broker`, Valkey `cache`) — just as easily as it can work on a simple Next.js presentational website.
+
+A **[recipe ecosystem](https://app.zerops.io/recipes)** covering the most popular frameworks — pre-prepared for the whole lifecycle — gives the agent a baseline to start from, or a guide for setting up any stack on Zerops.
+
+```text
+ ┌─ ZCP MCP ────┐ ┌─ recipes for any stack ────────────────────────────────┐
+ │ │ │ │
+ │ Claude Code │ │ │
+ │ Codex │ │ Bun, Deno, Node.js, Go, Java, Python, Rust, Gleam │
+ │ Gemini CLI ├───►│ │
+ │ opencode │ │ Ruby, PHP, .NET, Laravel, Next.js, Nuxt, Astro, Svelte │
+ │ │ │ │
+ └───────┬──────┘ │ React, Vue, Angular, Solid, Qwik, Analog, Nest.js │
+ │ │ │
+ │ │ │
+ │ └────────────────────────────────────────────────────────┘
+ │
+ │ zcp with agent has root ssh access to runtime services,
+ │ runs dev server on dev, deploys to stage, verifies
+ │
+ ├───────────────────────────────────────────────────────────────┐
+ │ │
+┌─ complex project ────────────────────────────────────────┐ ┌─ simple project ───┐
+│ │ │ │ │ │
+│ ▼ │ │ ▼ │
+│ ┌────────────┐ │ │ ┌──────────┐ │
+│ │ zcp │ │ │ │ zcp │ │
+│ │ Ubuntu │ │ │ │ Ubuntu │ │
+│ └────────────┘ │ │ └──────────┘ │
+│ │ │ │
+│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ ┌──────────┐ │
+│ │ appdev │ │ apidev │ │ workerdev │ │ │ │ appdev │ │
+│ │ Bun │ │ Golang │ │ Python │ │ │ │ Node.js │ │
+│ └────────────┘ └────────────┘ └────────────┘ │ │ └──────────┘ │
+│ │ │ │
+│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ ┌──────────┐ │
+│ │ appstage │ │ apistage │ │workerstage │ │ │ │ appstage │ │
+│ │ Bun │ │ Golang │ │ Python │ │ │ │ Node.js │ │
+│ └────────────┘ └────────────┘ └────────────┘ │ │ └──────────┘ │
+│ │ └────────────────────┘
+│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
+│ │ db │ │ search │ │ broker │ │ cache │ │storage │ │
+│ │Postgres│ │Elastic │ │ NATS │ │ Valkey │ │ S3 │ │
+│ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │
+└──────────────────────────────────────────────────────────┘
+
+```
+
+:::tip[Platform-first, not agent-first]
+
+Most coding-agent platforms went agent-first, then bolted on infrastructure — where it runs, how it reaches the database, how its output becomes production-ready, which third-party services to wire up. **Zerops went platform-first.** The complete development lifecycle existed before coding agents did; we taught them to operate it — **not just how to call APIs, but how to ship software the way a senior developer would.**
+
+:::
+
+## Main features
+
+### Your agent, your subscription
+
+Bring whichever agent you already use. Claude Code today; Codex, Gemini CLI, opencode, and any MCP-capable client next. The container is a regular Ubuntu — install your own CLI tools, drop in your `.claude` / `.cursor` configs, attach your IDE over SSH. **Zerops doesn't resell tokens or proxy your model calls** — sign in with your own Anthropic / OpenAI / Google subscription and the agent talks to its provider directly.
+
+### An ordinary Zerops project underneath
+
+The agent operates inside a normal Zerops project — same shape as production. Managed databases (PostgreSQL, MariaDB, ClickHouse), key-value stores (KeyDB, Valkey), search (Elasticsearch, Meilisearch, Typesense), vector store (Qdrant), message queues (NATS, Kafka), object and shared storage, managed Nginx — all on a private network, addressable by hostname. The same pipeline that deploys here can deploy to a separate HA production project with no `zcp` service attached. Not a sandbox the work outgrows.
+
+### Human ↔ agent handover
+
+The agent and the human share the same workspace — same filesystem, same SSH key, same Cloud IDE in the browser, same remote-dev attach from your local IDE. Take over mid-session, set something up before the agent runs, debug in the same container the agent just left. Nothing reaches production until you merge the PR — the agent opens it, you gate it.
+
+### Recipes for any stack
+
+Runtimes for Bun, Deno, Node.js, Go, Python, Rust, Java, .NET, PHP, Elixir, Gleam — with curated recipes for the framework on top: Next.js, Nuxt, Astro, Svelte, React, Vue, Angular, Solid, Qwik, Analog, NestJS, Laravel, and more. Pick a recipe, select the **AI Agent** environment, and the project comes up with a working dev runtime, a stage runtime, the right managed services wired in, and a coding agent briefed on the Zerops surface.
+
+## How it works in practice
+
+The agent reaches your project's private network one of two ways:
+
+- **Remote** — a `zcp` service deployed into the project runs the agent. You attach to it with Claude Code's IDE extension, with any IDE that supports remote development (Cursor, Windsurf, VS Code Remote), or by running [`zcli vpn up`](/references/networking/vpn) and ssh-ing into `zcp` to drive the rest of the project from a shell.
+- **Local** — install the `zcp` MCP on your machine and run `zcli vpn up` to join the network. From there your IDE, agent, and shell can ssh directly into any container.
+
+Either way, the agent reaches [managed services by hostname](/references/networking/internal-access) (`db:5432`, `cache:6379`), deploys through the [Zerops pipeline](/features/pipeline), and reads logs and events the same way you would.
+
+**Remote (zcp service)**
+
+```text
+ https://my-app.com
+ │
+ ▼
+┌────────────────────────────────────────────────────────────┐
+│ Zerops development project (private network) │
+│ ┌─────────────────┐ ┌──────────┐ ┌──────────┐ │
+│ │ project ctrl │ │ stats │ │ logger │ │
+│ │ + L3 balancer │ │ │ │ │ │
+│ │ + firewall │ │ │ │ │ │
+│ └────────┬────────┘ └──────────┘ └──────────┘ │
+│ │ │
+│ ┌────────┴────────┐ │
+│ │ L7 balancer │ │
+│ │ (Nginx) │ control plane │
+│ └────────┬────────┘ ssh into other services │
+│ │ dev runtime fs mounted │
+│ ├─────────────────┬─────────────────┐ │
+│ ┌──────┴──────┐ ┌───────┴───────┐ ┌──────┴──────┐ │
+│ │ appdev:3000 │ │ appstage:3000 │ │ zcp service │ │
+│ │ dev runtime │ │ stage runtime │ │ agent + MCP │ │
+│ └──────┬──────┘ └───────┬───────┘ └──────┬──────┘ │
+│ │ │ │ │
+│ └─────────────────┼─────────────────┘ │
+│ │ │
+│ ┌──────────────┴────────────┐ │
+│ │ │ │
+│ ┌──────┴──────┐ ┌──────┴──────┐ │
+│ │ db:5432 │ │ cache:6379 │ │
+│ │ Postgres │ │ Valkey │ │
+│ └─────────────┘ └─────────────┘ │
+│ │
+└────────────────────────────────────────────────────────────┘
+```
+
+**Local (zcli vpn up)**
+
+```text
+ https://my-app.com
+ │
+ ▼
+┌────────────────────────────────────────────────────────────┐
+│ Zerops development project (private network) │
+│ ┌─────────────────┐ ┌──────────┐ ┌──────────┐ │
+│ │ project ctrl │ │ stats │ │ logger │ │
+│ │ + L3 balancer │ │ │ │ │ │
+│ │ + firewall │ │ │ │ │ │
+│ └────────┬────────┘ └──────────┘ └──────────┘ │
+│ │ │
+│ ┌────────┴────────┐ │
+│ │ L7 balancer │ │
+│ │ (Nginx) │ │
+│ └────────┬────────┘ │
+│ │ │
+│ ├─────────────────┐ │
+│ ┌──────┴──────┐ ┌───────┴───────┐ │
+│ │ appdev:3000 │ │ appstage:3000 │ │
+│ │ dev runtime │ │ stage runtime │ │
+│ └──────┬──────┘ └───────┬───────┘ │
+│ │ │ │
+│ └────────┬────────┘ │
+│ │ │
+│ ┌─────┴─────────────────────┐ │
+│ │ │ │
+│ ┌──────┴──────┐ ┌──────┴──────┐ │
+│ │ db:5432 │ │ cache:6379 │ │
+│ │ Postgres │ │ Valkey │ │
+│ └─────────────┘ └─────────────┘ │
+│ │
+└──────────────────────────────▲─────────────────────────────┘
+ │
+ │ VPN tunnel
+ │
+ ┌────────────────┴────────────────┐
+ │ IDE / terminal │
+ │ + agent │
+ │ + zcp MCP │
+ │ │
+ │ $ curl zerops.io/zcp/install.sh │
+ │ $ zcp init │
+ │ $ zcli vpn up │
+ └─────────────────────────────────┘
+```
+
+The agent runs through two workflows. **Bootstrap** settles which services and runtime targets the app needs. **Develop** is the short work loop — edit code on `appdev`, deploy to `appstage`, check it's reachable, verify behavior against `db:5432` and `cache:6379`, fix from evidence. A session ends with a URL you can open, or a specific blocker — failure category, attempts, what's still needed. Same hostnames, same managed services, same pipeline as production — just at smaller scale. See [Workflows in depth](/zcp/reference/agent-workflow) for both.
+
+```text
+ zcp (local or remote)
+ │
+ ▼
+ edit code on appdev ◀────────────────────────┐
+ └ dev server, hot reload │
+ │ │
+ ▼ │
+ deploy to appstage │
+ │ │
+ ▼ │
+ check reachability │
+ │ │
+ ▼ │
+ verify behavior ─── fail ─────┐ │
+ │ │ │
+ │ pass ▼ │
+ ▼ read logs / events │
+ URL (proof) fix from evidence ─────┘
+```
+
+Once the loop produces verified work, the agent doesn't push to production. It hands off — through whichever path your team uses: a tag push, a protected-branch merge, a manual `zcli` release, a pull request, or a CI job. **A human gates the release**, and the production deploy runs into a [separate production project](/zcp/security/production-policy) that has no `zcp` service at all.
+
+```text
+ Dev project GitHub Prod project
+
+┌─────────────────────┐ ┌──────────────┐ ┌─────────────────────┐
+│ appdev │ │ │ │ app (HA) │
+│ appstage │ │ Pull │ │ │
+│ │ push │ Request │ CI/CD │ db (HA) │
+│ db, cache │ ────▶ │ │ ────▶ │ │
+│ │ │ + human │ │ cache (HA) │
+│ zcp service │ │ review │ │ │
+│ │ │ │ │ (no zcp service) │
+└─────────────────────┘ └──────────────┘ └─────────────────────┘
+```
+
+## Where does this fit in the agent landscape
+
+With the model clear, here's where ZCP sits among adjacent tools. People say "agent infrastructure," "infra for Claude agents," "agent hosting," or "agent sandboxes" to mean different things — usually one of the categories below.
+
+#### PaaS MCPs
+
+_AWS MCP servers · Railway MCP · Fly.io MCP · Render MCP_
+
+Most major PaaS providers have shipped an MCP — provision services, deploy code, list resources, read operational state. Great for "let my agent ship to my Railway account." These are *deploy and operate* surfaces, driven from outside the platform — and they reflect what's underneath: platforms optimized for day-one deploy that tuck the infrastructure behind a wall. Once an agent needs to actually *develop* against that infrastructure — debug a failed health check, follow real logs, hit Postgres from inside the network, inspect what a build is doing, run the dev loop before it ships anything — the wall stops it. That's by design on those platforms, not a missing feature.
+
+#### Cloud VPS MCPs
+
+_Hetzner Cloud MCP · DigitalOcean MCP · Linode MCP · raw SSH/server MCPs_
+
+"Let your agent manage your Hetzner VPS." An MCP gives the agent access to a Linux box — provision it, SSH in, install Docker and Postgres and nginx, set up systemd units, point a domain at it. Maximum control, lowest cost, full Linux to play with. The same reason senior developers reach for managed platforms applies here: even if you *can* harden SSH, write nginx configs, tune `pg_hba.conf`, rotate TLS, set firewall rules, run fail2ban, and stay on top of CVEs across kernel, OpenSSL, Docker, Postgres, and nginx — you usually don't want to. Each layer is its own domain with its own gotchas, each is a security surface that drifts the moment you stop tending it, and every project becomes a snowflake. Hand that work to an agent and you also hand it the blast radius: misconfigured firewall, debug endpoint left open, port 5432 exposed to the internet, keys never rotated. ZCP is the inverse trade-off — the **guardrails** of a managed platform. Private networking, TLS, isolated services, safe defaults, managed backups, no exposed ports unless you opt in — all built in. The agent operates through [project-scoped MCP tools](/zcp/reference/mcp-operations) instead of `sudo` on a fresh Ubuntu box, so the mistakes that matter on a VPS aren't reachable from where it sits.
+
+#### Cloud dev environments with AI
+
+_GitHub Codespaces + Copilot Workspace · Gitpod · Coder_
+
+A managed Linux container in the cloud with your editor and an AI assistant attached. Solves "where the agent runs" so state survives between sessions and machine setup stops being a question. The `zcp` service is the closest thing in this category — managed Linux container, Cloud IDE, your agent of choice — except it lives *inside* a Zerops project, addressing the project's runtimes, database, and cache by hostname, with deploys and logs as primitives the agent can call.
+
+#### Bundled agent platforms
+
+_Replit Agent · Lovable · Bolt.new · v0 · Devin · OpenHands_
+
+The agent, the workspace, the stack, and (often) the hosting target are fused into one closed product. Fast for prototypes. Decisions are made for you. Switching agents usually means switching platforms, and production-grade primitives — a real dev/stage/prod release flow, private networking, observability — tend to be limited or absent. **ZCP doesn't bundle**: the agent and model stay yours on your own subscription, and the platform underneath is normal Zerops with the full stack of managed services, networking, deploys, and observability.
+
+#### Local coding agents
+
+_Cursor · Windsurf · Zed · Claude Code · Codex CLI · Aider · Cline_
+
+The agent runs on your machine, edits your local checkout, runs local commands. Excellent at code changes. Anything beyond your machine — databases, networking, deploy targets, runtime logs — is yours to wire in. Install the ZCP MCP locally and run `zcli vpn up`, and any of these agents can now reach a real Zerops project alongside your local code: services addressed by hostname, deploys, logs, events.
+
+#### Code-execution sandboxes
+
+_E2B · Modal · Daytona · CodeSandbox SDK_
+
+Ephemeral Linux environments that AI *applications* spin up — often per request — to execute generated code safely. The right primitive when you're building a product that needs a model to run untrusted code and hand back the output. They're a building block for AI applications, not somewhere a coding agent settles in to iterate on your project. Different shape from ZCP; they show up here because the names cluster nearby.
+
+#### Agent SDKs and frameworks
+
+_Cloudflare Agents · Vercel AI SDK · Mastra · Anthropic Agent SDK_
+
+Libraries for building and shipping agents to *your* users — tool calling, memory, orchestration, model providers, sometimes hosting. They're how somebody would build a product like ZCP, not where a coding agent runs against a project. Same disambiguation — adjacent on the shelf, different shape.
+
+## Where to start
+
+- [Quickstart](/zcp/quickstart) — AI Agent recipe, Claude Code, and a real product change in about five minutes.
+- [ZCP MCP overview](/zcp/overview) — What the `zcp` MCP gives the agent, where it runs, and how a run ends in proof or a blocker.
+- [Remote or local setup](/zcp/setup/choose-workspace) — Choose where the `zcp` MCP runs — inside Zerops with bundled tools, or beside your local editor.
+- [Build and ship](/zcp/workflows/build-with-zcp) — Runtime layout, development, delivery, packaging, and production release.
+
+
+----------------------------------------
+
+# Features > Container Vs Vm
+
+
+Ever wondered why container technologies like Docker took over the development world so quickly? Let's break down the real differences between traditional VMs and containers - and why you might want to use one over the other.
+
+## Key Distinctions
+
+**Containers** are like lightweight packages that contain just your app and what it needs to run, sharing resources with your main system.
+
+**Virtual Machines** are like having a whole computer inside your computer. Complete with its own operating system, memory, and everything else.
+
+### Why Developers Love Containers
+
+#### They're Fast
+- Start up in seconds (not minutes)
+- Take up way less space
+- You can run many more of them on the same hardware
+
+#### They're Consistent
+- Works on your machine? Will work on everyone's machine
+- No more "but it works locally" problems
+- Same environment from development to production
+
+#### They're Simple
+- Easy to share with your team
+- Quick to update and modify
+- Less configuration headaches
+
+### When VMs Still Make Sense
+
+Sometimes you actually want a full computer-within-a-computer:
+
+- You need to run a completely different operating system
+- You're dealing with legacy applications that need specific system configurations
- You require maximum isolation for security reasons
+
### Real-World Comparison
+
Think of it like this:
- **Containers** are like apartments in a well-managed building (shared infrastructure, efficient, but with some limitations)
- **VMs** are like having your own house (complete control, but with more overhead)
+
## Containers and VMs in Zerops
+
### Why Zerops Uses Both
+
At Zerops, we use **containers** as our primary runtime environment - they're fast, efficient, and perfect for most modern development workflows. We've optimized our container infrastructure to handle nearly every type of application you might need to run.
+
However, we also provide **VMs** when you need them, particularly for Docker-based workloads where the additional isolation is essential. Docker containers are a special case - in Zerops, they actually need to run inside VMs for proper security and isolation. While it's technically possible to run Docker in containers using privileged mode, this creates security vulnerabilities.
+
### When to Use What
-
+
+
+
+
Go with Containers when:
-
- Building modern web applications
-
- Working with microservices
-
- Need quick deployment and vertical scaling
-
- Want efficient resource usage
-
+
+
+
+
+ Building modern web applications
+
+
+
+ Working with microservices
+
+
+
+ Need quick deployment and vertical scaling
+
+
+
+ Want efficient resource usage
+
+
+
+
+
Consider VMs when:
-
- Running legacy applications
-
- Need complete OS isolation
-
- Require specific hardware access
-
- Need to run Docker containers
-
+
+
+
+
+ Running legacy applications
+
+
+
+ Need complete OS isolation
+
+
+
+ Require specific hardware access
+
+
+
+ Need to run Docker containers
+
+
+
+
+
### Resource Allocation
+
Both containers and VMs in Zerops can have guaranteed resources:
- Specific CPU cores
- Dedicated memory
- Controlled disk space
+
The difference isn't in resource guarantee capabilities, but rather in how these resources are managed and isolated.
+
## The Bottom Line
+
For most modern development work, containers are the way to go. They're faster, more efficient, and easier to work with. VMs still have their place, but unless you have a specific reason to use them, containers will usually make your life easier.
+
*Remember: The goal is to spend less time managing infrastructure and more time building great applications. Choose the tool that lets you do that most effectively.*
+
:::tip Pro Tip
Not sure which to choose? Start with containers. You can always switch to VMs if you discover you need them for specific use cases.
:::
@@ -6690,127 +9706,198 @@ Not sure which to choose? Start with containers. You can always switch to VMs if
# Features > Debug Mode
+
This document describes the debug mode configuration capabilities for service stacks in Zerops, allowing developers to pause execution at specific points during build and runtime processes for debugging purposes.
+
## Overview
+
Debug mode introduces control over two distinct phases of deployment:
+
- **Build phase** - When the `buildCommands` are executed
- **Runtime prepare phase** - When the `prepareCommands` are executed
+
For each phase, you can choose when to pause the execution:
- **Disable** - No pausing, execution proceeds normally
- **Before first command** - Execution stops before running any commands
- **After last command** - Execution stops after all commands complete
- **On command fail** - Execution stops when a command fails
+
Each phase can be configured with its own debug settings without affecting the other phase.
+
:::warning Important
The entire build process, including any time spent in debug mode, has a maximum duration of 60 minutes. After this time limit is reached, the build process is automatically cancelled.
:::
+
## Configuration
+
The debug mode configuration can be found in your service detail under the **Pipelines & CI/CD settings**.
-
+
## Debug Control
+
When execution is paused in debug mode, you have several commands available to control the debugging process. Each command serves a specific purpose and affects the deployment process differently.
+
### Debug Pause Points
+
There are three key points where execution can pause during deployment:
- ➠ **Disable** - Do not pause
- ↪ **Before First Command** - Paused before any commands run
- ✖ **On Command Failure** - Paused when a command fails
- ✔ **After Last Command** - Paused after all commands complete
+
### Available Commands
+
#### Continuing Execution
To proceed with the normal deployment process, use:
```bash
zsc debug continue
```
-
- Pause Point
- Behavior
-
- ↪ Before First Command
- Begins running commands for the current phase until next possible pause point
-
- ✖ On Command Failure
- Skips the failed command and continues deployment
-
- ✔ After Last Command
- Moves to the next phase (from build to runtime prepare) or completes deployment
-
+
+
+
+
+
Pause Point
+
Behavior
+
+
+
+
+
↪ Before First Command
+
Begins running commands for the current phase until next possible pause point
+
+
+
✖ On Command Failure
+
Skips the failed command and continues deployment
+
+
+
✔ After Last Command
+
Moves to the next phase (from build to runtime prepare) or completes deployment
+
+
+
+
#### Marking Success
To force a successful deployment status, use:
```bash
zsc debug success
```
-
- Pause Point
- Behavior
-
- ↪ Before First Command
- Ends current phase without running any commands
-
- ✖ On Command Failure
- Ignores the failure and ends current phase with success
-
- ✔ After Last Command
- Concludes current phase with a successful status
-
+
+
+
+
+
Pause Point
+
Behavior
+
+
+
+
+
↪ Before First Command
+
Ends current phase without running any commands
+
+
+
✖ On Command Failure
+
Ignores the failure and ends current phase with success
+
+
+
✔ After Last Command
+
Concludes current phase with a successful status
+
+
+
+
:::note
Requires valid `deployFiles` to work properly (fails otherwise).
:::
+
#### Forcing Failure
To terminate the deployment with a failure status, use:
```bash
zsc debug fail
```
-
- Pause Point
- Behavior
-
- ↪ Before First Command
- Marks current phase as failed without running commands
-
- ✖ On Command Failure
- Ends deployment with original error
-
- ✔ After Last Command
- Overwrites successful execution with failed status and ends deployment
-
+
+
+
+
+
Pause Point
+
Behavior
+
+
+
+
+
↪ Before First Command
+
Marks current phase as failed without running commands
+
+
+
✖ On Command Failure
+
Ends deployment with original error
+
+
+
✔ After Last Command
+
Overwrites successful execution with failed status and ends deployment
+
+
+
+
Each phase can be configured independently to pause at any of the points described above, giving you precise control over your debugging workflow. The 60-minute timeout ensures deployments don't remain blocked indefinitely.
+
## Usage Examples
+
### Example 1: Debugging Build Failures
-
- Build phase
- ✖ On Command Failure
-
- Prepare runtime phase
- ➠ Disable
-
+
+
+
+
+
Build phase
+
✖ On Command Failure
+
+
+
Prepare runtime phase
+
➠ Disable
+
+
+
+
This configuration allows you to:
1. Inspect the container state after a failure
2. Make necessary adjustments
3. Use `zsc debug continue` to resume or `zsc debug fail` to abort
+
### Example 2: Validating Runtime Setup
-
- Build phase
- ➠ Disable
-
- Prepare runtime phase
- ✔ After Last Command
-
+
+
+
+
+
Build phase
+
➠ Disable
+
+
+
Prepare runtime phase
+
✔ After Last Command
+
+
+
+
## Best Practices
+
#### Targeted Debugging
- Enable debug mode only for the specific phase you need to investigate
- This minimizes disruption to the deployment process
- Helps maintain clear debugging sessions
+
#### Clean Up
- Always remember to disable debug mode after completing your debugging session
- Set both phases to **Disable**
- Prevents unexpected pauses in future deployments
+
#### Production Consideration
- Be cautious when using debug mode in production environments
- Paused executions can block deployments
- Consider using separate development services for extended debugging sessions
+
#### Timeout Awareness
- Be mindful of the 60-minute maximum debug pause time (plan debugging sessions accordingly)
+
## Technical Considerations
+
- Debug mode settings persist until explicitly changed
- Build phase and runtime prepare phase operate independently
- Debug commands are only available when execution is paused
@@ -6820,14 +9907,23 @@ This configuration allows you to:
# Features > Env Variables
+
Zerops manages environment variables at two scopes: service level and project level. These variables are handled automatically without requiring `.env` files.
+
**On this page:** [Service Variables](#service-variables) · [Project Variables](#project-variables) · [Referencing Variables](#referencing-variables) · [Variable Isolation](#environment-variable-isolation) · [Restrictions](#variable-restrictions) · [Examples](#environment-variable-examples)
+
## Service Variables
+
Variables that are specific to individual [services](/features/infrastructure#services).
+
### User-Defined Variables
+
You can define service-level variables in two ways:
+
#### 1. Build & Runtime Variables
+
These variables are defined with `envVariables` attribute in the [build](/zerops-yaml/specification#envvariables-) or [run](/zerops-yaml/specification#envvariables--1) section of your `zerops.yaml` file and are accessible within their respective containers.
+
```yaml title="zerops.yaml"
...
build:
@@ -6844,21 +9940,30 @@ These variables are defined with `envVariables` attribute in the [build](/zerops
DB_USER: db
DB_PASS: password
```
+
See how to [reference variables](#referencing-variables) between services and between build and runtime environments. All variables must follow the [naming restrictions](#variable-restrictions).
+
:::note
Your application must be redeployed when updating environmental variables in `zerops.yaml`.
:::
+
#### 2. Secret Variables
+
For storing sensitive data you don't want in your source repository. They can be updated without redeployment (though services need to be reloaded).
+
Secret variables can be managed through:
+
##### GUI Interface
+
Navigate to service details and find **Environment variables** in the menu. You can:
- Add individual variables using the "Add secret variable" button
- Edit individual variables through the menu that appears on hover
- Use the bulk editor for managing multiple variables in .env format
-
+
##### Import Configuration
+
Create secret variables for a service with `envSecrets` attribute. See the complete [import.yaml structure](/references/import).
+
```yaml title="import.yaml"
services:
...
@@ -6866,25 +9971,40 @@ services:
S3_ACCESS_KEY_ID: 'your-secret-s3-key'
S3_ACCESS_SECRET: 'your-s3-access-secret'
```
+
### System-Generated Variables
+
Zerops automatically generates variables based on service type.
+
These variables cannot be deleted and are always listed at the bottom of the environment variables page. Some are read-only (like `hostname`), while others can be edited (like `PATH`).
+
These variables can also be [referenced](#referencing-variables).
+
## Project Variables
+
Variables that apply across all services within a [project](/features/infrastructure#projects). These provide a way to share common configuration across services.
+
They work similarly to service secret variables but at project scope - they're managed through the GUI and can be updated without redeployment (though services need to be reloaded).
+
:::important
Project variables are **automatically inherited** by all services in the project — both in build and runtime environments. You do not need to [reference](#referencing-variables) them in your `zerops.yaml`.
:::
+
### User-Defined Variables
+
You can set project-wide variables through:
+
#### GUI Interface
+
Access **Project environment variables** in your project detail to:
- Add individual variables one by one
- Edit individual variables
- Use the bulk editor with .env format
+
#### Import Configuration
+
Create project variables with `envVariables` attribute. See the complete [import.yaml structure](/references/import).
+
```yaml title="import.yaml"
project:
...
@@ -6892,55 +10012,89 @@ project:
LOG_LEVEL: info
API_VERSION: v1
```
+
These variables will be automatically available in all services without any additional configuration.
+
### System-Generated Variables
+
Zerops automatically generates project-level variables that are also automatically available in all services.
+
### Overriding Project Variables
+
If you need a different value for a specific service, you can override a project variable by defining a service-level variable with the same key. See [Variable Precedence](#variable-precedence) for details on how conflicts are resolved.
+
```yaml title="zerops.yaml"
run:
envVariables:
LOG_LEVEL: debug # Overrides the project-level LOG_LEVEL for this service only
```
+
## Environment Variable Isolation
+
A security feature that controls the **visibility** of environment variables across services within a project. This affects how [referencing variables](#referencing-variables) across services works.
+
By default, Zerops isolates environment variables between services to enhance security and prevent unintended access to sensitive information. This isolation can be configured at both project and service levels.
+
### Isolation Modes
+
Zerops supports two isolation modes:
-
- Mode
- Description
-
- service
- Default mode. Variables are isolated to their respective services. Services can only access their own variables and must explicitly reference variables from other services.
-
- none
- Legacy mode. All variables from all services are automatically shared and accessible via prefixing.
-
+
+
+
+
+
Mode
+
Description
+
+
+
+
+
service
+
Default mode. Variables are isolated to their respective services. Services can only access their own variables and must explicitly reference variables from other services.
+
+
+
none
+
Legacy mode. All variables from all services are automatically shared and accessible via prefixing.
+
+
+
+
### Configuring Isolation
+
#### Project-Level Isolation
+
Zerops automatically creates the `envIsolation` project variable with the default value `service`. You only need to modify this if you want to disable isolation:
+
```yaml title="import.yaml"
project:
envIsolation: none # Disables isolation, sharing all variables
```
+
This can also be set through the Project Environment Variables section in the GUI.
+
#### Service-Level Override
+
Individual services can override the project-level isolation setting:
+
```yaml title="import.yaml"
services:
- hostname: db
envIsolation: none # This service's variables will be visible to all services
```
+
:::tip
You might set a database service to `envIsolation: none` to expose its connection details to other services, without having to manually reference them, while keeping the rest of your services isolated.
:::
+
:::note
In import YAML, `envIsolation` can also be nested under `envVariables`/`envSecrets`. (If both are present, the nested version takes precedence).
:::
+
### Accessing Variables Across Services
+
#### With Isolation Enabled (`service` mode)
+
When isolation is enabled, you must explicitly create reference variables to access variables from other services:
+
```yaml title="zerops.yaml"
# In the 'app' service:
run:
@@ -6948,48 +10102,70 @@ run:
# Create a local reference to the 'password' variable from the 'db' service
DB_PASSWORD: ${db_password}
```
+
This approach gives you complete control over which variables are shared between services.
+
#### With Isolation Disabled (`none` mode)
+
When isolation is disabled, variables are automatically available across all services with the service name prefix:
+
```yaml
# In any service, you can directly access:
${db_password} # Accesses the 'password' variable from the 'db' service
```
+
### Best Practices for Variable Isolation
+
1. **Use Default Isolation**: Keep the default `service` isolation for enhanced security.
2. **Explicit References**: Create explicit references only for variables that need to be shared.
3. **Naming Conventions**: Use clear naming patterns for reference variables (e.g. `DB_PASSWORD` for a reference to `db_password`).
4. **Service-Level Exceptions**: Use service-level isolation overrides sparingly and only for services that need to expose their variables widely.
+
## Referencing Variables
+
You can reference other variables using the `${variable_name}` syntax. This is used to reference **service-level variables**, not project variables (which are already automatically inherited).
+
### Within Same Service
+
```yaml
envVariables:
id: 42069
hostname: app
name: ${id}-${hostname} # Results in: 42069-app
```
+
### Across Services
+
How this works depends on your [environment variable isolation](#environment-variable-isolation) setting:
+
**With Isolation Enabled** (`service` mode - default)
+
Create an explicit reference in the destination service:
+
```yaml
# In the 'app' service
envVariables:
# Creating a reference to the 'connectionString' from 'dbtest' service
dbConnection: ${dbtest_connectionString}
```
+
**With Isolation Disabled** (`none` mode)
+
Variables from other services are automatically injected into the container and available using the service prefix format `servicename_variablename`:
+
```yaml
# In any container, you can directly access variables from other services:
# ${dbtest_connectionString}
```
+
### Between Build and Runtime Environments
+
Build and runtime are two distinct environments in Zerops. Each environment can have its own set of variables, and you can use the same variable names in both environments since they are separate. Due to this separation, variables defined in one are not automatically accessible in the other.
+
To share variables between environments, you need to use specific prefixes:
- Use `RUNTIME_` prefix to access runtime variables during build
- Use `BUILD_` prefix to access build variables during runtime
+
```yaml title="zerops.yaml"
build:
envVariables:
@@ -6998,35 +10174,52 @@ run:
envVariables:
API_KEY: "12345-abcde" # Referenced in build with RUNTIME_ prefix
```
+
### Project Variables — No Reference Needed
+
[Project variables](#project-variables) are **automatically available** in all services. Do not use the `${...}` syntax to reference them:
+
```yaml
# ❌ Wrong - this shadows the project variable
envVariables:
PROJECT_NAME: ${PROJECT_NAME}
+
# ✅ Correct - just use the project variable directly in your app
# It's already available without any configuration
```
+
If a project variable is named `LOG_LEVEL`, your application can read it directly — you don't need to add anything to your `zerops.yaml`.
+
## Variable Restrictions
+
All environment variables must follow these restrictions:
+
### Key
- Alphanumeric characters only (use `_` to separate words)
- Must be unique within their scope
- Case-sensitive
+
### Value
- ASCII characters only
- No EOL characters
+
## Variable Management
+
### Variable Precedence
+
When the same environment variable key exists in multiple places, Zerops follows these precedence rules:
+
1. Service-level variables take precedence over project variables
2. Within service-level:
- Build/runtime variables override secret variables
- Build and runtime containers are separate environments
+
## Environment Variable Examples
+
### Variable Isolation Example
+
Consider a project with three services: `api`, `db`, and `cache`:
+
```yaml title="Project structure"
project:
name: my-project
@@ -7046,114 +10239,313 @@ services:
password: cacheServerPass
port: 6379
```
+
With this setup:
- The `api` service can only access the specific `db` and `cache` variables it explicitly references
- The `db` service cannot see any variables from `api` or `cache`
- The `cache` service cannot see any variables from `api` or `db`
+
If we changed the project's `envIsolation` to `none`, all services would be able to see all variables from all other services (prefixed with the service name).
+
*Need help? Join our [Discord community](https://discord.gg/zeropsio).*
----------------------------------------
# Features > Infrastructure
+
Zerops organizes your infrastructure into three hierarchical levels: **projects**, **services**, and **containers**. This structure provides secure networking, resource isolation, and scalable application deployment.
+
## Projects
+
A project is the top-level entity in Zerops, functioning as a private network where services can communicate internally and share environment variables. Each project provides essential infrastructure including load balancing, routing, and container orchestration.
+
### Key Project Features
+
- **Private Networking**: All services within a project share a secure network
- **Environment Variables**: Services can access shared environment variables
- **IPv6/IPv4 Addressing**: Each project receives an IPv6 address, with optional IPv4 addressing
- **Integrated Security**: Built-in firewall and SSL certificate management
+
:::tip Project Organization
Consider your project strategy carefully. Create separate projects for different environments (dev/staging/prod) or consolidate related applications in a single project to optimize resources and simplify networking.
:::
+
### Project Core Options
+
When you create a project, it requires a functioning **core** that includes logger and statistics services, HTTP routing with automatic SSL certificate management, and IP routing with integrated firewall.
+
Zerops offers two core types to match different needs and budgets:
+
#### Lightweight Core
+
Single-container solution perfect for development projects and smaller production workloads. Includes project controller, L3 balancer, firewall, logger, statistics, and HTTP handling in one efficient package.
+
:::tip Ideal For
Development environments, low-traffic applications, personal projects, budget-conscious teams.
:::
+
#### Serious Core
+
Enterprise-grade infrastructure with separated core services across multiple containers for true redundancy and high availability.
+
:::tip Ideal For
Production applications, high-traffic websites, mission-critical business applications, teams requiring maximum uptime.
:::
+
#### Features Comparison
-
- Lightweight Core
- Serious Core
-
- Infrastructure
- Single container (limited redundancy)
- Multi-container (highly available)
-
- SSL Termination
-
- Automatic Certificate Generation
-
- Proxy / Load Balancer
-
- IPv6 Address
-
- Build Time
- 15 hours
- 150 hours
-
- Backup Space
- 5 GB
- 25 GB
-
- Egress
- 100 GB
- 3 TB
-
- Failover Protection
- Limited
- Comprehensive
-
+
+
+
+
+
+
Lightweight Core
+
Serious Core
+
+
+
+
+
Infrastructure
+
Single container (limited redundancy)
+
Multi-container (highly available)
+
+
+
SSL Termination
+
+
+
+
+
Automatic Certificate Generation
+
+
+
+
+
Proxy / Load Balancer
+
+
+
+
+
IPv6 Address
+
+
+
+
+
Build Time
+
15 hours
+
150 hours
+
+
+
Backup Space
+
5 GB
+
25 GB
+
+
+
Egress
+
100 GB
+
3 TB
+
+
+
Failover Protection
+
Limited
+
Comprehensive
+
+
+
+
For detailed pricing information on both core types, visit our [pricing page](/company/pricing#project-core-plans).
+
#### Project Core Upgrade
+
You can upgrade from Lightweight Core to Serious Core for enhanced reliability and increased resources.
+
:::warning Important
The core upgrade is a **partially destructive process** that will temporarily disrupt your project's operations. Plan upgrades during maintenance windows.
:::
+
**What happens during upgrade:**
- All project logs and statistics will be lost (forwarded logs/statistics are not affected)
- Services will be network-unavailable during the process (avg. 35 seconds but can take longer)
- $10 project core fee will be charged upon upgrade
- Free project resources will reset to Serious Core limits
- Project IP addresses remain unchanged
+
:::important
If you encounter issues, **contact support immediately** and try running the process again.
:::
+
## Services
+
Services encapsulate your containers and provide specific functionality within a project. A project can contain unlimited services, each with its own purpose.
+
**Service types include:**
- Runtimes, Linux Containers & Docker
- Databases, Search Engines & Messages Brokers
- Storages
- *System services (needed for fully functioning project core)*
+
**Management options:**
- **Fully managed**: Zerops handles scaling, routing, and repairs automatically (Databases and Storages)
- **Partially managed**: You maintain control over certain management aspects (Runtimes)
+
Services within a project communicate via internal hostnames and can share environment variables for seamless integration.
+
## Containers
+
Containers are the most granular level of the Zerops architecture. Each service consists of one or more containers that work together to deliver functionality.
+
**Container deployment:**
- Single containers for simple applications
- Multiple containers for High Availability (HA) mode (e.g. fully managed MariaDB service in HA mode uses 3 containers for the database cluster and 2 for proxies)
+
**Container capabilities:**
- Use predefined images or custom configurations
- Can be exposed publicly via Zerops subdomains, custom domains, or public ports
- Operate within service resource constraints with automatic scaling
+----------------------------------------
+
+# Features > Local Remote Development
+
+
+Zerops development is network-first. Keep your editor on your laptop, work fully inside Zerops, or use a native editor over SSH — in each case you join the same project-private network with the same hostnames, credentials, managed services, and deploy pipeline that staging and production use. What changes between environments is policy: credentials, resources, access rules, data, and release authority — not the platform underneath.
+
+## How development on Zerops works
+
+Every project ships with a private network. Services reach each other by hostname (`db:5432`, `api:3000`, `redis:6379`), with credentials injected as environment variables.
+
+The development question is how you get onto that network. Three paths give you the same project-private reach, with different filesystem, tooling, and credential boundaries.
+
+- **Local + VPN.** Your laptop joins the private network via WireGuard. Editor, toolchain, and processes stay where they are. A hosted workspace is not required.
+- **Cloud IDE.** A Linux workspace in the project, accessed through VS Code Server in the dashboard. Zero local setup.
+- **Native IDE over SSH.** SSH from your local VS Code, JetBrains Gateway, Cursor, or plain `ssh` into a workspace or directly into a runtime service container.
+
+Switch paths without reprovisioning the project. A teammate on Local + VPN and another in the Cloud IDE are hitting the same `db:5432`.
+
+```text
+ Laptop + editor Browser tab Laptop + native IDE
+ │ │ │
+ zcli vpn up VS Code Server zcli vpn up
+ (WireGuard) on the project + ssh apidev
+ │ │ │
+ └──────────────────────┴────────────────────────┘
+ │
+ ▼
+ ┌─────────── project private network ───────────┐
+ │ │
+ │ api:3000 db:5432 cache:6379 │
+ │ │
+ └───────────────────────────────────────────────┘
+```
+
+## Local + VPN
+
+**Best for:** keeping your existing editor, dotfiles, and toolchain — and offloading just the dependencies that are painful to run locally.
+
+```bash
+zcli vpn up
+
+psql "postgresql://app:secret@db:5432/myapp"
+redis-cli -h cache -p 6379
+ssh apidev
+```
+
+Your laptop can reach project services by hostname: Postgres, Valkey, S3-compatible storage, runtime containers, and any other service in the project. You can keep your normal dev loop and point it at `db:5432` instead of a local mock or Docker Compose dependency.
+
+You do not need a hosted workspace, `zcli push`, or a new editor for this path.
+
+**Source control.** Use git on your laptop the way you always have. Commits, pushes, SSH agent against GitHub, your existing credentials — nothing about Zerops sits between you and the remote.
+
+:::info Complete VPN setup
+See the [VPN reference guide](/references/networking/vpn).
+:::
+
+## Cloud IDE in Zerops
+
+**Best for:** zero local setup, working from a machine that isn't yours, or wanting a pristine environment that doesn't touch your laptop.
+
+A hosted workspace is a normal Zerops service in the project. It gives you a project-contained Linux environment with private-network access, optional Browser VS Code, `zcli`, git tooling, database CLIs, and shell utilities.
+
+The workspace can also mount runtime service files, so you can inspect or edit code that runs in another container without moving it to your laptop:
+
+```bash
+ls /var/www/apidev
+ls /var/www/frontenddev
+vim /var/www/apidev/src/server.ts
+```
+
+The dev server in the runtime container hot-reloads, the database is the same `db:5432`, and staging deploys still go through the Zerops deploy pipeline.
+
+The Cloud IDE itself is configurable. Two access methods:
+
+- **VPN Only.** The IDE is reachable through `zcli vpn up`, no public exposure. Most secure.
+- **Public Access.** The IDE is reachable on a `.zerops.app` subdomain, gated by an auto-generated password.
+
+**Source control.** The hosted workspace isn't on your laptop, so your local SSH keys don't follow it. Two patterns work:
+
+- **GitHub via `gh`.** The GitHub CLI is preinstalled. Run `gh auth login` once and `gh` handles HTTPS auth, PR creation, and review flows from the container.
+- **Token in env vars.** Save a fine-grained personal access token to the workspace service's secret environment variables; `git` reads it through a credential helper.
+
+Either pattern keeps your token in the workspace service, not in your project's source.
+
+## Native IDE over SSH
+
+**Best for:** native editor UX without carrying the toolchain or databases on your laptop.
+
+Once `zcli vpn up` is connected, every container on the project's private network is reachable from your laptop over SSH. Any editor that speaks Remote SSH can use it: VS Code Remote SSH, JetBrains Gateway, Cursor, Zed, or plain `vim`.
+
+```bash
+ssh apidev # any runtime service in the project
+ssh frontenddev
+```
+
+In this path, a hosted workspace is convenient but not required. You can connect straight to `apidev`, edit the source there, and run the dev server in the same container. A hosted workspace is only a convenience layer when you want shared tools, runtime file mounts, or Cloud IDE.
+
+**Source control.** SSH agent forwarding works the same way it does to any other machine. Add your local SSH key to your agent (`ssh-add`), and `git push` from inside `apidev` or the workspace service uses your laptop's GitHub key over the forwarded agent socket — no token storage required.
+
+```ssh-config
+# Local ~/.ssh/config
+Host apidev.zerops
+ HostName apidev
+ ForwardAgent yes
+```
+
+:::info SSH access details
+See the [SSH reference guide](/references/networking/ssh).
+:::
+
+## Picking a path
+
+| | Local + VPN | Cloud IDE | Native IDE over SSH |
+| --------------------- | ------------------ | -------------------------- | --------------------------------- |
+| Editor runs | Local | Browser | Local |
+| Toolchain | Local | Hosted workspace | Hosted workspace or service container |
+| Network entry | WireGuard VPN | Browser into the project | WireGuard VPN, then SSH |
+| Hosted workspace required | No | Yes | No (convenience) |
+| Git auth | Local credentials | `gh` or token in env | SSH agent forwarding |
+| Best for | Keeping your setup | Disposable environments | Native UX, lighter laptop |
+| Best for | Keeping your setup | Disposable environments | Native UX, lighter laptop |
+
+## Why this is not just a cloud IDE
+
+If you've used GitHub Codespaces or Gitpod, Cloud IDE looks similar: a Linux container in the cloud, accessed from a browser or local IDE. Two structural differences matter.
+
+**You don't have to be in the editor.** Codespaces and Gitpod are editor-first. Zerops is network-first. Cloud IDE is one way to reach the project's private network; `zcli vpn up` lets you skip the editor environment entirely and consume the project's managed services from your existing local setup. The hosted workspace itself is just another Zerops service — SSH in, install packages, run processes, configure it however you want.
+
+**Your dev environment runs the same platform as production.** On a CDE, your dev container is one platform and the deployment target is another — making "works on my machine" a fact of life. On Zerops, dev Postgres, queue, cache, or object storage is the same managed service type the app meets later in stage and prod, on the same private network, with the same `zerops.yaml`. Policy differs across environments; the platform underneath doesn't.
+
+## Where to start
+
+- [VPN reference](/references/networking/vpn) — Connect your laptop to a Zerops project-private network.
+- [SSH reference](/references/networking/ssh) — Use a native editor or shell over SSH.
+- [Build & deploy pipeline](/features/pipeline) — Build and deploy from the same project model.
+- [Infrastructure for Coding Agents](/features/coding-agents) — The sibling feature: agents working on Zerops projects through the same access model.
+
+
----------------------------------------
# Features > Pipeline
+
export const languages = [
{ name: "Node.js", link: "/nodejs/how-to/build-pipeline" },
{ name: "PHP", link: "/php/how-to/build-pipeline" },
@@ -7168,6 +10560,7 @@ export const languages = [
{ name: "Gleam", link: "/gleam/how-to/build-pipeline" },
{ name: "Nginx", link: "/nginx/how-to/build-pipeline" }
]
+
export const customizeBuild = [
{ name: "Node.js", link: "/nodejs/how-to/build-process#build-environment" },
{ name: "PHP", link: "/php/how-to/build-process#build-environment" },
@@ -7182,6 +10575,7 @@ export const customizeBuild = [
{ name: "Gleam", link: "/gleam/how-to/build-process#build-environment" },
{ name: "Nginx", link: "/nginx/how-to/build-process#build-environment" }
]
+
export const customizeRuntime = [
{ name: "Node.js", link: "/nodejs/how-to/customize-runtime" },
{ name: "PHP", link: "/php/how-to/customize-runtime" },
@@ -7196,9 +10590,13 @@ export const customizeRuntime = [
{ name: "Gleam", link: "/gleam/how-to/customize-runtime" },
{ name: "Nginx", link: "/nginx/how-to/customize-runtime" }
]
+
## Configure the pipeline
+
Zerops provides a customizable build and runtime environment for your application. Start by adding a [zerops.yaml](/zerops-yaml/specification) file to the **root of your repository** and modify it to fit your application.
+
Here is a basic example for a Node.js application:
+
```yaml
zerops:
- setup: api
@@ -7213,104 +10611,158 @@ zerops:
base: nodejs@20
start: npm start
```
+
The zerops.yaml in your repository tells Zerops how to build and deploy your application. When the build & deploy pipeline triggers for the Node.js service named `api`, Zerops will:
+
1. Create a build environment with Node.js v.20 preinstalled
2. Run build commands: `npm i`, `npm run build`
3. Create a runtime environment with Node.js v.20 preinstalled
4. Deploy the built artifact from the `./dist` folder to runtime containers
5. Cache the `./node_modules` folder for faster subsequent builds
6. Start your application using `npm start`
+
Learn more about `zerops.yaml` parameters for your runtime:
+
## Trigger the pipeline
-
+
### Continuous deployment
+
Set up automatic builds triggered by Git events. You can establish continuous deployment in two ways:
+
* **New Service:** Create a new runtime service and connect it to your GitHub or GitLab repository during the service creation process.
* **Existing Services:** Go to the service detail and choose **Pipelines & CI/CD settings** from the left menu. Click **Connect with a GitHub repository** or **Connect with a GitLab repository** to link your repository.
+
Once connected, Zerops will automatically build and deploy your application with each push to the selected branch or when you create a new tag.
-
+
### On-demand deployment
+
Trigger builds and deployments manually when needed using either the CLI or GUI.
+
#### Using Zerops CLI
+
- **Build and deploy:** `zcli service push` - Uploads code and triggers the full pipeline
- **Deploy only:** `zcli service deploy` - Skips build, deploys pre-built artifacts
+
See [CLI commands documentation](/references/zcli/commands#service-operations) for all parameters.
+
#### Using Zerops GUI
+
In **Pipelines & CI/CD settings** section of your service detail:
+
- **Re-deploy last pipeline** - With optional secret env variable updates
- **Trigger new pipeline** - From git repo or with custom configuration
+
#### Using import YAML
-Add `buildFromGit: ` to your service configuration for one-time build during import. See [import documentation](/references/import#service-basic-configuration).
+
+Add `buildFromGit: ` to your service configuration for one-time build during import. See [import documentation](/references/import#service-basic-configuration).
+
## Build phase
-
+
Zerops starts a temporary build container and executes these steps:
+
1. **Install build environment** - Sets up the runtime and tools
2. **Download source code** - From [GitHub ↗](https://www.github.com), [GitLab ↗](https://www.gitlab.com) or via [Zerops CLI](/references/cli)
3. **Customize environment** - Runs optional preparation commands
4. **Execute build commands** - Compiles and packages your application
5. **Upload artifacts** - Stores build output in internal Zerops storage
6. **Cache files** - Optionally [caches](/features/build-cache) selected files for faster future builds
+
Zerops automatically deletes the build container after the build finishes or fails.
+
### Build hardware resources
+
All runtime services use the same hardware resources for build containers:
-
- HW resource
- Minimum
- Maximum
-
- CPU cores
- 1
- 5
-
- RAM
- 8 GB
- 8 GB
-
- Disk
- 1 GB
- 100 GB
-
+
+
+
+
+
HW resource
+
Minimum
+
Maximum
+
+
+
+
+
CPU cores
+
1
+
5
+
+
+
RAM
+
8 GB
+
8 GB
+
+
+
Disk
+
1 GB
+
100 GB
+
+
+
+
Build containers start with minimum resources and scale vertically up to maximum capacity as needed.
+
:::info
Build container resources are not charged. Build costs are covered by the standard Zerops [project fee](https://zerops.io/#pricing).
:::
+
### Build time limit
+
The entire build pipeline has a **1 hour** time limit. After 1 hour, Zerops terminates the build pipeline and deletes the build container.
+
### Customize the build environment
+
All runtime services start with a default build environment based on the [build.base](/zerops-yaml/specification#base-) attribute in `zerops.yaml`. Install additional packages or tools by adding [build.prepareCommands](/zerops-yaml/specification#preparecommands-) to your configuration.
+
Learn more about customizing build environments:
+
## Runtime prepare phase (optional)
-
+
When your application requires additional system packages, libraries, or tools in the runtime environment, Zerops allows you to build a custom runtime image. This optional phase occurs after the build phase and before deployment.
+
### When to use custom runtime images
+
Build custom runtime images when you need:
- System packages or libraries for runtime operations (e.g., `sudo apk add imagemagick` for image processing)
- Library dependencies for interpreted languages or dynamically linked binaries
- System-level tools or utilities your application requires
- Customized base operating system or additional software layers
+
### Configuration
+
Configure custom runtime images in your `zerops.yml` file using these fields:
+
#### `run.os` + `run.base`
+
Specify the operating system and base packages for your custom runtime image:
+
```yaml
run:
os: alpine # or ubuntu
base: nodejs@20 # specify your runtime and version
```
+
#### `run.prepareCommands`
+
Define commands that customize your runtime image. These commands run inside a fresh base container:
+
```yaml
run:
prepareCommands:
- sudo apk add --no-cache imagemagick
- sudo apt-get update && apt-get install -y some-package # for Ubuntu
```
+
:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::
+
Zerops creates the custom runtime image from this container after all commands complete successfully.
+
#### `build.addToRunPrepare`
+
Copy specific files from the build phase to the runtime prepare phase. This is useful when you need source files during runtime preparation:
+
```yaml
build:
addToRunPrepare:
@@ -7318,16 +10770,23 @@ build:
- requirements.txt
- config/runtime-setup.sh
```
+
These files are packed immediately after `build.buildCommands` finish and become available during the runtime prepare phase.
+
### How it works
+
When you trigger the first deploy with defined [run.prepareCommands](/zerops-yaml/specification#preparecommands--1), Zerops:
+
1. **Creates prepare container** - Based on `run.os` and `run.base`
2. **Copies build files** - Files specified in [build.addToRunPrepare](/zerops-yaml/specification#addtorunprepare-) (if any)
3. **Runs prepare commands** - Executes [run.prepareCommands](/zerops-yaml/specification#preparecommands--1) in order
4. **Creates runtime image** - Builds custom runtime image from the prepared container
5. **Uses for deployment** - Deploys your application using this custom runtime image
+
### Custom runtime image caching
+
Zerops caches custom runtime images to optimize deployment times. The runtime prepare phase is skipped and cached images are reused when:
+
- It is not the first deployment of your service
- None of these `zerops.yaml` fields changed since the last deployment:
- `run.os` or `run.base`
@@ -7335,61 +10794,94 @@ Zerops caches custom runtime images to optimize deployment times. The runtime pr
- `build.addToRunPrepare`
- File contents specified in `build.addToRunPrepare` remain unchanged
- The custom runtime image cache hasn't been manually invalidated
+
#### Manual cache invalidation
+
To invalidate the custom runtime image cache, go to your service detail in the Zerops GUI, choose **Pipelines & CI/CD settings** section from the left menu, and click on the button under **Pipeline #**. Then click on the **Clear runtime prepare image** button.
+
Learn more about building custom runtime images:
+
:::warning
Do not include your application code in the custom runtime image, as your built application code is deployed automatically into fresh containers.
+
Shared storage mounts are also not available during the runtime prepare phase.
:::
+
## Deploy phase
-
+
### Application artifacts
+
After the [build phase](#build-phase) completes, Zerops stores the application artifact in internal storage and deletes the build container.
+
For [manual deployments](#manual-deploy-using-zerops-cli) using Zerops CLI, the application artifact is also uploaded to internal storage.
+
Zerops uses the stored artifact to deploy identical versions of your application whenever a new container starts:
+
- During new application version deployments
- When applications [scale horizontally](/features/scaling#horizontal-scaling-runtime-services-linux-containers-and-docker)
- When runtime containers fail and new containers start automatically
+
### First deploy
+
For initial deployments, Zerops starts one or more runtime containers based on your service [auto scaling settings](/features/scaling).
+
Zerops executes these steps for each new container:
+
1. **Install runtime environment** - Sets up the runtime (or uses a custom runtime image if configured)
2. **Download application artifact** - Retrieves build output from internal storage
3. **Run initialization** - Executes optional [init commands](/zerops-yaml/specification#initcommands-)
4. **Start application** - Launches your app using the [start command](/zerops-yaml/specification#startcommands-)
5. **Check readiness** - Waits for [readiness check](/zerops-yaml/specification#readinesscheck-) to succeed (if configured)
6. **Activate container** - Container becomes active and receives incoming requests
+
Services with multiple containers deploy in parallel.
+
:::info
If your application needs initialization in each runtime container, add [init commands](/zerops-yaml/specification#initcommands-) to `zerops.yaml`.
:::
+
:::caution
Do not use `initCommands` for runtime environment customization. See [how to build custom runtime images](#runtime-prepare-phase-optional).
:::
+
### Subsequent deploys
+
For applications with existing running versions, Zerops starts new containers matching the count of existing containers.
+
Zerops executes the same steps as the first deployment for each new container. Your service briefly contains both new and old versions during this process.
+
Old containers are then removed from the project balancer to stop receiving new requests. The processes inside old containers terminate and Zerops gradually deletes all old containers.
+
### Readiness checks
+
If your application is not ready to handle requests immediately after starting via the [start command](/zerops-yaml/specification#startcommands-), configure a [readiness check](/zerops-yaml/specification#readinesscheck-) in your `zerops.yaml`.
+
When readiness checks are defined, Zerops:
+
1. **Starts your application**
2. **Performs readiness check**
3. **Waits and retries** - If check fails, waits 5 seconds and repeats step 2
4. **Activates container** - If check succeeds, marks container as active
+
Runtime containers with pending readiness checks do not receive incoming requests - only active containers handle traffic.
+
If readiness checks fail for 5 minutes, Zerops marks the container as failed, deletes it, creates a new container, and repeats the deployment process.
+
**Readiness check types:**
+
- `httpGet` - Succeeds when URL returns HTTP `2xx` status (5-second timeout, follows `3xx` redirects)
- `exec.command` - Succeeds when command returns status code 0 (5-second timeout)
+
Read the [runtime log](/nodejs/how-to/logs#runtime-log) to troubleshoot failed readiness checks.
+
## Manual deploy using Zerops CLI
-
-Start deploy-only pipelines using the [Zerops CLI](/references/cli). The `zcli service deploy` command uploads and deploys your application in Zerops. Use this when you have your own build process. For building applications in Zerops, use [continuous](#continuous-deployment) or [on-demand](#on-demand-deployment) deployment instead.
-```sh
+
+Start deploy-only pipelines using the [Zerops CLI](/references/cli). The [`zcli service deploy`](/references/zcli/commands#deploy) command uploads and deploys your application in Zerops. Use this when you have your own build process. For building applications in Zerops, use [continuous](#continuous-deployment) or [on-demand](#on-demand-deployment) deployment instead.
+
+```sh
Usage:
zcli service deploy pathToFileOrDir [flags]
+
Flags:
--archive-file-path string If set, zCLI creates a tar.gz archive with the application code in the required path relative
to the working directory. By default, no archive is created.
@@ -7405,109 +10897,159 @@ Flags:
--zerops-yaml-path string Sets a custom path to the zerops.yaml file relative to the working directory. By default zCLI
looks for zerops.yaml in the working directory.
```
+
`pathToFileOrDir` defines paths to directories and/or files relative to the working directory. The working directory defaults to the current directory and can be changed using the `--working-dir` flag.
+
Place `zerops.yaml` in the working directory.
+
:::info
You can modify the deploy pipeline anytime by updating the `zerops.yaml` in your working directory.
:::
+
## Manage builds and deployments
+
### Cancel running build
+
When you need to cancel an incorrect running build, use the Zerops GUI. Go to the service detail, open the running processes list, and click **Open pipeline detail**. Then click **Cancel build**.
-
+
:::caution
Build cancellation is only available before the build pipeline finishes. Once the build completes, deployment cannot be cancelled.
:::
+
### Application versions
+
Zerops keeps the 10 most recent versions of your application in internal storage.
+
Access the application versions list in Zerops GUI by going to service detail and choosing the **Pipelines & CI/CD settings** section from the left menu. The active version is highlighted - click the button below to show all archived versions.
-
+
Access pipeline details from the additional menu. Pipeline details contain:
+
- Pipeline configuration (`zerops.yaml`) used for the selected version
- Build log (if available)
- Prepare runtime log (if available)
+
You can download the build artifact for selected versions or manually delete inactive versions.
+
### Restore an archived version
+
Restore archived versions by choosing **Activate** from the additional menu. Zerops will deploy the selected version and archive the currently active version.
+
Environment variables restore to their state from the last moment when the selected version was active.
----------------------------------------
# Features > Rbac
+
Zerops provides granular access control through a role-based permission system, allowing you to precisely manage who can access and modify your organization's resources. This system operates at two levels: **organization-wide roles** and **per-project role overrides**.
+
## Core Concepts
+
When a user performs an action on a project or its resources, Zerops first checks for a project-specific role override. If none exists, the organization role applies:
+
#### Organization Role
The primary role assigned to a user, determining their **default permissions** across the entire organization and all its projects.
+
#### Project Role Override
An optional per-project permission that **supersedes the organization role** for that specific project and its resources (services, containers, environment variables, routing, etc.).
+
## User Roles
+
Zerops supports four user roles, listed from highest to lowest permission level:
-
- Role
- Organization Access
- Default Project Access
- Can Create Projects
- Can Manage Team
-
- Owner
- Full (incl. billing)
- Full
- ✓
- All roles
-
- Admin
- Full (excl. billing)
- Full
- ✓
- Developer, Guest
-
- Developer
- None
- None (per-project only)
- ✓
- ✗
-
- Guest
- None
- None (per-project only)
- ✗
- ✗
-
+
+
+
+
+
Role
+
Organization Access
+
Default Project Access
+
Can Create Projects
+
Can Manage Team
+
+
+
+
+
Owner
+
Full (incl. billing)
+
Full
+
✓
+
All roles
+
+
+
Admin
+
Full (excl. billing)
+
Full
+
✓
+
Developer, Guest
+
+
+
Developer
+
None
+
None (per-project only)
+
✓
+
✗
+
+
+
Guest
+
None
+
None (per-project only)
+
✗
+
✗
+
+
+
+
### Owner
+
:::note
Every organization must have at least one Owner at all times.
:::
+
The **Owner** role has unrestricted access to all organization resources:
+
- Full access to billing, invoices, and payment management
- Can invite, edit, and remove users of any role
- Automatic *Full access* to all projects
- Can create unlimited projects
- Minimum access level on any project is *Read only*
+
### Admin
+
The **Admin** role provides comprehensive access without billing permissions:
+
- Cannot view or manage billing information
- Can invite, edit, and remove users with Developer or Guest roles only
- Cannot manage other Admins or Owners
- Automatic *Full access* to all projects
- Can create unlimited projects
- Minimum access level on any project is *Read only*
+
### Developer
+
The **Developer** role is designed for team members who need to work on specific projects:
+
- No access to organization-level settings
- No default access to any projects — access must be granted per-project
- Can create new projects (automatically receives full access to projects they create)
- Cannot invite or manage other team members
+
### Guest
+
The **Guest** role provides the most restricted access:
+
- No access to organization-level settings
- No default access to any projects — access must be granted per-project
- Cannot create new projects
- Cannot invite or manage other team members
+
## Project Access Levels
+
When granting project access (either as a default for Owners/Admins or as an override for any role), two permission levels are available:
+
### Full Access
+
Users with full access to a project can:
+
- Start, stop, and restart services
- Deploy applications
- Create, edit, and delete services
@@ -7518,208 +11060,315 @@ Users with full access to a project can:
- Download backups and deployed code
- Manage project settings and routing
- Delete the project
+
### Read Only
+
Users with read-only access to a project can:
+
- View project structure and service status
- View logs and metrics
- View deployment history
- View non-sensitive environment variables
- View backup existence and metadata
- View VPN public keys (but not create new key pairs)
+
Users with read-only access **cannot**:
+
- Make any changes to project configuration
- Start, stop, or deploy services
- Access SSH web terminal or file browser
- Download backups or deployed code
- View sensitive environment variables (displayed as `REDACTED`)
- Create VPN key pairs
+
:::info Coming Soon
**Sensitive Environment Variables**: You will soon be able to mark specific environment variables as sensitive. These variables will be stored encrypted and hidden from users with read-only access, providing additional security for credentials and secrets.
:::
+
## Managing Team Members
+
Access team management at **Organization → Team**.
+
### Inviting New Members
+
1. Navigate to the Team section
2. Click **Invite Member**
3. Enter the user's email address
4. Select their organization role (Owner, Admin, Developer, or Guest)
5. Send the invitation
+
If the email belongs to an existing Zerops account, they'll receive an invitation to join your organization. If not, they'll be invited to create an account and will set up their password upon accepting.
+
### Editing Member Permissions
+
You can modify a team member's permissions in two ways:
+
**From the Team section**:
- Edit the user's organization role
- Configure their access to all projects at once
+
**From Project Settings**:
- Manage access for all users to that specific project
- Useful when onboarding a team to a new project
+
### Role Change Restrictions
+
- Users cannot modify their own role
- Admins can only modify users with Developer or Guest roles
- A user cannot be demoted if they have integration tokens with higher permissions — those tokens must be modified or deleted first
- At least one Owner must exist in the organization at all times
+
## Project Role Overrides
+
Project role overrides allow you to customize access for specific projects without changing a user's organization-wide role.
+
### Common Use Cases
+
**Restricting Admin access to production**:
An Admin who should have full access to development projects but only read-only access to production can have a Read only override set on the production project.
+
**Granting Developer access to specific projects**:
A Developer (who has no default project access) can be granted Full access to the projects they work on, while remaining unable to see other projects.
+
**Temporary project access for Guests**:
A Guest user (perhaps an external contractor) can be granted Read only or Full access to specific projects for the duration of their engagement.
+
### How Overrides Work
+
:::note
Owners and Admins cannot be set to "No access" on any project — the minimum override available for these roles is Read only.
:::
-
- Organization Role
- Without Override
- With Full Access Override
- With Read Only Override
-
- Owner
- Full access
- Full access
- Read only
-
- Admin
- Full access
- Full access
- Read only
-
- Developer
- No access
- Full access
- Read only
-
- Guest
- No access
- Full access
- Read only
-
+
+
+
+
+
Organization Role
+
Without Override
+
With Full Access Override
+
With Read Only Override
+
+
+
+
+
Owner
+
Full access
+
Full access
+
Read only
+
+
+
Admin
+
Full access
+
Full access
+
Read only
+
+
+
Developer
+
No access
+
Full access
+
Read only
+
+
+
Guest
+
No access
+
Full access
+
Read only
+
+
+
+
## Integration Tokens
+
Integration tokens provide programmatic access to the Zerops API, ideal for CI/CD pipelines, automation scripts, and third-party integrations.
+
### Token Access Levels
-
- Token Type
- Description
-
- Full access to all projects
- Can perform all operations on all current and future projects
-
- Read access to all projects
- Can view all projects and their resources, but cannot make changes
-
- Custom access per project
- No default access; each project must be explicitly added with Full or Read only permission
-
+
+
+
+
+
Token Type
+
Description
+
+
+
+
+
Full access to all projects
+
Can perform all operations on all current and future projects
+
+
+
Read access to all projects
+
Can view all projects and their resources, but cannot make changes
+
+
+
Custom access per project
+
No default access; each project must be explicitly added with Full or Read only permission
+
+
+
+
### Creating Tokens
+
Access token management at **Settings → Access Tokens Management**.
+
1. Click **Create Token**
2. Enter a descriptive name for the token
3. Select the access level
4. If using custom per-project access, add each project and set its permission level
5. Create the token
+
:::warning
The token value is displayed only once upon creation. Store it securely — you cannot retrieve it later.
:::
+
### Token Permission Constraints
+
Tokens cannot have higher permissions than the user who creates them:
-
- Your Role
- Available Token Types
-
- Owner
- Full access, Read access, Custom per project
-
- Admin
- Full access, Read access, Custom per project
-
- Developer
- Custom per project only
-
- Guest
- Custom per project only
-
+
+
+
+
+
Your Role
+
Available Token Types
+
+
+
+
+
Owner
+
Full access, Read access, Custom per project
+
+
+
Admin
+
Full access, Read access, Custom per project
+
+
+
Developer
+
Custom per project only
+
+
+
Guest
+
Custom per project only
+
+
+
+
### Managing Tokens
+
:::note
Admins can manage tokens created by Developers and Guests, but cannot manage tokens created by other Admins or Owners.
:::
+
- **View**: Owners and Admins can see all tokens; Developers and Guests can only see their own tokens
- **Edit**: A token's name, access level, or per-project permissions can be modified at any time
- **Regenerate**: Creates a new token value while preserving all settings (the old token immediately stops working)
- **Delete**: Permanently removes the token
+
---
+
## API Access & Advanced Configuration
+
The Zerops API provides additional flexibility beyond what's available in the dashboard. This section covers capabilities accessible only through the API.
+
:::info
For complete API documentation, see the [Zerops OpenAPI Specification](/references/api).
:::
+
### Backend Role System
+
The API uses a more granular role system than the dashboard interface:
-
- Dashboard Role
- API Role Code
- Notes
-
- Owner
- OWNER
- Includes canViewFinances, canEditFinances, and canCreateProjects flags (always enabled)
-
- Admin
- ADMIN
- Includes canCreateProjects flag (always enabled)
-
- Developer
- NO_ACCESS
- With canCreateProjects: true
-
- Guest
- NO_ACCESS
- With canCreateProjects: false
-
- —
- BASIC_USER
- Available via API only
-
- —
- READ_ONLY
- Available via API only
-
+
+
+
+
+
Dashboard Role
+
API Role Code
+
Notes
+
+
+
+
+
Owner
+
OWNER
+
Includes canViewFinances, canEditFinances, and canCreateProjects flags (always enabled)
+
+
+
Admin
+
ADMIN
+
Includes canCreateProjects flag (always enabled)
+
+
+
Developer
+
NO_ACCESS
+
With canCreateProjects: true
+
+
+
Guest
+
NO_ACCESS
+
With canCreateProjects: false
+
+
+
—
+
BASIC_USER
+
Available via API only
+
+
+
—
+
READ_ONLY
+
Available via API only
+
+
+
+
### Additional Roles (API Only)
+
**BASIC_USER**
- Can view all projects (unless overridden to `NO_ACCESS`)
- Can perform all project operations (start/stop services, deploy, view logs, etc.)
- Cannot delete projects
- Cannot create projects without the `canCreateProjects` flag
- Cannot manage team members
+
**READ_ONLY**
- Can view all projects (unless overridden to `NO_ACCESS`)
- Cannot make any changes
- Cannot access SSH terminal, file browser, or VPN key creation
- Cannot download backups or deployed code
- Sensitive environment variables displayed as `REDACTED`
+
### Permission Flags
+
The API supports additional permission flags that can be set on any user regardless of role:
-
- Flag
- Description
-
- canViewFinances
- Allows viewing billing information, invoices, and payment sources
-
- canEditFinances
- Allows modifying billing information and processing payments (automatically enables canViewFinances)
-
- canCreateProjects
- Allows creating new projects (user receives OWNER role on projects they create)
-
+
+
+
+
+
Flag
+
Description
+
+
+
+
+
canViewFinances
+
Allows viewing billing information, invoices, and payment sources
+
+
+
canEditFinances
+
Allows modifying billing information and processing payments (automatically enables canViewFinances)
+
+
+
canCreateProjects
+
Allows creating new projects (user receives OWNER role on projects they create)
+
+
+
+
These flags enable scenarios like:
- An Admin who needs to view (but not edit) billing information
- A Developer who should be able to create projects but also view invoices
- A read-only user who monitors billing status
+
### Project Role Overrides via API
+
The API allows setting any role as a project override, including `NO_ACCESS`:
+
```yaml
# Example: Set NO_ACCESS override for a user on a specific project
PUT /api/rest/public/client-user/{id}/roles
@@ -7732,144 +11381,218 @@ PUT /api/rest/public/client-user/{id}/roles
]
}
```
+
This enables scenarios not possible through the dashboard, such as hiding specific projects from users who would otherwise have access based on their organization role.
+
### Role Resolution Logic
+
When determining a user's effective permissions for a project:
+
1. Check if a project-specific role override exists
2. If yes, use that role for all project-related operations
3. If no, use the organization role
+
For non-project operations (billing, team management), only the organization role applies.
+
----------------------------------------
# Features > Scaling
+
Zerops delivers enterprise-grade infrastructure with built-in automatic scaling and high availability. This means applications and databases dynamically adjust to traffic demands—scaling up during peak loads to maintain performance and scaling down during quiet periods to reduce costs.
+
Unlike traditional hosting where resources must be predicted and pre-provisioned, Zerops continuously monitors workloads and automatically allocates exactly what is needed, when it is needed. This intelligent resource management ensures optimal performance without wasted spend.
+
## Key Benefits
+
- **Cost Optimization**: Only pay for resources actually used
- **Performance Reliability**: Maintain responsiveness during traffic spikes
- **Automatic Management**: Built-in best practices with customizable settings
- **High Availability**: Redundancy options for production environments
+
## Understanding Zerops Scaling Architecture
+
Zerops uses two fundamentally different approaches for optimizing infrastructure:
+
#### **Resource Management (Vertical Scaling)**
- **Applies to:** Runtime services, databases, shared storage, and Linux containers (Alpine and Ubuntu)
- **What it does:** Adjusts CPU, RAM, and disk resources within individual containers
- **Management:** Automated by Zerops, but customizable by users
+
:::note
Docker services do not support automatic vertical scaling. Resource values can be manually changed, but this triggers a VM restart.
:::
+
#### **Container Architecture**
- **For Runtime Services, Linux Containers, and Docker:** Horizontal Scaling (dynamic container count)
- Adds or removes containers/VMs based on load
- Requires applications to be designed for HA operation
- Container/VM creation limits can be controlled
- Docker containers run in VMs rather than native containers
+
- **For Databases & Shared Storage:** High Availability Mode (fixed container count)
- Single Container OR Multi-Container HA configuration
- Must be chosen at service creation (cannot be changed later)
- Managed by Zerops (no application changes needed)
+
### At-a-Glance Comparison
+
* ✓ = Available *(configurable, defaults vary according to service type)*
-
- Feature
- Runtime Services & Linux Containers
- Databases
- Shared Storage
- Docker
-
- Automatic Resource Scaling
- ✓
- ✓
- ✓
- Manual (triggers VM restart)
-
- Automatic Horizontal Scaling
- ✓
- Fixed # of containers
- Fixed # of containers
- ✓
-
- High Availability
- User-implemented
- Zerops-managed HA mode
- Zerops-managed HA mode
- User-implemented
-
+
+
+
+
Feature
+
Runtime Services & Linux Containers
+
Databases
+
Shared Storage
+
Docker
+
+
+
+
+
Automatic Resource Scaling
+
✓
+
✓
+
✓
+
Manual (triggers VM restart)
+
+
+
Automatic Horizontal Scaling
+
✓
+
Fixed # of containers
+
Fixed # of containers
+
✓
+
+
+
High Availability
+
User-implemented
+
Zerops-managed HA mode
+
Zerops-managed HA mode
+
User-implemented
+
+
+
+
## When to Configure Scaling
+
You can configure scaling settings at three different stages:
+
- **During service creation** - Configure initial scaling parameters when creating services in the Zerops GUI. Set resource limits, CPU mode, and container counts from the start.
+
- **During import** - Use YAML configuration files to define comprehensive scaling settings including `verticalAutoscaling` parameters and horizontal scaling limits. See [Import & Export YAML Configuration](/references/import) for complete syntax.
+
- **After service creation** - Modify most scaling settings anytime through your service's **Automatic scaling configuration** page. Note that some parameters like deployment mode for databases and shared storage cannot be changed after creation.
+
This flexibility lets you plan scaling strategies upfront or adapt them as requirements evolve.
+
## Part 1: Resource Management
+
Resource management in Zerops focuses on efficiently allocating and adjusting CPU, RAM, and disk resources within individual containers based on actual usage patterns.
+
These resource management capabilities apply to **runtime** services, **databases**, **shared storage**, and **Linux containers** (Alpine and Ubuntu).
+
:::note
Docker services do not support automatic vertical scaling. Resources for Docker services are fixed at the values set manually and do not automatically adjust based on usage.
:::
+
:::tip Disable Scaling for Specific Resources
To prevent automatic scaling of specific resources, simply set identical minimum and maximum values for CPU, RAM, or Disk.
:::
+
### CPU Settings
+
#### CPU Mode
+
Two CPU allocation modes are available for any service:
+
**Shared CPU**
+
Shared CPU provides a physical CPU core shared with up to 10 other applications. Performance varies depending on neighbors, ranging from 1/10 to 10/10 power. This option is cost-effective for non-critical workloads, development, and testing environments.
+
**Dedicated CPU**
+
Dedicated CPU gives exclusive access to a full physical CPU core(s), ensuring consistent and predictable performance. This option is ideal for production environments and CPU-intensive applications.
+
:::tip
CPU mode can be changed (once per hour) as needed.
:::
+
See the [pricing](/company/pricing#resource-pricing) for the difference between CPU modes.
+
#### Minimum and Maximum CPU Cores
+
Set boundaries for CPU core allocation. Zerops will scale CPU resources within these limits based on actual usage.
+
#### Start CPU Core Count
+
Determines how many CPU cores are allocated when containers start:
- Default: 2 cores
- Applies to both dedicated and shared CPU modes
- Higher values provide more processing power during application initialization
- After startup, resources are automatically adjusted based on actual usage and limits
+
#### CPU Scaling Thresholds
+
For services using [dedicated CPU](#cpu-mode) only, CPU scaling is controlled by:
+
**Min. Free CPU Cores (%)**
- Scale-up is triggered when free capacity drops below a fixed fraction of a single CPU core
- Default: 10%
- Set as a percentage of a single core's capacity
- Example: Setting to 20% means that with one core, at least 20% of that core should remain free
+
**Dynamic Min. Free Total Core Percent**
- Scale-up is triggered when total free capacity across all cores falls below a percentage of total capacity
- Default: 0% (disabled)
- Dynamically adjusts as the number of cores changes
- Ideal for accommodating varying load distributions
- Example: 20% setting ensures at least 20% of the combined capacity of all cores remains free
+
### RAM Settings
+
#### Minimum and Maximum RAM
+
Set boundaries for RAM allocation. Zerops will scale RAM within these limits based on actual usage.
+
#### RAM Scaling Thresholds
+
RAM usage is monitored every 10 seconds to ensure optimal performance. The minimum free RAM settings serve multiple important purposes: they prevent Out of Memory (OOM) errors, provide space for kernel disk caching (which improves application performance), and maintain a buffer for sudden memory demands.
+
Swap is enabled for all containers to help prevent OOM errors, but proper minimum free RAM configuration is still essential—especially for services that use large amounts of RAM or benefit from kernel disk caching. Without sufficient free memory, performance may degrade due to increased disk access.
+
Two threshold types determine RAM scaling:
+
**Minimum Free RAM (absolute value in GB)**
- Specifies an absolute threshold for free RAM
- Additional memory is triggered when available RAM falls below this fixed amount
- Default: 0.0625 GB (64 MB) for most services
- Ideal for maintaining system stability and responsiveness
+
**Minimum Free RAM (% of Granted)**
- Establishes a dynamic threshold based on a percentage of total granted memory
- Default: 0% (disabled)
- The buffer scales proportionally as total memory increases
- Particularly useful for handling varying loads
+
:::note
Whichever setting provides more free memory is used.
:::
+
+[Video: /vids/ram-scaling.webm](/vids/ram-scaling.webm)
+
### Disk Settings
+
#### Minimum and Maximum Disk
+
Set boundaries for disk space allocation. Zerops will scale disk space within these limits based on actual usage.
+
### Resource Scaling Behavior
+
Zerops implements an exponential growth pattern ensuring that **resources grow gradually** for minor load increases but can scale rapidly when significant additional capacity is needed. When resource usage triggers scaling, Zerops initially adds smaller increments, but as demand continues to increase, it can add larger increments to quickly meet the needs of your application.
+
Below are the parameters that control this behavior across all services that support vertical scaling:
+
- **Data Collection Interval:** How frequently resource usage metrics are collected
- **Scale-Up Window Interval:** The timeframe in which high usage must persist before adding resources
- **Scale-Down Window Interval:** The timeframe in which low usage must persist before reducing resources
@@ -7877,122 +11600,177 @@ Below are the parameters that control this behavior across all services that sup
- **Scale-Down Threshold Percentile:** The usage percentile that triggers resource scaling down
- **Minimum Step:** The smallest increment by which resources can increase during scaling
- **Maximum Step:** The largest possible increment for resources when scaling rapidly under high load
-
- Parameter
- CPU
- RAM
- Disk
-
- Data Collection Interval
- 10 seconds
- 10 seconds
- 10 seconds
-
- Scale-Up Window Interval
- 20 seconds
- 10 seconds
- 10 seconds
-
- Scale-Down Window Interval
- 60 seconds
- 120 seconds
- 300 seconds
-
- Scale-Up Threshold Percentile
- 60
- 50
- 50
-
- Scale-Down Threshold Percentile
- 40
- 50
- 50
-
- Minimum Step
- 1 (0.1 cores)
- 0.125 GB
- 0.5 GB
-
- Maximum Step
- 40
- 32 GB
- 128 GB
-
-## Part 2: Container Architecture — Service-Specific Approaches
-Container architecture in Zerops defines how services are distributed across containers. Different service types use fundamentally different approaches:
-1. **Horizontal Scaling** (Runtime Services, Linux Containers, and Docker)
+
+
+
+
+
Parameter
+
CPU
+
RAM
+
Disk
+
+
+
+
+
Data Collection Interval
+
10 seconds
+
10 seconds
+
10 seconds
+
+
+
Scale-Up Window Interval
+
20 seconds
+
10 seconds
+
10 seconds
+
+
+
Scale-Down Window Interval
+
60 seconds
+
120 seconds
+
300 seconds
+
+
+
Scale-Up Threshold Percentile
+
60
+
50
+
50
+
+
+
Scale-Down Threshold Percentile
+
40
+
50
+
50
+
+
+
Minimum Step
+
1 (0.1 cores)
+
0.125 GB
+
0.5 GB
+
+
+
Maximum Step
+
40
+
32 GB
+
128 GB
+
+
+
+
+## Part 2: Container Architecture — Service-Specific Approaches
+
+Container architecture in Zerops defines how services are distributed across containers. Different service types use fundamentally different approaches:
+
+1. **Horizontal Scaling** (Runtime Services, Linux Containers, and Docker)
2. **Deployment Modes** (Databases and Shared Storage)
+
### Horizontal Scaling (Runtime Services, Linux Containers, and Docker)
+
Horizontal scaling adds or removes entire containers (or VMs for Docker) as demand fluctuates.
* When vertical scaling reaches its defined maximum, new containers/VMs are automatically added to handle additional load.
* As demand decreases, containers/VMs are gradually removed to optimize resource usage.
+
:::important HA-ready Applications
For applications to work properly across multiple containers, they must be designed to be HA-ready.
:::
+
#### Setting Horizontal Scaling Parameters
+
To configure horizontal scaling, users need to set the minimum and maximum number of containers:
+
- **Minimum Containers**: The baseline number of containers that should always be running (system limit: 1)
- **Maximum Containers**: The upper limit of containers that can be created during high demand (system limit: 10)
+
:::tip Disable Horizontal Scaling
Setting identical minimum and maximum values creates a fixed number of containers (disables automatic horizontal scaling).
:::
+
### Deployment Modes (Databases and Shared Storage)
+
For databases and shared storage services, Zerops offers two deployment modes focused on reliability and data integrity.
+
:::warning
Deployment mode cannot be changed after creation.
:::
+
#### Single Container Mode
+
Single Container Mode provides one container with vertical scaling only. This is suitable for development environments or non-critical data storage.
+
**Characteristics:**
- Limited redundancy
- No automatic recovery if the container fails
- Data since last backup (if available) may be lost if failure occurs
- Cost-effective for non-production environments
+
#### Highly Available (HA) Mode
+
Highly Available (HA) Mode creates multiple containers with built-in redundancy. This mode is strongly recommended for production environments and mission-critical data.
+
**Characteristics:**
- Multiple containers distributed across different physical machines
- Automatic failover and recovery mechanisms
- Data redundancy and integrity protection
- Higher reliability and availability
- Recommended for production use
+
:::important
Database and shared storage services in HA mode have a **fixed number of containers** that cannot be increased or decreased.
:::
+
**Recovery process:**
+
In HA mode, when a container or physical machine fails, recovery is handled automatically:
+
1. The failed container is disconnected from the cluster
2. A new container is created on a different physical machine
3. Data is synchronized from remaining healthy copies
4. The failed container is removed
5. Service continues with minimal disruption
+
+[Video: /vids/database-scaling.webm](/vids/database-scaling.webm)
+
### Fixed Resource Allocation (Docker Services)
+
Docker services in Zerops operate differently from other service types:
+
#### Docker Service Characteristics
+
- **VM-Based Deployment**: Docker services run in virtual machines rather than containers
- **Fixed Resources**: Unlike other services, Docker services do not support automatic vertical scaling
- **User-Defined Resources**: Resources are set at creation and remain fixed until manually changed
- **VM Count Changes**: The number of VMs can be changed, but this requires a VM restart
- **No Automatic Scaling**: Resource levels do not automatically adjust based on usage
+
**Important Considerations for Docker Services:**
- Initial resource values should be chosen carefully, as they cannot automatically scale
- Planning for expected peak loads is important when setting resource values
- Runtime services or Linux containers should be considered instead if dynamic scaling is essential
- VM restarts cause temporary service disruption when changing VM count or resources
+
:::warning
Docker services use fixed resources that do not automatically scale. Sufficient resources should be allocated at creation to handle expected workload. Additionally, disk space for Docker services can only be increased, not decreased without recreation of the service.
:::
+
## Monitoring Your Infrastructure
+
Zerops provides comprehensive monitoring tools in the user interface to track both resource usage and container scaling activities:
+
### Resource History Graphs
+
Resource and container scaling can be visualized over time:
- CPU utilization per container
- RAM usage patterns
- Disk space consumption
- Container count changes
+
These graphs help understand application resource needs, identify usage patterns, and fine-tune scaling settings for optimal performance and cost efficiency.
+
+[Video: /vids/containers.webm](/vids/containers.webm)
+
## Troubleshooting
+
#### Resource-Related Issues (All Service Types Except Docker)
+
**Out of Memory Errors**
* **Issue:** Application crashes with OOM errors despite resource scaling.
* **Possible Cause:** Insufficient minimum free RAM setting.
@@ -8000,6 +11778,7 @@ These graphs help understand application resource needs, identify usage patterns
- Increase the "Minimum free RAM" setting
- Check for memory leaks in the application
- Consider setting a higher minimum RAM value
+
**Excessive Resource Costs**
* **Issue:** Resources scaling up but not scaling down efficiently.
* **Possible Cause:** Scale-down thresholds not optimized.
@@ -8007,7 +11786,9 @@ These graphs help understand application resource needs, identify usage patterns
- Review usage patterns in monitoring graphs
- Adjust scale-down thresholds to be more aggressive
- Set appropriate resource minimums based on base requirements
+
#### Runtime Service and Linux Container Issues (Horizontal Scaling)
+
**Application Not Working Properly Across Multiple Containers**
* **Issue:** Application errors or inconsistent behavior when horizontally scaled.
* **Possible Cause:** Application not designed for distributed operation.
@@ -8015,22 +11796,29 @@ These graphs help understand application resource needs, identify usage patterns
- Ensure the application properly handles stateless operation
- Implement proper session management across containers
- Review and modify application code to support multiple instances
+
#### Docker Service Issues
+
**Insufficient Resources for Workload**
* **Issue:** Docker service experiencing performance issues or crashes.
* **Possible Cause:** Fixed resources inadequate for actual workload.
* **Solution:**
- Since Docker services don't support automatic vertical scaling, a new service with higher resource allocations may be needed
- Consider migrating to a runtime service or Linux container if dynamic resource scaling is needed
+
*Need help implementing scaling in your project? Join our [Discord community](https://discord.gg/zerops) where our team and other Zerops users can assist you!*
----------------------------------------
# Gleam > How To > Build Pipeline
+
Zerops provides a customizable build and runtime environment for your Gleam application.
+
## Add zerops.yaml to your repository
+
Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:
+
```yaml
zerops:
# define hostname of your service
@@ -8039,51 +11827,65 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: gleam@latest
+
# OPTIONAL. Set the operating system for the build environment.
# os: ubuntu
+
# OPTIONAL. Customise the build environment by installing additional packages
# or tools to the base build environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Build your application
buildCommands:
- npm i
- npm run build
+
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- dist
- package.json
- node_modules
+
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: node_modules
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: gleam@latest
+
# OPTIONAL. Sets the internal port(s) your app listens on:
ports:
# port number
- port: 3000
+
# OPTIONAL. Customise the runtime Gleam environment by installing additional
# dependencies to the base Gleam runtime environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Run one or more commands each time a new runtime container
# is started or restarted. These commands are triggered before
# your Gleam application is started.
# initCommands:
# - rm -rf ./cache
+
# REQUIRED. Your Gleam application start command
start: npm start
```
+
The top-level element is always `zerops`.
+
### Setup
+
The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:
+
```yaml
zerops:
# definition for app service
@@ -8094,6 +11896,7 @@ zerops:
deploy: ...
# required
run: ...
+
# definition for api service
- setup: api
# optional
@@ -8103,11 +11906,19 @@ zerops:
# required
run: ...
```
+
Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.
+
## Build pipeline configuration
+
### base
+
_REQUIRED._ Sets the base technology for the build environment.
+
Following options are available for Gleam builds:
+
+- `gleam@1.5`, `gleam@1`, `gleam@latest`
+
```yaml
zerops:
# hostname of your service
@@ -8118,12 +11929,18 @@ zerops:
base: gleam@latest
...
```
+
+
The base build environment contains {data.alpine.default}, the selected
- major version of Gleam, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
+ major version of Gleam, [Zerops command line tool](/references/cli), `npm`, `yarn`, `git` and `npx` tools.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -8137,34 +11954,52 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).
+
To customise your build environment use the [prepareCommands](#preparecommands) attribute.
+
:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::
+
### os
+
_OPTIONAL._ Sets the operating system for the build environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customised.
:::
+
:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::
+
### prepareCommands
+
_OPTIONAL._ Customises the build environment by installing additional dependencies or tools to the base build environment.
+
The base build environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- selected version of Gleam defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `npm`, `yarn`, `git` and `npx` tools
+
To install additional packages or tools add one or more prepare commands:
+
```yaml
zerops:
# hostname of your service
@@ -8173,6 +12008,7 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: gleam@latest
+
# OPTIONAL. Customise the build environment by installing additional packages
# or tools to the base build environment.
prepareCommands:
@@ -8180,20 +12016,31 @@ zerops:
- curl something else
...
```
+
When the first build is triggered, Zerops will
+
1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order
+
The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.
+
:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/gleam/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### buildCommands
+
_OPTIONAL._ Defines build commands.
+
```yaml
zerops:
# hostname of your service
@@ -8202,42 +12049,59 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: gleam@latest
+
# OPTIONAL. Build your application
buildCommands:
- npm i
- npm run build
...
```
+
Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.
+
Before the build commands are triggered the build container contains:
+
1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code
+
#### Run build commands as a single shell instance
+
Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.
+
```yaml
buildCommands:
- |
npm i
npm run build
```
+
#### Run build commands as a separate shell instances
+
When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.
+
```yaml
buildCommands:
- npm i
- npm run build
```
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/gleam/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.
+
```yaml
buildCommands:
- npm i --verbose
- npm run build
```
+
If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.
+
### deployFiles
-_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use `.deployignore` file.
+
+_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.
+
```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
@@ -8246,56 +12110,81 @@ deployFiles:
- package.json
- node_modules
```
+
Determines files or folders produced by your build, which should be deployed to your runtime service containers.
+
The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.
+
The files/folders will be placed into `/var/www` folder in runtime, e.g. `./src/assets/fonts` would result in `/var/www/src/assets/fonts`.
+
#### Examples
+
Deploys a folder, and a file from the project root directory:
+
```yaml
deployFiles:
- dist
- package.json
```
+
Deploys the whole content of the build container:
+
```yaml
deployFiles: .
```
+
Deploys a folder, and a file in a defined path:
+
```yaml
deployFiles:
- ./path/to/file.txt
- ./path/to/dir/
```
+
#### How to use a wildcard in the path
+
Zerops supports the `~` character as a wildcard for one or more folders in the path.
+
Deploys all `file.txt` files that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/file.txt
```
+
Deploys all folders that are located in any path that begins with `/path/to/`
+
```yaml
deployFiles: ./path/to/~/
```
+
Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/
```
+
:::note Example
By default, `./src/assets/fonts` deploys to `/var/www/src/assets/fonts`, keeping the full path. Adding `~`, like `./src/assets/~fonts`, shortens it to `/var/www/fonts`
:::
#### .deployignore
-Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as `.gitignore`.
+
+Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as [`.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format).
+
To ignore a specific file or directory path, start the pattern with a forward slash (`/`). Without the leading slash, the pattern will match files with that name in any directory.
+
:::tip
For consistency, it's recommended to configure both your `.gitignore` and `.deployignore` files with the same patterns.
:::
+
Examples:
+
```yaml title="zerops.yaml"
zerops:
- setup: app
build:
deployFiles: ./
```
+
```text title=".deployignore"
/src/file.txt
```
@@ -8307,22 +12196,33 @@ This example above ignores `file.txt` in ANY directory named `src`, such as:
- `/src/file.txt`
- `/folder2/folder3/src/file.txt`
- `/src/src/file.txt`
+
:::note
-`.deployignore` file also works with `zcli service deploy` command.
+`.deployignore` file also works with [`zcli service deploy`](/references/zcli/commands#deploy) command.
:::
+
### cache
+
_OPTIONAL._ Defines which files or folders will be cached for the next build.
+
```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```
+
The cache attribute helps optimize build times by preserving specified files between builds.
+
The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).
+
Learn more about the [build cache system](/features/build-cache) in Zerops.
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the build environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -8331,6 +12231,7 @@ zerops:
build:
base: gleam@latest
…
+
# OPTIONAL. Defines the env variables for the build environment:
envVariables:
NODE_ENV: production
@@ -8339,12 +12240,20 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/gleam/how-to/env-variables) in Zerops.
+
## Runtime configuration
+
### base
+
_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Gleam version for your runtime.
+
Following options are available for Gleam runtimes:
+
+- `gleam@1.5`, `gleam@1`, `gleam@latest`
+
```yaml
zerops:
# hostname of your service
@@ -8354,18 +12263,25 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: gleam@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: gleam@latest
...
```
+
+
The base runtime environment contains {data.alpine.default}, the
selected major version of Gleam, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -8375,6 +12291,7 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: gleam@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
@@ -8384,36 +12301,58 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [run base environments](/zerops-yaml/base-list).
+
To customise your build environment use the `prepareCommands` attribute.
+
### os
+
_OPTIONAL._ Sets the operating system for the runtime environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customised.
:::
+
### ports
+
_OPTIONAL._ Specifies one or more internal ports on which your application will listen.
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
For example, to connect to a Gleam service with hostname = "app" and port = 3000 from another service of the same project, simply use `app:3000`. Read more about [how to access a Gleam service](/references/networking/internal-access#basic-service-communication).
+
Each port has following attributes:
+
| parameter | description |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| port | Defines the port number. You can set any port number between _10_ and _65435_. Ports outside this interval are reserved for internal Zerops systems. |
| protocol | **Optional.** Defines the protocol. Allowed values are `TCP` or `UDP`. Default value is `TCP`. |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |
| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. |
+
### prepareCommands
+
_OPTIONAL._ Customises the Gleam runtime environment by installing additional dependencies or tools to the runtime base environment.
+
+
The base Gleam environment contains {data.alpine.default} the selected
- major version of Gleam, Zerops command line tool and `npm`, `yarn`, `git` and `npx` tools. To install
+ major version of Gleam, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools. To install
additional packages or tools add one or more prepare commands:
+
+
```yaml
zerops:
# hostname of your service
@@ -8421,6 +12360,7 @@ zerops:
# ==== how to build your application ====
build:
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -8430,27 +12370,45 @@ zerops:
- curl something else
...
```
+
When the first deploy with a defined prepare attribute is triggered, Zerops will
+
1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order
+
:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/gleam/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.
+
#### Cache of your custom runtime environment
+
Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:
+
1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.
+
To invalidate the custom runtime cache go to `yyy`
+
When the custom runtime cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### Copy folders or files from your build container
+
+
The prepare runtime container contains {data.alpine.default}, the
- selected major version of Gleam, Zerops command line tool and `npm`, `yarn`, `git` and `npx` tools.
+ selected major version of Gleam, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools.
+
+
The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).
+
```yaml
zerops:
# hostname of your service
@@ -8459,6 +12417,7 @@ zerops:
build:
...
addToRunPrepare: ./runtime-config.yaml
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -8468,15 +12427,20 @@ zerops:
- curl something else
...
```
+
In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.
+
### initCommands
+
_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Run one or more commands each time a new runtime container
@@ -8485,22 +12449,35 @@ zerops:
initCommands:
- rm -rf ./cache
```
+
These commands are triggered in the runtime container before your Gleam application is started via the [start command](#start).
+
:::note
`run.initCommands` run in the `/var/www` directory.
:::
+
Use init commands to clean or initialise your application cache or similar operations.
+
:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/gleam/how-to/scaling) or when a runtime container is restarted).
+
Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::
+
#### Command exit code
+
If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/gleam/how-to/logs#runtime-log) to troubleshoot the error.
+
#### Single or separated shell instances
+
You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the runtime environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -8515,57 +12492,84 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/gleam/how-to/env-variables) in Zerops.
+
### start
+
_REQUIRED._ Defines the start command for your Gleam application.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Gleam application start command
start: npm start
```
+
We recommend starting your Gleam application using `npm start`.
+
### health check
+
_OPTIONAL._ Defines a health check.
+
`healthCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the health check to request a local URL using a HTTP GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Gleam application start command
start: npm start
+
# OPTIONAL. Define a health check with a HTTP GET request option.
# Configures the check on http://127.0.0.1:80/status
healthCheck:
@@ -8573,25 +12577,32 @@ zerops:
port: 80
path: /status
```
+
#### exec
+
Configures the health check to run a local command.
Following attributes are available:
+
| Parameter | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/gleam/how-to/create#set-secret-environment-variables) as your Gleam application.
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below. |
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Gleam application start command
start: npm start
+
# OPTIONAL. Define a health check with a shell command.
healthCheck:
exec:
@@ -8600,13 +12611,18 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
### crontab
+
_OPTIONAL._ Defines cron jobs.
+
Setup cron jobs in the following format:
+
```yaml
zerops:
# define hostname of your service
- setup: app
+
# ==== how to run your application ====
run:
crontab:
@@ -8615,14 +12631,23 @@ zerops:
# REQUIRED. Sets the interval time to execute:
timing: "0 * * * *"
```
+
Read more about setting up [cron](/zerops-yaml/cron) in Zerops.
+
## Deploy configuration
+
### readiness check
+
_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/gleam/how-to/deploy-process#readiness-checks) in Zerops.
+
`readinessCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the readiness check to request a local URL using a http GET method.
+
Following attributes are available:
+
@@ -8652,13 +12677,16 @@ If your application requires a https request, set scheme: https
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -8667,25 +12695,33 @@ zerops:
httpGet:
port: 80
path: /status
+
# ==== how to run your application ====
run: ...
```
+
Read more about how the [readiness check works](/gleam/how-to/deploy-process#readiness-checks) in Zerops.
+
#### exec
+
Configures the readiness check to run a local command.
Following attributes are available:
+
| Parameter | Description |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **command** | Defines a local command to be run.
The command has access to the same [environment variables](/gleam/how-to/create#set-secret-environment-variables) as your Gleam application.
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below. |
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -8697,8 +12733,10 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
Read more about how the [readiness check works](/gleam/how-to/deploy-process#readiness-checks) in Zerops.
+
----------------------------------------
# Gleam > How To > Build Process
@@ -8715,34 +12753,58 @@ Read more about how the [readiness check works](/gleam/how-to/deploy-process#rea
# Gleam > How To > Create
+
Zerops provides a powerful Gleam runtime service with extensive build support. The Gleam runtime is highly scalable and customizable to suit your development and production needs. With just a few clicks or commands, you can have a production-ready Gleam environment up and running in no time.
+
## Create a Gleam service using Zerops GUI
+
First, set up a project in the Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu under the **Services** section. From there, you can add a new Gleam service:
+
+[Video: /vids/services/gleam.webm](/vids/services/gleam.webm)
+
### Choose a Gleam version
+
Zerops supports the following Gleam versions:
+
:::info
You can easily [upgrade](/gleam/how-to/upgrade) the major version at any time later.
:::
+
### Set a hostname
+
Enter a unique service identifier like "app", "cache", "gui", etc. Duplicate services with the same name within the same project are not allowed.
+
#### Limitations:
+
- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::
+
### Set secret environment variables
+
Add environment variables with sensitive data, such as passwords, tokens, salts, certificates, etc. These will be securely saved inside Zerops and added to your runtime service upon start.
+
Setting secret environment variables is optional. You can always set them later in the Zerops GUI.
+
Read more about the [different types of environment variables](/gleam/how-to/env-variables#service-env-variables) in Zerops.
+
## Create a Gleam service using zCLI
+
zCLI is the Zerops command-line tool. To create a new Gleam service via the command line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/gleam/how-to/create#create-a-project-description-file)
3. [Create a project with a Gleam and PostgreSQL service](#full-example)
+
### Create a project description file
+
Zerops uses a YAML format to describe the project infrastructure.
+
#### Basic example:
+
Create a directory called `my-project`. Inside the `my-project` directory, create a `description.yaml` file with the following content:
```yaml
# basic project data
@@ -8764,13 +12826,18 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes your future project infrastructure. The project will contain one Gleam version 20 service with default [auto scaling](/gleam/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/gleam/how-to/build-pipeline#ports). Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
#### Full example:
+
Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:
+
```yaml
# basic project data
project:
@@ -8815,103 +12882,171 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain a Gleam service and a [PostgreSQL](/postgresql/overview) service.
+
Gleam service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/gleam/how-to/build-pipeline#ports). Gleam service will run on version 20 with a custom vertical and horizontal scaling. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
+
| Parameter | Description | Limitations |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **name** | The name of the new project. Duplicates are allowed. | |
| **description** | **Optional.** Description of the new project. | Maximum 255 characters. |
| **tags** | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |
| **tags** | **Optional.** One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects. |
+
At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Gleam and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
+ hostname
+
+
The unique service identifier.
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
+ type
+
+
Specifies the service type and version.
-
+
See what [Gleam service types](/references/import-yaml/type-list#runtime-services) are currently supported.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto scaling parameters.
+
+
+
+
+ verticalAutoscaling
+
+
+ Optional. Defines [custom vertical auto scaling parameters](/gleam/how-to/create#set-auto-scaling-configuration).
+
All verticalAutoscaling attributes are optional. Not specified
attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
- minContainers
-
- Optional. Default = 1. Defines the minimum number of containers
- for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
+ - cpuMode
+
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
+ - minCpu/maxCpu
+
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
+ - minRam/maxRam
+
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
+ - minDisk/maxDisk
+
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
+ minContainers
+
+
+ Optional. Default = 1. Defines the minimum number of containers
+ for [horizontal autoscaling](/gleam/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- maxContainers
-
- Defines the maximum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
+ maxContainers
+
+
+ Defines the maximum number of containers for [horizontal autoscaling](/gleam/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- envSecrets
-
- Optional. Defines one or more secret env variables as a key value
- map. See env variable restrictions.
-
+
+
+
+
+ envSecrets
+
+
+ Optional. Defines one or more secret env variables as a key value
+ map. See env variable [restrictions](/gleam/how-to/env-variables#env-variable-restrictions).
+
+
+
+
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add Gleam service to an existing project
+
#### Example:
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -8932,33 +13067,38 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Gleam service version 20 with default [auto scaling](/gleam/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the import.yaml file is 100 kB.
+
----------------------------------------
# Gleam > How To > Customize Runtime
-System packages for processing: When your app processes images, videos, or files (requiring packages like sudo apk add imagemagick)',
- 'Erlang libraries: When you need additional Erlang libraries for your Gleam application',
- 'Native dependencies: When your Gleam dependencies require system libraries that aren\'t in the default environment',
- 'Different base OS: When you need Ubuntu instead of Alpine for specific compatibility requirements'
-]} />
+
----------------------------------------
@@ -9012,55 +13152,101 @@ System packages for processing: When your app processes images, videos, or files
# Gleam > Overview
+
[Gleam ↗](https://gleam.org/en) is an asynchronous event-driven JavaScript runtime, which is designed to build scalable network applications.
+
As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-gleam), a **_recipe_**, containing the most simple Gleam web application. The repo will be used as a source from which the app will be built.
- This is the most bare-bones example of Gleam app running in Zerops — as few libraries as possible,
+
+### 🚀 Feel free to deploy the recipe yourself
+
+This is the most bare-bones example of Gleam app running in Zerops — as few libraries as possible,
just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.
-
+
+ [Deploy "gleam" recipe on Zerops](https://app.zerops.io/recipe/?lf=gleam)
+
1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
+
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-gleam/blob/main/zerops-project-import.yaml)):
+
```yaml
project:
name: recipe-gleam
tags:
- zerops-recipe
+
services:
- hostname: api
type: gleam@1.5
enableSubdomainAccess: true
buildFromGit: https://github.com/zeropsio/recipe-gleam
+
- hostname: db
type: postgresql@16
mode: NON_HA
priority: 1
```
+
3. Click on **Import project** and wait until all pipelines have finished.
+
**That's it, your application is now up and running! :star: Let's check it works:**
+
1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://api-808-3000.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see
+
```
{"message":"This is a simple Gleam application running in Zerops.io, each request adds an entry to the PostgreSQL database and returns a count. See the source repository (https://github.com/zeropsio/recipe-gleam) for more information.","newEntry":"e64be640-d6c2-4be8-93ac-d1e40e56fa06","count":1}
```
+
:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::
+
## How to start
+
It doesn't matter whether it's your first curious introduction to Zerops, you have already mastered the basics and are looking for a tiny detail or inspiration. Below, choose a section that fits your needs:
+
+- [Care for details?](/gleam/how-to/create) — Dive in all Zerops has to offer for your Gleam application.
+- [Gleam recipes](https://github.com/zeropsio?q=gleam&type=all&language=&sort=) — Get inspired by already existing repositories, ready to be imported to Zerops.
+
## Feature Highlights
+
+- [Create Gleam service](/gleam/how-to/create) — Start with creating a Gleam service using GUI or zCLI.
+- [Zerops.yaml](/gleam/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
+- [Scaling configuration](/gleam/how-to/scaling) — Set up scaling of your Gleam application so that it runs smoothly while using only necessary resources.
+
{" "}
+
+- [Customize build environment](/gleam/how-to/build-process#customize-build-environment)
+- [Customize runtime environment](/gleam/how-to/customize-runtime)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+
+- [FAQ](/gleam/faq) — Most common questions in one place.
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Go > How To > Build Pipeline
+
Zerops provides a customizable build and runtime environment for your Go application.
+
## Add zerops.yaml to your repository
+
Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:
+
```yaml
zerops:
# define hostname of your service
@@ -9069,47 +13255,60 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: go@latest
+
# OPTIONAL. Set the operating system for the build environment.
# os: ubuntu
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Build your application
buildCommands:
- go build -o app main.go
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles: app
+
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
# cache: some_file
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: go@latest
+
# OPTIONAL. Sets the internal port(s) your app listens on:
ports:
# port number
- port: 8080
+
# OPTIONAL. Customize the runtime Go environment by installing additional
# dependencies to the base Go runtime environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Run one or more commands each time a new runtime container
# is started or restarted. These commands are triggered before
# your Go application is started.
# initCommands:
# - rm -rf ./cache
+
# REQUIRED. Your Go application start command
start: ./app
```
+
The top-level element is always `zerops`.
+
### Setup
+
The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:
+
```yaml
zerops:
# definition for app service
@@ -9120,6 +13319,7 @@ zerops:
deploy: ...
# required
run: ...
+
# definition for api service
- setup: api
# optional
@@ -9129,11 +13329,19 @@ zerops:
# required
run: ...
```
+
Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.
+
## Build pipeline configuration
+
### base
+
_REQUIRED._ Sets the base technology for the build environment.
+
Following options are available for Go builds:
+
+- `go@1.22`, `go@1`, `golang@1`, `go@latest`, `golang@latest`
+
```yaml
zerops:
# hostname of your service
@@ -9144,12 +13352,18 @@ zerops:
base: go@latest
...
```
+
+
The base build environment contains {data.alpine.default}, the selected
- version of Go, Zerops command line tool, `git` and `wget`.
+ version of Go, [Zerops command line tool](/references/cli), `git` and `wget`.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -9163,34 +13377,52 @@ zerops:
- zsc add nodejs@latest
...
```
+
See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).
+
To customize your build environment use the [prepareCommands](#preparecommands) attribute.
+
:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::
+
### os
+
_OPTIONAL._ Sets the operating system for the build environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customized.
:::
+
:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::
+
### prepareCommands
+
_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.
+
The base build environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- selected version of Go defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `git` and `wget`
+
To install additional packages or tools add one or more prepare commands:
+
```yaml
zerops:
# hostname of your service
@@ -9199,6 +13431,7 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: go@latest
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
prepareCommands:
@@ -9206,20 +13439,31 @@ zerops:
- curl something else
...
```
+
When the first build is triggered, Zerops will
+
1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order
+
The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.
+
:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/go/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### buildCommands
+
_OPTIONAL._ Defines build commands.
+
```yaml
zerops:
# hostname of your service
@@ -9228,96 +13472,138 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: go@latest
+
# OPTIONAL. Build your application
buildCommands:
- go build -o app main.go
...
```
+
Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.
+
Before the build commands are triggered the build container contains:
+
1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code
+
#### Run build commands as a single shell instance
+
Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it. Suppose your `main.go` file is in a `src` directory.
+
```yaml
buildCommands:
- |
cd src
go build -o app main.go
```
+
#### Run build commands as a separate shell instances
+
When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command. Suppose your `main.go` file is in a `src` directory.
+
```yaml
buildCommands:
- cd src
- go build -o app src/main.go
```
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/go/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.
+
```yaml
buildCommands:
- go build -v -o app main.go
```
+
If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.
+
### deployFiles
-_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use `.deployignore` file.
+
+_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.
+
```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- app
```
+
Determines files or folders produced by your build, which should be deployed to your runtime service containers.
+
The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.
+
The files/folders will be placed into `/var/www` folder in runtime, e.g. `./src/assets/fonts` would result in `/var/www/src/assets/fonts`.
+
#### Examples
+
Deploys a folder, and a file from the project root directory:
+
```yaml
deployFiles:
- app
- file.txt
```
+
Deploys the whole content of the build container:
+
```yaml
deployFiles: .
```
+
Deploys a folder, and a file in a defined path:
+
```yaml
deployFiles:
- ./path/to/file.txt
- ./path/to/dir/
```
+
#### How to use a wildcard in the path
+
Zerops supports the `~` character as a wildcard for one or more folders in the path.
+
Deploys all `file.txt` files that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/file.txt
```
+
Deploys all folders that are located in any path that begins with `/path/to/`
+
```yaml
deployFiles: ./path/to/~/
```
+
Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/
```
+
:::note Example
By default, `./src/assets/fonts` deploys to `/var/www/src/assets/fonts`, keeping the full path. Adding `~`, like `./src/assets/~fonts`, shortens it to `/var/www/fonts`
:::
#### .deployignore
-Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as `.gitignore`.
+
+Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as [`.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format).
+
To ignore a specific file or directory path, start the pattern with a forward slash (`/`). Without the leading slash, the pattern will match files with that name in any directory.
+
:::tip
For consistency, it's recommended to configure both your `.gitignore` and `.deployignore` files with the same patterns.
:::
+
Examples:
+
```yaml title="zerops.yaml"
zerops:
- setup: app
build:
deployFiles: ./
```
+
```text title=".deployignore"
/src/file.txt
```
@@ -9329,22 +13615,33 @@ This example above ignores `file.txt` in ANY directory named `src`, such as:
- `/src/file.txt`
- `/folder2/folder3/src/file.txt`
- `/src/src/file.txt`
+
:::note
-`.deployignore` file also works with `zcli service deploy` command.
+`.deployignore` file also works with [`zcli service deploy`](/references/zcli/commands#deploy) command.
:::
+
### cache
+
_OPTIONAL._ Defines which files or folders will be cached for the next build.
+
```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```
+
The cache attribute helps optimize build times by preserving specified files between builds.
+
The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).
+
Learn more about the [build cache system](/features/build-cache) in Zerops.
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the build environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -9353,6 +13650,7 @@ zerops:
build:
base: go@latest
…
+
# OPTIONAL. Defines the env variables for the build environment:
envVariables:
GO_ENV: production
@@ -9361,12 +13659,20 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/go/how-to/env-variables) in Zerops.
+
## Runtime configuration
+
### base
+
_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Go version for your runtime.
+
Following options are available for Go builds:
+
+- `go@1.22`, `go@1`, `golang@1`, `go@latest`, `golang@latest`
+
```yaml
zerops:
# hostname of your service
@@ -9376,18 +13682,25 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: go@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: go@latest
...
```
+
+
The base runtime environment contains {data.alpine.default}, the
selected major version of Go, Zerops command line tool, `git` and `wget`.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -9397,6 +13710,7 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: go@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
@@ -9406,42 +13720,73 @@ zerops:
- zsc add nodejs@latest
...
```
+
See the full list of supported [run base environments](/zerops-yaml/base-list).
+
To customise your build environment use the `prepareCommands` attribute.
+
### os
+
_OPTIONAL._ Sets the operating system for the runtime environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customised.
:::
+
### ports
+
_OPTIONAL._ Specifies one or more internal ports on which your application will listen.
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
For example, to connect to a Go service with hostname = "app" and port = 8080 from another service of the same project, simply use `app:8080`. Read more about [how to access a Go service](/references/networking/internal-access#basic-service-communication).
+
Each port has following attributes:
-
- Parameter
- Description
-
- port
- Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
-
- protocol
- Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
-
- httpSupport
- Optional. httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of public access. httpSupport = true is available only in combination with the TCP protocol.
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
+
+
+
protocol
+
Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
+
+
+
httpSupport
+
Optional.httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). httpSupport = true is available only in combination with the TCP protocol.
+
+
+
+
### prepareCommands
+
_OPTIONAL._ Customises the Go runtime environment by installing additional dependencies or tools to the runtime base environment.
+
+
The base Go environment contains {data.alpine.default}, the selected
- major version of Go, Zerops command line tool and `git` and `wget`. To install additional packages or tools add one or more prepare commands:
+ major version of Go, [Zerops command line tool](/references/cli) and `git` and `wget`. To install additional packages or tools add one or more prepare commands:
+
+
```yaml
zerops:
# hostname of your service
@@ -9449,6 +13794,7 @@ zerops:
# ==== how to build your application ====
build:
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -9458,27 +13804,45 @@ zerops:
- curl something else
...
```
+
When the first deploy with a defined prepare attribute is triggered, Zerops will
+
1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order
+
:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/go/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.
+
#### Cache of your custom runtime environment
+
Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:
+
1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.
+
To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.
+
When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### Copy folders or files from your build container
+
+
The prepare runtime container contains {data.alpine.default}, the
- selected major version of Go, Zerops command line tool and `git` and `wget`.
+ selected major version of Go, [Zerops command line tool](/references/cli) and `git` and `wget`.
+
+
The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).
+
```yaml
zerops:
# hostname of your service
@@ -9487,6 +13851,7 @@ zerops:
build:
...
addToRunPrepare: ./runtime-config.yaml
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -9496,15 +13861,20 @@ zerops:
- curl something else
...
```
+
In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.
+
### initCommands
+
_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Run one or more commands each time a new runtime container
@@ -9513,22 +13883,35 @@ zerops:
initCommands:
- rm -rf ./cache
```
+
These commands are triggered in the runtime container before your Go application is started via the [start command](#start).
+
:::note
`run.initCommands` run in the `/var/www` directory.
:::
+
Use init commands to clean or initialise your application cache or similar operations.
+
:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/go/how-to/scaling) or when a runtime container is restarted).
+
Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::
+
#### Command exit code
+
If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/go/how-to/logs#runtime-log) to troubleshoot the error.
+
#### Single or separated shell instances
+
You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the runtime environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -9543,57 +13926,84 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/go/how-to/env-variables) in Zerops.
+
### start
+
_REQUIRED._ Defines the start command for your Go application.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Go application start command
start: ./app
```
+
We recommend starting your Go application using `./app`.
+
### health check
+
_OPTIONAL._ Defines a health check.
+
`healthCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the health check to request a local URL using a HTTP GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Go application start command
start: ./app
+
# OPTIONAL. Define a health check with a HTTP GET request option.
# Configures the check on http://127.0.0.1:80/status
healthCheck:
@@ -9601,30 +14011,47 @@ zerops:
port: 80
path: /status
```
+
#### exec
+
Configures the health check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
Defines a local command to be run.
- The command has access to the same environment variables as your Go application.
+
+ The command has access to the same [environment variables](/go/how-to/create#set-secret-environment-variables) as your Go application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Go application start command
start: ./app
+
# OPTIONAL. Define a health check with a shell command.
healthCheck:
exec:
@@ -9633,13 +14060,18 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
### crontab
+
_OPTIONAL._ Defines cron jobs.
+
Setup cron jobs in the following format:
+
```yaml
zerops:
# define hostname of your service
- setup: app
+
# ==== how to run your application ====
run:
crontab:
@@ -9648,72 +14080,112 @@ zerops:
# REQUIRED. Sets the interval time to execute:
timing: "0 * * * *"
```
+
Read more about setting up [cron](/zerops-yaml/cron) in Zerops.
+
## Deploy configuration
+
### readiness check
+
_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/go/how-to/deploy-process#readiness-checks) in Zerops.
+
`readinessCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the readiness check to request a local URL using a http GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
-**Example:**
-```yaml
-zerops:
- # hostname of your service
- - setup: app
- # ==== how to build your application ====
- build: ...
- # ==== how to deploy your application ====
- deploy:
- # OPTIONAL. Define a readiness check with a HTTP GET request option.
- # Configures the check on http://127.0.0.1:80/status
- readinessCheck:
- httpGet:
- port: 80
- path: /status
- # ==== how to run your application ====
- run: ...
-```
-Read more about how the [readiness check works](/go/how-to/deploy-process#readiness-checks) in Zerops.
-#### exec
-Configures the readiness check to run a local command.
-Following attributes are available:
-
- Parameter
- Description
-
- command
-
- Defines a local command to be run.
- The command has access to the same environment variables as your Go application.
- A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
-**Example:**
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
+**Example:**
+
+```yaml
+zerops:
+ # hostname of your service
+ - setup: app
+ # ==== how to build your application ====
+ build: ...
+
+ # ==== how to deploy your application ====
+ deploy:
+ # OPTIONAL. Define a readiness check with a HTTP GET request option.
+ # Configures the check on http://127.0.0.1:80/status
+ readinessCheck:
+ httpGet:
+ port: 80
+ path: /status
+
+ # ==== how to run your application ====
+ run: ...
+```
+
+Read more about how the [readiness check works](/go/how-to/deploy-process#readiness-checks) in Zerops.
+
+#### exec
+
+Configures the readiness check to run a local command.
+Following attributes are available:
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
+ Defines a local command to be run.
+
+ The command has access to the same [environment variables](/go/how-to/create#set-secret-environment-variables) as your Go application.
+
+ A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
+
+
+
+
+
+**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -9725,8 +14197,10 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
Read more about how the [readiness check works](/go/how-to/deploy-process#readiness-checks) in Zerops.
+
----------------------------------------
# Go > How To > Build Process
@@ -9743,35 +14217,60 @@ Read more about how the [readiness check works](/go/how-to/deploy-process#readin
# Go > How To > Create
+
Zerops provides a Go runtime service with extensive build support. Go runtime is highly scalable and customisable to suit both development and production.
+
## Create Go service using Zerops GUI
+
First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Go service:
+
+[Video: /vids/services/golang.webm](/vids/services/golang.webm)
+
### Choose Go version
+
Following Go versions are currently supported:
+
:::info
You can [change](/go/how-to/upgrade) the major version at any time later.
:::
+
### Set a hostname
+
Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.
+
#### Limitations:
+
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::
+
### Set secret environment variables
+
Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.
+
Setting the secret environment variables is optional. You can set them later in Zerops GUI.
+
Read more about [different types of env variables](/go/how-to/env-variables#service-env-variables) in Zerops.
+
## Create Go service using zCLI
+
zCLI is the Zerops command-line tool. To create a new Go service via the command-line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/go/how-to/create#create-a-project-description-file)
3. [Create a project with a Go and PostgreSQL service](#full-example)
+
### Create a project description file
+
Zerops uses a yaml format to describe the project infrastructure.
+
#### Basic example:
+
Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -9792,13 +14291,18 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes your future project infrastructure. The project will contain one Go version 1 service with default [auto scaling](/go/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/go/how-to/build-pipeline#ports). Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
#### Full example:
+
Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:
+
```yaml
# basic project data
project:
@@ -9843,98 +14347,143 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain a Go service and a [PostgreSQL](/postgresql/overview) service.
+
Go service with "app" hostname, the internal port(s) the service listens on will be defined later in the zerops.yaml. Go service will run on version 1 with a custom vertical and horizontal scaling. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
hostname
+
The unique service identifier.
-
+
The hostname of the new database will be set to the `hostname` value.
-
- Limitations:
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+ Limitations:
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
type
+
Specifies the service type and version.
-
+
See what [Go service types](/references/import-yaml/type-list#runtime-services) are currently supported.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto scaling parameters.
-
+
+
+
+
verticalAutoscaling
+
+ Optional. Defines [custom vertical auto scaling parameters](/go/how-to/create#set-auto-scaling-configuration).
+
All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
- minContainers
-
- Optional. Default = 1. Defines the minimum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
- cpuMode
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
- minCpu/maxCpu
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
- minRam/maxRam
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
- minDisk/maxDisk
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
minContainers
+
+ Optional. Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/go/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- maxContainers
-
- Defines the maximum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
maxContainers
+
+ Defines the maximum number of containers for [horizontal autoscaling](/go/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- envSecrets
-
- Optional. Defines one or more secret env variables as a key value map. See env variable restrictions.
-
+
+
+
+
envSecrets
+
+ Optional. Defines one or more secret env variables as a key value map. See env variable [restrictions](/go/how-to/env-variables#env-variable-restrictions).
+
+
+
+
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add Go service to an existing project
+
#### Example:
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -9955,33 +14504,38 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Go service version 1 with default [auto scaling](/go/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the import.yaml file is 100 kB.
+
----------------------------------------
# Go > How To > Customize Runtime
-System packages for processing: When your app processes images, videos, or files (requiring packages like sudo apk add imagemagick)',
- 'CGO dependencies: When you use CGO and need C libraries not included in the default environment',
- 'Development tools: When you need debugging tools, profilers, or other development utilities',
- 'Different base OS: When you need Ubuntu instead of Alpine for specific compatibility requirements'
-]} />
+
----------------------------------------
@@ -10035,13 +14589,21 @@ System packages for processing: When your app processes images, videos, or files
# Go > Overview
+
[Go ↗](https://go.dev/) is a statically typed, compiled high-level programming language designed at Google.
+
As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-go-hello-world), a **_recipe_**, containing the most simple Go web application. The repo will be used as a source from which the app will be built.
- This is the most bare-bones example of Go running in Zerops — as few libraries as possible,
+
+### 🚀 Feel free to deploy the recipe yourself
+
+This is the most bare-bones example of Go running in Zerops — as few libraries as possible,
just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.
-
+
+ [Deploy "golang" recipe on Zerops](https://app.zerops.io/recipe/?lf=golang)
+
1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-go-hello-world/blob/main/import-project/description.yaml)):
+
```yaml
project:
name: my-first-project
@@ -10053,43 +14615,78 @@ services:
buildFromGit: https://github.com/zeropsio/recipe-go-hello-world@main
enableSubdomainAccess: true
```
+
3. Click on **Import project** and wait until all pipelines have finished.
+
**That's it, your application is now up and running! :star: Let's check it works:**
+
1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://helloworld-24-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see
+
```
Hello, World!
```
+
:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::
+
## How to start
+
+- [Care for details?](/go/how-to/create) — Dive in all Zerops has to offer for your Go application.
+
## Feature Highlights
+
+- [Create Go service](/go/how-to/create) — Start with creating a Go service using GUI or zCLI.
+- [zerops.yaml](/go/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
+- [Scaling configuration](/go/how-to/scaling) — Set up scaling of your Go application so that it runs smoothly while using only necessary resources.
+
{" "}
+
+- [Customize build environment](/go/how-to/build-process#customize-build-environment)
+- [Customize runtime environment](/go/how-to/customize-runtime)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+
+- [FAQ](/go/faq) — Most common questions in one place.
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Guides > Backup
+
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
MariaDB, PostgreSQL, Qdrant, Elasticsearch, NATS, Meilisearch, Shared Storage.
+
**Not supported**: Runtimes, Object Storage (use S3 lifecycle policies), Valkey/KeyDB (in-memory).
+
## Schedule Options
- No backups
- Once a day (default: 00:00-01:00 UTC)
- Once a week
- Once a month
- Custom CRON: `minute hour day month weekday`
+
## Tagging
- Auto tags: `daily` (every backup), `weekly` (first Monday UTC), `monthly` (1st of month UTC)
- User tags: Up to 24 chars (letters, numbers, `:-_`)
- **Protected tags**: Exempt from automatic deletion — use for critical snapshots
+
## Storage Limits
| Plan | Backup Storage | Egress |
|------|---------------|--------|
@@ -10097,13 +14694,17 @@ MariaDB, PostgreSQL, Qdrant, Elasticsearch, NATS, Meilisearch, Shared Storage.
| Serious | 25 GB | 3 TB |
| Technical max | 1 TiB per project (shared across all services) |
| Technical max | 1 TiB per project (shared across all services) |
+
## Retention Defaults
- Minimum kept: 7 daily + 4 weekly + 3 monthly
- Maximum per service: 50 backups
+
## Encryption
End-to-end with X25519 per-project keys. Decrypted only on download.
+
## Grace Period
7 days after service or project deletion before backups are permanently removed.
+
## Backup Formats by Service
| Service | Format |
|---------|--------|
@@ -10115,56 +14716,84 @@ End-to-end with X25519 per-project keys. Decrypted only on download.
| NATS | .tar.gz |
| Shared Storage | filesystem archive |
| Shared Storage | filesystem archive |
+
## Gotchas
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
+
----------------------------------------
# Guides > Build Cache
+
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).
+
---
+
## Two-Layer Architecture
+
| Layer | Contains | Cached when |
|-------|----------|-------------|
| **Base layer** | OS, installed packages, prepareCommands output | prepareCommands unchanged |
| **Build layer** | Files from `cache:` attribute after buildCommands | cache config unchanged |
| **Build layer** | Files from `cache:` attribute after buildCommands | cache config unchanged |
+
Both layers are currently **coupled** -- invalidating the base layer also invalidates the build layer (cascade invalidation).
+
## Cache Lifecycle
+
1. **Restoration**: cached files moved from `/build/cache` to `/build/source` (no-clobber -- source files win)
2. **Build execution**: buildCommands run with cached + source files
3. **Preservation**: specified cache files moved from `/build/source` to `/build/cache`
+
No compression or network transfer -- fast directory rename operations within the container.
+
---
+
## Configuration
+
### Path-Specific Caching (Recommended)
+
```yaml
build:
cache: node_modules # single path
cache: [node_modules, .next] # multiple paths
```
+
All paths resolve relative to `/build/source`. Supports Go `filepath.Match` patterns (e.g., `"subdir/*.txt"`, `"package*"`). Forms `./node_modules`, `node_modules`, `node_modules/` are equivalent.
+
### System-Wide Caching
+
- **`cache: true`** -- preserves entire build container state. Best for global package managers (Go modules, pip)
- **`cache: false`** -- only prevents caching within `/build/source`. Files outside (e.g., `$GOPATH`) **remain cached**
+
---
+
## Cache Invalidation
+
### Automatic Triggers
+
Any change to these zerops.yml fields invalidates **both layers**:
+
- `build.os`
- `build.base`
- `build.prepareCommands`
- `build.cache`
+
**DO NOT** add trivial changes to `prepareCommands` (e.g., adding `vim`) without understanding this will also invalidate cached `node_modules`, `vendor/`, etc.
+
### Manual Triggers
+
- **GUI**: Service detail -> Pipelines & CI/CD Settings -> Invalidate build cache
- **API**: `DELETE /service-stack/{id}/build-cache`
- **Version restore**: Activating a backup app version also invalidates cache
+
---
+
## Per-Runtime Cache Recommendations
+
| Runtime | Recommended `cache:` paths |
|---------|---------------------------|
| Node.js / Bun | `node_modules`, `.next`, `.turbo`, `package-lock.json` |
@@ -10175,21 +14804,30 @@ Any change to these zerops.yml fields invalidates **both layers**:
| Java | `cache: true` (.m2 lives outside /build/source) |
| .NET | `cache: true` (NuGet outside /build/source) |
| .NET | `cache: true` (NuGet outside /build/source) |
+
---
+
## Build Container Specs
+
CPU 1-5 cores, RAM 8 GB fixed, Disk 1-100 GB, Timeout 60 min. User `zerops` with **sudo**. Default OS: **Alpine** (use `apt-get` with `os: ubuntu`).
+
---
+
## Common Pitfalls
+
1. **Cascade invalidation**: Changing `prepareCommands` wipes build-layer cache too (e.g., adding `sqlite` to prepare also clears cached `node_modules`)
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
+
----------------------------------------
# Guides > Cdn
+
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
1. **EU (Prague, CZ)** — Primary + all-region failover
2. **EU (Falkenstein, DE)** — Secondary European
@@ -10197,25 +14835,32 @@ Zerops CDN has 6 global regions with a **fixed 30-day cache TTL** (HTTP Cache-Co
4. **AU (Sydney)**
5. **SG (Singapore)**
6. **CA (Beauharnois, Canada)**
+
DNS TTL: 30 seconds. Geo-steering routes to nearest node. EU Prague is fallback if all others down.
+
## CDN Modes
+
### Object Storage CDN
- URL: `https://storage.cdn.zerops.app/bucket/path`
- Env var: `${storageCdnUrl}`
- Direct from Object Storage through CDN
+
### Static CDN
- URL: `https://static.cdn.zerops.app/domain.com/path`
- Env var: `${staticCdnUrl}`
- For custom domains on static/nginx services
- **Wildcard domains NOT supported**
+
### API CDN
- Coming soon
- Env var: `${apiCdnUrl}`
+
## Cache Behavior
- TTL: **Fixed 30 days** (not configurable)
- HTTP `Cache-Control` headers: Affect browser caching, **NOT CDN caching**
- Eviction: LRU when storage capacity reached
- First request: Fetched from origin and cached
+
## Purge Patterns
```
/* # All content
@@ -10224,100 +14869,138 @@ DNS TTL: 30 seconds. Geo-steering routes to nearest node. EU Prague is fallback
/prefix* # Pattern prefix match
```
Wildcard must be at end. Use `$` suffix for exact file match.
+
### Purge via zsc
```bash
zsc cdn purge /* # Purge all cached content
zsc cdn purge /images/* # Purge directory
zsc cdn purge /style.css$ # Purge exact file
```
+
## Gotchas
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/*`
+
----------------------------------------
# Guides > Choose Cache
+
**Use Valkey.** KeyDB development has stalled and is effectively deprecated on Zerops.
+
## Decision Matrix
+
| Need | Choice | Why |
|------|--------|-----|
| **Any caching need** | **Valkey** (default) | Active development, full HA, Redis-compatible |
| Legacy KeyDB apps | KeyDB | Only if migrating existing KeyDB deployment |
| Legacy KeyDB apps | KeyDB | Only if migrating existing KeyDB deployment |
+
## Valkey (Default Choice)
+
- Redis-compatible drop-in replacement
- HA: 3 nodes (1 master + 2 replicas) with automatic failover
- Ports: 6379 (non-TLS), 6380 (TLS), 7000 (read replica non-TLS), 7001 (read replica TLS)
- Connection: `redis://${user}:${password}@${hostname}:6379`
- HA detail: Ports 6379/6380 on replicas forward traffic to current master (Zerops-specific, not native Valkey)
+
## KeyDB (Deprecated)
+
- Development activity has slowed significantly
- Port: 6379
- **Do not use for new projects**
+
## Gotchas
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
+
----------------------------------------
# Guides > Choose Database
+
**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
+
| Need | Choice | Why |
|------|--------|-----|
| **General-purpose** | **PostgreSQL** (default) | Full HA, read replicas, pgBouncer, best Zerops support |
| MySQL compatibility | MariaDB | MaxScale routing, async replication |
| Analytics / OLAP | ClickHouse | Columnar storage, ReplicatedMergeTree, 4 protocol ports |
| Analytics / OLAP | ClickHouse | Columnar storage, ReplicatedMergeTree, 4 protocol ports |
+
## PostgreSQL (Default Choice)
+
- HA: 3 nodes (1 primary + 2 replicas)
- Ports: 5432 (primary), 5433 (read replicas), 6432 (external TLS via pgBouncer)
- Connection: `postgresql://${user}:${password}@${hostname}:5432/${db}`
- Read scaling: Use port 5433 for read-heavy workloads
+
## MariaDB
+
- HA: MaxScale routing with async replication
- Port: 3306
- Connection: `mysql://${user}:${password}@${hostname}:3306/${db}`
- Use when: Application requires MySQL wire protocol
+
## ClickHouse
+
- HA: 3 data nodes, replication factor 3
- Ports: 9000 (native), 8123 (HTTP), 9004 (MySQL), 9005 (PostgreSQL)
- Requires `ReplicatedMergeTree` engine in HA mode
- Use when: Analytics, time-series, OLAP workloads
+
## Gotchas
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
+
----------------------------------------
# Guides > Choose Queue
-**Use NATS** for most cases (simple, fast, JetStream persistence). Use **Kafka** only for enterprise event streaming with guaranteed ordering and unlimited retention.
+
+**Use NATS** for most cases (simple, fast, optional JetStream persistence layer when durability is needed). Use **Kafka** only for enterprise event streaming with guaranteed ordering and unlimited retention.
+
## Decision Matrix
+
| Need | Choice | Why |
|------|--------|-----|
-| **General messaging** | **NATS** (default) | Simple auth, JetStream built-in, fast |
+| **General messaging** | **NATS** (default) | Simple auth, fast, JetStream available when needed |
| Enterprise event streaming | Kafka | SASL auth, 3-broker HA, unlimited retention |
-| Lightweight pub/sub | NATS | Low overhead, 8MB default messages |
+| Lightweight pub/sub | NATS — core | Low overhead, 8MB default messages, fire-and-forget |
+| Durable queues, replay, at-least-once | NATS — JetStream | Persistent streams, durable consumers, ack/redeliver |
| Event sourcing / audit logs | Kafka | Indefinite topic retention, strong ordering |
| Event sourcing / audit logs | Kafka | Indefinite topic retention, strong ordering |
+
## NATS (Default Choice)
+
+NATS exposes **two distinct messaging shapes**. Pick ONE per recipe and write yaml comments / KB content describing only that shape — mixing them confuses porters about what the recipe actually does.
+
+- **Core pub/sub + queue groups**: `nc.subscribe('subject', { queue: 'workers' })`. No persistence; queue groups load-balance delivery across replicas; lost messages stay lost. HA story: surviving cluster nodes keep delivering, no consumer position to restore. Use when fan-out + load balance + at-most-once is enough.
+- **JetStream streams + durable consumers**: opens an explicit stream via `JetStreamManager`, subscribes durably via `js.subscribe(...)`. Persistent message store; replay on reconnect; ack/redeliver. HA story: cluster replicates stream state, acked-but-unprocessed messages survive node loss. Use when at-least-once + replay + persistence are required.
+
+**Authoring rule**: a recipe's yaml comments and KB bullets should reflect the shape the code actually uses. If the worker only calls `nc.subscribe()` with a queue group and never opens a stream, do not invoke JetStream language at HA tiers — the recipe has no stream to replicate. If the worker opens a JetStream stream, the JetStream HA story is the relevant one.
+
- Ports: 4222 (client), 8222 (HTTP monitoring)
- Auth: user `zerops` + auto-generated password
- **Connection** — two supported patterns, pick ONE:
- **Separate env vars** (recommended, works with every NATS client library): pass `servers: ${hostname}:${port}` plus `user: ${user}, pass: ${password}` as client-side connect options. The servers list stays credential-free.
- **Opaque connection string**: pass `${connectionString}` directly as the servers option — the platform builds a correctly-formatted URL with embedded auth that the NATS server expects.
-- JetStream: Enabled by default (`JET_STREAM_ENABLED=1`)
+- JetStream capability: enabled by default (`JET_STREAM_ENABLED=1`); recipes opt in by writing JetStream client code. Setting `JET_STREAM_ENABLED=0` hard-disables the capability across the project.
- Storage: Up to 40GB memory + 250GB file store
- Max message: 8MB default, 64MB max (`MAX_PAYLOAD`)
- Health check: `GET /healthz` on port 8222
- **Config changes require restart** (no hot-reload)
+
## Kafka
+
- Port: 9092 (SASL PLAIN auth)
- Auth: `user` + `password` env vars (auto-generated)
- Bootstrap: `${hostname}:9092`
@@ -10325,19 +15008,24 @@ zsc cdn purge /style.css$ # Purge exact file
- Storage: Up to 40GB RAM + 250GB persistent
- Topic retention: **Indefinite** (no time or size limits)
- Schema Registry: Port 8081 (if enabled)
+
## Gotchas
1. **NATS config changes need restart**: No hot-reload — changing env vars requires service restart
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
+3. **NATS JetStream HA sync interval**: 1-minute sync across nodes — brief data lag possible. Applies only to recipes that actually open JetStream streams; core pub/sub recipes are unaffected.
4. **Kafka SASL only**: No anonymous connections — always use the generated credentials
5. **NATS authorization violation from a hand-composed URL**: do not build a `nats://user:pass@host:4222` URL from the separate env vars. Most NATS client libraries will parse the embedded credentials AND separately attempt SASL with the same values, producing a double-auth that the server rejects with `Authorization Violation` on the first CONNECT frame (symptom: startup crash, no successful subscription). Use either the separate env vars passed as connect options (credential-free servers list) or the opaque `${connectionString}` the platform builds for you — both patterns in the Connection section above avoid the double-auth path.
+
----------------------------------------
# Guides > Choose Runtime Base
+
**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
+
| Need | Choice | Why |
|------|--------|-----|
| **Any standard app** | **Alpine** (default) | ~5MB, fast, secure, sufficient for 95% of apps |
@@ -10345,36 +15033,47 @@ zsc cdn purge /style.css$ # Purge exact file
| Pre-built Docker images | Docker | VM-based, bring your own image |
| CGO / native libs | Ubuntu | Better glibc compatibility than Alpine's musl |
| CGO / native libs | Ubuntu | Better glibc compatibility than Alpine's musl |
+
## Alpine (Default)
+
- Size: ~5MB base
- Package manager: `apk add`
- Best for: All runtimes (Node.js, Python, Go, Rust, Java, PHP, etc.)
- Zerops uses Alpine as default base for all managed runtimes
+
## Ubuntu
+
- Size: ~100MB base
- Package manager: `apt-get install`
- Version: 24.04 LTS
- Use when: You need packages not available in Alpine, or need glibc (not musl)
- Example: Go apps with CGO, Python packages with C extensions that don't compile on musl
+
## Docker
+
- **Runs in a VM** (not a container) — slower boot, higher overhead
- Network: **Must use `--network=host`** or `network_mode: host` in compose
- Scaling: Fixed resources only (no min-max auto-scaling), VM restarts on resource change
- Disk: Can only increase, never decrease without recreation
- Build phase runs in containers (not VMs)
- **Always use specific version tags** — `:latest` is cached and won't re-pull
+
## Gotchas
1. **Alpine uses musl**: Some C libraries may not compile — use Ubuntu if you hit musl issues
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
+
----------------------------------------
# Guides > Choose Search
+
**Use Meilisearch** for simple full-text search. Use **Elasticsearch** for advanced queries or HA requirements. Use **Qdrant** for vector/AI search.
+
## Decision Matrix
+
| Need | Choice | Why |
|------|--------|-----|
| **Simple full-text search** | **Meilisearch** (default) | Instant setup, typo-tolerant, frontend-safe keys |
@@ -10382,46 +15081,60 @@ zsc cdn purge /style.css$ # Purge exact file
| Autocomplete + typo-tolerance | Typesense | Raft HA, CORS built-in, fast |
| Vector / AI similarity | Qdrant | gRPC + HTTP, automatic cluster replication |
| Vector / AI similarity | Qdrant | gRPC + HTTP, automatic cluster replication |
+
## Meilisearch (Default for Simple Search)
+
- Single-node only (no clustering)
- Port: 7700
- API keys: `masterKey` (admin), `defaultSearchKey` (frontend-safe), `defaultAdminKey` (backend)
- Production mode by default (no search preview dashboard)
+
## Elasticsearch (Advanced / HA)
+
- Cluster support with multiple nodes
- Port: 9200 (HTTP only)
- Auth: `elastic` user with auto-generated password
- Plugins via `PLUGINS` env var (comma-separated)
- JVM heap: `HEAP_PERCENT` env var (default 50%)
- Min RAM: 0.25 GB
+
## Typesense (Fast Autocomplete)
+
- HA: 3-node Raft consensus
- API key via `apiKey` env var (immutable after generation)
- CORS enabled by default
- Recovery time: up to 1 minute during failover (503/500 auto-resolves)
- Data persisted at `/var/lib/typesense`
+
## Qdrant (Vector Search)
+
- Ports: 6333 (HTTP), 6334 (gRPC)
- API keys: `apiKey` (full access), `readOnlyApiKey` (search only)
- HA: 3 nodes with `automaticClusterReplication=true` by default
- **Internal access only** — no public access available
+
## Gotchas
1. **Meilisearch has no HA**: Single-node only — for HA full-text search, use Elasticsearch or Typesense
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
+
----------------------------------------
# Guides > Ci Cd
+
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)
+
### Setup (GUI)
1. Service detail → Build, Deploy, Run Pipeline Settings
2. Connect with GitHub repository
3. Select repo + authorize (requires **full access** for webhooks)
4. Choose trigger: **New tag** (optional regex filter) or **Push to branch**
+
### GitHub Actions
```yaml
name: Deploy
@@ -10434,25 +15147,33 @@ jobs:
- uses: zeropsio/actions@main
with:
access-token: ${{ secrets.ZEROPS_TOKEN }}
- service-id:
+ service-id:
```
+
- `access-token`: From Settings → Access Token Management
- `service-id`: From service URL or three-dot menu → Copy Service ID
+
## GitLab Integration (Webhook)
+
### Setup (GUI)
1. Service detail → Build, Deploy, Run Pipeline Settings
2. Connect with GitLab repository
3. Authorize (requires **full access** for webhooks)
4. Choose trigger: **New tag** (optional regex) or **Push to branch**
+
## Skip Pipeline
Include `ci skip` or `skip ci` in commit message (case-insensitive).
+
## Disconnect
Service detail → Build, Deploy, Run → Stop automatic build trigger.
+
## Gotchas
1. **Full repo access required**: Webhook integration needs full access to create/manage webhooks
2. **`ci skip` in commit message**: Prevents pipeline trigger — useful for docs-only changes
3. **Service ID not obvious**: Find it in service URL or three-dot menu → Copy Service ID
+
## GitLab CI
+
```yaml
deploy:
stage: deploy
@@ -10465,11 +15186,14 @@ deploy:
only:
- main
```
+
## Generic CI (Any System)
+
Any CI system with shell access can deploy via `zcli push`:
1. Install zcli: `curl -L https://zerops.io/zcli/install.sh | sh`
-2. Authenticate: `zcli login `
-3. Deploy: `zcli push --project-id --service-id `
+2. Authenticate: `zcli login `
+3. Deploy: `zcli push --project-id --service-id `
+
### zcli push key flags
| Flag | Description |
|------|-------------|
@@ -10482,16 +15206,21 @@ Any CI system with shell access can deploy via `zcli push`:
| `--deploy-git-folder` | Include `.git/` directory in deploy |
| `--deploy-git-folder` | Include `.git/` directory in deploy |
+
----------------------------------------
# Guides > Cloudflare
+
Always use **Full (strict)** SSL mode in Cloudflare — "Flexible" causes redirect loops. Shared IPv4 with Cloudflare proxy is not recommended.
+
## DNS Configuration
+
### CNAME (non-apex or with CNAME flattening)
```
-CNAME
+CNAME
```
+
### With Cloudflare Proxy (orange cloud)
| IP Type | Record | Proxy |
|---------|--------|-------|
@@ -10499,6 +15228,7 @@ CNAME
| Dedicated IPv4 | `A ` | Proxied |
| Shared IPv4 | **Not recommended** | Reverse AAAA lookup issues |
| Shared IPv4 | **Not recommended** | Reverse AAAA lookup issues |
+
### DNS-Only (gray cloud)
| IP Type | Records Required |
|---------|-----------------|
@@ -10506,19 +15236,24 @@ CNAME
| Dedicated IPv4 | `A` (AAAA optional) |
| IPv6 only | `AAAA` |
| IPv6 only | `AAAA` |
+
## Wildcard Domains
```
-Method A: A *. + AAAA *.
-Method B: CNAME *.
-ACME: CNAME _acme-challenge. .zerops.zone
+Method A: A *. + AAAA *.
+Method B: CNAME *.
+ACME: CNAME _acme-challenge..zerops.zone
```
+
## SSL/TLS Settings (Cloudflare Dashboard)
- **Encryption mode: Full (strict)** — mandatory
- **Never use "Flexible"** — causes infinite redirect loops
- Enable "Always Use HTTPS"
- WAF exception: Skip rule for `/.well-known/acme-challenge/` (ACME validation)
+
## Preparing a Service for Cloudflare
+
Any runtime service (nodejs, go, python, etc.) can be put behind Cloudflare. Steps:
+
1. **Create the service** with `enableSubdomainAccess: true` in import YAML:
```yaml
services:
@@ -10530,8 +15265,11 @@ Any runtime service (nodejs, go, python, etc.) can be put behind Cloudflare. Ste
2. **Deploy code** to the service (via `zcli push` or `buildFromGit`)
3. **Configure Cloudflare DNS** to point to your Zerops project IP
4. **Set SSL mode to "Full (strict)"** in Cloudflare dashboard
+
**Important**: The `zerops_subdomain enable` tool only works on deployed (ACTIVE) services. For new services, use `enableSubdomainAccess: true` in import YAML.
+
Internal service-to-service communication must always use `http://` — never `https://`. SSL terminates at the Zerops L7 balancer.
+
## Gotchas
1. **Flexible SSL = redirect loop**: Zerops forces HTTPS, Cloudflare Flexible sends HTTP → infinite redirect
2. **Shared IPv4 + proxy is broken**: Reverse AAAA lookup doesn't work with Cloudflare proxy on shared IPv4
@@ -10539,16 +15277,24 @@ Internal service-to-service communication must always use `http://` — never `h
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
+
----------------------------------------
# Guides > Deployment Lifecycle
+
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`.
+
---
+
## Build Phase
+
### Build Container Lifecycle
+
The build container is **temporary** -- created on demand, destroyed after completion or failure.
+
**Step-by-step execution order:**
+
1. **Container creation** -- base environment from `build.base` + `build.os` (default Alpine)
2. **Source code download** -- from GitHub, GitLab, or zcli push to `/var/www`
3. **Cache restoration** -- cached files moved to `/build/source` (no-clobber, source wins)
@@ -10557,56 +15303,81 @@ The build container is **temporary** -- created on demand, destroyed after compl
6. **Artifact upload** -- files matching `deployFiles` stored in internal Zerops storage
7. **Cache preservation** -- files matching `cache:` moved to `/build/cache`
8. **Container deletion** -- build container destroyed regardless of outcome
+
### Build Limits
+
- **Resources**: CPU 1-5 cores, RAM 8 GB fixed, Disk 1-100 GB (auto-scales, not charged separately)
- **Timeout**: **60 minutes** hard limit -- no retry, must trigger new pipeline
- **Cancellation**: only available before build finishes -- once artifact uploaded, deploy cannot be cancelled
+
### Command Exit Codes
+
- **Exit 0** -- success, next command runs
- **Non-zero** -- build cancelled, check build log for errors
- YAML list items = **separate shells**; use `|` block scalar for **single shell** (shared env/cwd)
+
---
+
## Runtime Prepare Phase (Optional)
+
Runs **after build, before deploy** when `run.prepareCommands` is defined. Creates a **custom runtime image** with additional system packages.
+
**Execution order:**
1. Create prepare container from `run.os` + `run.base`
2. Copy files from `build.addToRunPrepare` to `/home/zerops/`
3. Execute `run.prepareCommands` in order
4. Snapshot as custom runtime image
5. Image cached for future deploys
+
**Cache invalidation triggers:**
- Change to `run.os`, `run.base`, or `run.prepareCommands`
- Change to `build.addToRunPrepare` file contents
- Manual invalidation via GUI
+
**DO NOT** include application code in the runtime prepare image. Deploy files arrive separately.
+
---
+
## Deploy Phase
+
### First Deploy
+
For each new container (count based on auto scaling settings):
+
1. **Install runtime** -- base image or custom runtime image
2. **Download artifact** -- from internal storage to `/var/www`
3. **initCommands** -- optional per-container initialization (runs every start/restart)
4. **start command** -- launch application
5. **Readiness check** -- if configured, gates traffic routing
6. **Container active** -- receives incoming requests
+
Multiple containers deploy **in parallel**.
+
### Subsequent Deploys (Rolling Deployment)
+
Default behavior (`temporaryShutdown: false`):
+
1. New containers started (same count as existing)
2. New containers go through steps 1-6 above
3. **Both old and new versions run simultaneously** during transition
4. Old containers removed from load balancer (stop receiving new requests)
5. Old container processes terminated
6. Old containers deleted
+
### temporaryShutdown Behavior
+
| Setting | Behavior | Downtime |
|---------|----------|----------|
| `false` (default) | New containers start BEFORE old ones stop | **Zero downtime** |
| `true` | Old containers stop BEFORE new ones start | **Temporary downtime** |
| `true` | Old containers stop BEFORE new ones start | **Temporary downtime** |
+
Use `temporaryShutdown: true` only when you cannot run two versions simultaneously (e.g., database migrations, singleton locks).
+
---
+
## Readiness Check vs Health Check
+
| Aspect | Readiness Check | Health Check |
|--------|----------------|--------------|
| When | **During deploy only** | **Continuously after deploy** |
@@ -10614,59 +15385,85 @@ Use `temporaryShutdown: true` only when you cannot run two versions simultaneous
| Location | `deploy.readinessCheck` | `run.healthCheck` |
| Failure action | Container marked failed after timeout, replaced | Container restarted |
| Failure action | Container marked failed after timeout, replaced | Container restarted |
+
### Readiness Check Mechanics
+
1. Application starts via `start` command
2. Readiness check runs (httpGet or exec)
3. If **fails** -- wait `retryPeriod` seconds (default 5s), retry
4. If **succeeds** -- container marked active, receives traffic
5. If still failing after `failureTimeout` (default 300s / 5 min) -- container deleted, new one created
+
**httpGet**: succeeds on HTTP `2xx`, follows `3xx` redirects, 5-second per-request timeout
**exec.command**: succeeds on exit code 0, 5-second per-command timeout
+
---
+
## Event Timeline (zerops_events)
+
Typical pipeline events in chronological order:
+
1. **`stack.build` process RUNNING** -- build container created, pipeline started
2. **`stack.build` process FINISHED** -- build complete, artifact uploaded
3. **`appVersion` build event ACTIVE** -- deploy started, containers launching
4. **Service status returns to RUNNING** -- all containers active, deploy complete
+
**Terminal states:**
- Build done: `stack.build` process status = `FINISHED`
- Build failed: `stack.build` process status = `FAILED`
- Deploy done: service containers all active, new appVersion is `ACTIVE`
+
**DO NOT** keep polling after `stack.build` shows `FINISHED` -- that means the build itself is complete. The `ACTIVE` status on appVersion means deployed and running.
+
---
+
## Build Event Polling Checklist
+
When monitoring a build/deploy via `zerops_events`:
+
1. **Filter by service**: always use `serviceHostname` parameter to avoid stale events from other services or previous iterations
2. **Check `stack.build` process**: look for status `FINISHED` (success) or `FAILED` (error). Once `FINISHED`, the build is done — stop polling build status
3. **Check `appVersion` build event**: status `ACTIVE` means deployed and running. This confirms deploy completion
4. **Do NOT confuse build events**: `stack.build` process `RUNNING` = build in progress. `appVersion` `ACTIVE` = already deployed. These are different events
5. **Timeout guidance**: builds have a 60-minute hard limit. If no `FINISHED` after ~5 minutes for typical apps, check build logs via `zerops_logs`
6. **Stale events**: project-level events may include old builds from previous deploys. Always verify the event timestamp and service match
+
## Application Versions
+
Zerops keeps **10 most recent versions**. Older auto-deleted. Any archived version can be **restored** -- activates that version, archives current, restores env vars to their state when that version was last active.
+
## Gotchas
+
1. **Build and run are SEPARATE containers** -- build output does not automatically appear in runtime. You must specify `deployFiles`
2. **initCommands run on EVERY container start** -- including restarts and horizontal scaling, not just deploys
3. **initCommands failures do NOT cancel deploy** -- app starts regardless of init exit code
4. **prepareCommands in build vs run** -- `build.prepareCommands` customizes build env, `run.prepareCommands` creates custom runtime image. Different containers, different purposes
5. **deployFiles land in `/var/www`** -- tilde syntax (`dist/~`) extracts contents directly to `/var/www/` (strips directory). Without tilde, `dist` → `/var/www/dist/` (preserved). **CRITICAL**: `run.start` path must match — `dist/~` + `start: bun dist/index.js` BREAKS because the file is at `/var/www/index.js`, not `/var/www/dist/index.js`
+
## SSHFS Mount and Deploy Interaction
+
When using SSHFS (`zerops_mount`) for dev workflows, deploy replaces the container. This has important consequences:
+
1. **After deploy, run container only has `deployFiles` content.** All other files (including zerops.yml if not in deployFiles) are gone. Use `deployFiles: [.]` for dev services to ensure zerops.yml and source files survive the deploy cycle.
2. **SSHFS mount auto-reconnects after deploy.** No explicit remount is needed — the SSHFS reconnect mechanism handles the container replacement transparently. The mount only becomes truly stale during stop (container not running); after start it auto-reconnects again.
3. **zerops.yml must be in deployFiles** for dev self-deploy lifecycle. Without it, subsequent deploys from the container fail because zerops.yml is missing.
+
**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.
+
----------------------------------------
# Guides > Environment Variables
+
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. **Both project-level vars AND cross-service vars (`${hostname_varname}`) auto-inject as OS env vars into every container in the project** — no declaration required. `run.envVariables` exists only for mode flags and framework-convention renames. Re-declaring an auto-injected var under its own name creates a literal-string self-shadow. Secret vars are write-only after creation. Changes require service restart.
+
---
+
## Scope Hierarchy
+
| Scope | Defined In | Visibility | Editable Without Redeploy |
|-------|-----------|------------|--------------------------|
| **Project** | import.yml `project.envVariables`, GUI | All services (auto-inherited) | Yes (restart required) |
@@ -10674,19 +15471,27 @@ Zerops manages environment variables at two scopes (project and service) with st
| **Service basic (build)** | zerops.yml `build.envVariables` | Build container only | No (redeploy required) |
| **Service basic (runtime)** | zerops.yml `run.envVariables` | Runtime container only | No (redeploy required) |
| **Service basic (runtime)** | zerops.yml `run.envVariables` | Runtime container only | No (redeploy required) |
+
## Variable Precedence
+
When the same key exists at multiple levels:
+
1. **Service basic (build/runtime)** wins over service secret
2. **Service-level** wins over project-level
3. Build and runtime are **separate environments** -- same key can have different values in each
+
**DO NOT** create a secret and a basic runtime variable with the same key expecting both to persist. The basic runtime variable from zerops.yml silently overrides the secret.
+
## Build/Runtime Isolation
+
Build and runtime run in **separate containers**. Variables from one phase are not visible in the other unless explicitly referenced with prefixes:
+
| Want to access | From | Use prefix |
|---------------|------|-----------|
| Runtime var `API_KEY` | Build container | `${RUNTIME_API_KEY}` |
| Build var `BUILD_ID` | Runtime container | `${BUILD_BUILD_ID}` |
| Build var `BUILD_ID` | Runtime container | `${BUILD_BUILD_ID}` |
+
```yaml
zerops:
- setup: app
@@ -10697,20 +15502,27 @@ zerops:
envVariables:
API_KEY: "12345-abcde"
```
+
## Cross-Service References — Auto-Injected Project-Wide
+
**Every service's variables are automatically injected as OS environment variables into every other service's containers** — both runtime and build. A worker container sees `db_hostname`, `db_password`, `queue_user`, `storage_apiUrl`, etc. as real OS env vars at container start. Zero declaration in zerops.yml required.
+
Read them directly in application code:
+
```javascript
// Node — lowercase native names match the platform
const host = process.env.db_hostname;
const pwd = process.env.db_password;
const natsUser = process.env.queue_user;
```
+
```php
// PHP
$host = getenv('db_hostname');
```
+
`run.envVariables` and `build.envVariables` have **two legitimate uses only**:
+
1. **Mode flags** — per-setup values that don't come from another service:
```yaml
run:
@@ -10718,6 +15530,7 @@ $host = getenv('db_hostname');
NODE_ENV: production
APP_ENV: local
```
+
2. **Framework-convention renames** — forward a platform var under a different name because the framework config expects it. The key on the left MUST DIFFER from the source var name on the right:
```yaml
run:
@@ -10725,39 +15538,55 @@ $host = getenv('db_hostname');
DB_HOST: ${db_hostname} # TypeORM expects uppercase DB_HOST
DATABASE_URL: ${db_connectionString}
```
+
**Do NOT re-declare auto-injected vars under their own name.** It is always wrong and never useful:
+
```yaml
run:
envVariables:
db_hostname: ${db_hostname} # SELF-SHADOW — see next section
db_password: ${db_password} # SELF-SHADOW
queue_hostname: ${queue_hostname} # SELF-SHADOW
- STAGE_API_URL: ${STAGE_API_URL} # SELF-SHADOW (project-level variant)
+ API_URL: ${API_URL} # SELF-SHADOW (project-level variant)
```
+
The referenced variable does **not** need to exist at definition time — Zerops resolves at container start.
+
### Self-Shadow Trap
+
Writing `varname: ${varname}` in `run.envVariables` creates a literal-string self-shadow. The platform's interpolator sees the service-level variable of that name first, can't recurse back to the auto-injected value, and the resolved OS env var becomes the literal string `${varname}`:
+
```yaml
run:
envVariables:
db_hostname: ${db_hostname} # OS env: db_hostname='${db_hostname}' (literal)
db_password: ${db_password} # OS env: db_password='${db_password}' (literal)
```
+
At runtime, the worker tries to connect to `"${db_hostname}:5432"` and crashes. The fix is to **delete the entire block** — those vars are already in the container's env without any declaration.
-This applies identically to project-level vars (`${STAGE_API_URL}`, `${APP_SECRET}`) and cross-service vars (`${db_hostname}`, `${queue_user}`) — both auto-propagate, both self-shadow under the same rule.
+
+This applies identically to project-level vars (`${API_URL}`, `${APP_SECRET}`) and cross-service vars (`${db_hostname}`, `${queue_user}`) — both auto-propagate, both self-shadow under the same rule.
+
**Hostname transformation**: dashes become underscores. Service `my-db` variable `port` is `${my_db_port}`.
+
### Cross-Service References in API vs Runtime
+
Cross-service references (`${hostname_varname}`) are **resolved at container start time**, not at definition time. This means:
+
- **`zerops_discover` with `includeEnvs=true`** returns the **literal template** (e.g., `${db_password}`), NOT the resolved value. This is expected — the API stores templates, not resolved values.
- **Inside the running container**, environment variables contain the actual resolved values.
- **Restarting a service does NOT change** what `zerops_discover` returns — it always shows templates. To verify resolved values, check from inside the container (e.g., via SSH or application endpoint).
+
### Isolation Modes (envIsolation)
+
`envIsolation` does NOT control whether cross-service vars auto-inject — they do, in every mode. It controls something narrower: how `${hostname_varname}` templates inside zerops.yml and import.yml *resolve* during platform interpolation.
+
| Mode | Behavior |
|------|----------|
| `service` (default) | Service-scoped: `${hostname_varname}` templates inside that service's YAML resolve by following the hostname prefix. The OS env in every container still contains every other service's vars as auto-injected keys. |
| `none` (legacy) | Cross-service references can be written without the `${hostname_varname}` prefix (e.g. `${password}` resolves to the nearest match). Do not use for new projects — ambiguous, error-prone. |
| `none` (legacy) | Cross-service references can be written without the `${hostname_varname}` prefix (e.g. `${password}` resolves to the nearest match). Do not use for new projects — ambiguous, error-prone. |
+
Set in import.yml at project or service level:
```yaml
project:
@@ -10766,58 +15595,76 @@ services:
- hostname: db
envIsolation: none # legacy — avoid
```
+
**Default (`service`) is the right choice.** The auto-inject behavior above applies under the default.
+
## Project Variables -- Auto-Inherited
+
Project variables are **automatically available in every service, in both runtime AND build containers**. The platform injects them as OS env vars at container start in every service's runtime container and also in every service's build container during the build phase. From zerops.yaml's point of view they are referenced **directly by name** with `${VAR_NAME}` — **no `RUNTIME_` prefix in either scope**. The `RUNTIME_` prefix is reserved for a different use case: lifting a single service's service-level runtime variable into that same service's build context. Project-scope vars are broader than service-scope and do not need lifting.
+
**In shell commands** (buildCommands, initCommands, start) project vars are directly readable:
```yaml
build:
buildCommands:
- - echo "building for $STAGE_API_URL" # shell reads the OS env var
- - VITE_API_URL=$STAGE_API_URL npm run build # or pass it forward by shell prefix
+ - echo "building for $API_URL" # shell reads the OS env var
+ - VITE_API_URL=$API_URL npm run build # or pass it forward by shell prefix
```
+
**In `build.envVariables` YAML** (to compose a derived var that the bundler consumes) reference the project var directly without prefix:
```yaml
build:
envVariables:
- VITE_API_URL: ${STAGE_API_URL} # project var STAGE_API_URL read as-is, NO RUNTIME_ prefix
+ VITE_API_URL: ${API_URL} # project var API_URL read as-is, NO RUNTIME_ prefix
```
+
**In `run.envVariables` YAML** (to forward a project var under a framework-conventional name without creating a shadow), reference directly without prefix:
```yaml
run:
envVariables:
- FRONTEND_URL: ${STAGE_FRONTEND_URL} # project var STAGE_FRONTEND_URL forwarded as FRONTEND_URL
+ CORS_ALLOWED_ORIGIN: ${FRONTEND_URL} # project var FRONTEND_URL forwarded under a different name
```
+
**DO NOT** re-reference an auto-injected variable under its SAME name — that's a self-shadow loop. Applies to BOTH project-level vars AND cross-service vars:
+
```yaml
envVariables:
PROJECT_NAME: ${PROJECT_NAME} # project-level self-shadow
- STAGE_API_URL: ${STAGE_API_URL} # project-level self-shadow
+ API_URL: ${API_URL} # project-level self-shadow
db_hostname: ${db_hostname} # cross-service self-shadow
queue_user: ${queue_user} # cross-service self-shadow
```
+
All four resolve to the literal string `${VAR_NAME}` inside the container — the framework tries to connect to `"${db_hostname}:5432"` and crashes. The fix is to delete those lines entirely — the platform already injects the real value as an OS env var.
+
To **override** a project variable for one service, define a service-level variable with the same key and a DIFFERENT VALUE (not a reference to the project var):
```yaml
run:
envVariables:
LOG_LEVEL: debug # overrides project-level LOG_LEVEL for this service
```
+
### Typical pattern: project-level URL constants for dual-runtime recipes
+
Dual-runtime recipes (frontend SPA + backend API on the same platform) use project-level URL constants as the single source of truth for cross-service URLs. The constants are derived from `${zeropsSubdomainHost}` (a platform-generated project-scope env var present from project creation) and the services' known hostnames:
+
```yaml
project:
envVariables:
- STAGE_API_URL: https://apistage-${zeropsSubdomainHost}-3000.prg1.zerops.app
- STAGE_FRONTEND_URL: https://appstage-${zeropsSubdomainHost}.prg1.zerops.app
+ API_URL: https://apistage-${zeropsSubdomainHost}-3000.prg1.zerops.app
+ FRONTEND_URL: https://appstage-${zeropsSubdomainHost}.prg1.zerops.app
```
-The platform resolves `${zeropsSubdomainHost}` when injecting the value into services at container start. The frontend consumes `STAGE_API_URL` via plain `${STAGE_API_URL}` in `build.envVariables` (baking it into the bundle at compile time) — **no `RUNTIME_` prefix**. The API consumes `STAGE_FRONTEND_URL` via plain `${STAGE_FRONTEND_URL}` in `run.envVariables` (for CORS allow-list). The same names must be set on the workspace project via `zerops_env project=true action=set` after provision, so workspace verification doesn't see literal `${STAGE_FRONTEND_URL}` strings.
+
+The platform resolves `${zeropsSubdomainHost}` when injecting the value into services at container start. The frontend consumes `API_URL` via plain `${API_URL}` in `build.envVariables` (baking it into the bundle at compile time) — **no `RUNTIME_` prefix**. The API consumes `FRONTEND_URL` via plain `${FRONTEND_URL}` in `run.envVariables` (for CORS allow-list). The same names must be set on the workspace project via `zerops_env project=true action=set` after provision, so workspace verification doesn't see literal `${FRONTEND_URL}` strings.
+
## Secret Variables
+
- Defined via GUI, import.yml `envSecrets`, or `dotEnvSecrets`
- **Write-only after creation** -- values masked in GUI, cannot be read back via API
- Can be updated without redeploy, but service **must be restarted**
- Overridden by basic (zerops.yml) variables with the same key
+
### dotEnvSecrets
+
Import secrets in `.env` format within import.yml:
```yaml
services:
@@ -10827,8 +15674,11 @@ services:
DB_PASSWORD=secure123
```
All entries become secret variables. Requires `#zeropsPreprocessor=on` if using generator functions.
+
## envReplace -- File-Level Substitution
+
Replaces placeholders in deployed files with environment variable values **during deployment** (not at runtime).
+
```yaml
run:
envReplace:
@@ -10837,34 +15687,50 @@ run:
- ./config/
- ./templates/settings.json
```
+
| Parameter | Required | Description |
|-----------|----------|-------------|
| `delimiter` | Yes | Wrapping characters (e.g., `%%` makes `%%VAR%%`). String or array |
| `target` | Yes | Files or directories to process. String or array |
| `target` | Yes | Files or directories to process. String or array |
+
**DO NOT** expect directory targets to recurse into subdirectories. `./config/` processes only files directly in `config/`, not `config/jwt/`. Specify each subdirectory explicitly.
+
## Naming Restrictions
+
**Key**: must match `[a-zA-Z_]+[a-zA-Z0-9_]*`. Case-sensitive. Must be unique within scope regardless of case.
+
**Value**: ASCII only. No EOL characters.
+
## Restart Requirement
+
Env var changes (secret or project) take effect only on container start. The running process does **not** receive updated values.
+
**DO NOT** expect hot-reload of env vars. After changing secrets or project vars in GUI, **restart the service**. For zerops.yml `envVariables` changes, a **full redeploy** is required.
+
## System-Generated Variables
+
Zerops auto-generates variables per service (e.g., `hostname`, `PATH`, DB connection strings). Cannot be deleted. Some read-only (`hostname`), others editable (`PATH`). Can be referenced by other services using `${hostname_varname}`.
+
## Common Mistakes
-- **DO NOT** re-reference auto-injected vars under their own name — self-shadow loop. Applies to BOTH project-level (`STAGE_API_URL: ${STAGE_API_URL}`) AND cross-service (`db_hostname: ${db_hostname}`, `queue_user: ${queue_user}`).
+
+- **DO NOT** re-reference auto-injected vars under their own name — self-shadow loop. Applies to BOTH project-level (`API_URL: ${API_URL}`) AND cross-service (`db_hostname: ${db_hostname}`, `queue_user: ${queue_user}`).
- **DO NOT** declare cross-service vars you only want to READ — they are already in the container's OS env. Read via `process.env.db_hostname` / `getenv('db_hostname')` directly. Declare in `run.envVariables` only to RENAME (e.g. `DB_HOST: ${db_hostname}`) or to set mode flags.
- **DO NOT** forget restart after GUI/API env changes — process won't see new values
- **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
+
----------------------------------------
# Guides > Firewall
+
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)
+
| Port | Protocol | Status |
|------|----------|--------|
| 22 | SSH | Allowed |
@@ -10877,161 +15743,73 @@ Zerops uses nftables with restricted TCP ports 1-1024 (only 22, 53, 80, 123, 443
| 587 | SMTP/STARTTLS | Allowed |
| All others | — | **Blocked** |
| All others | — | **Blocked** |
+
## UDP Ports
No restrictions on any UDP port.
+
## TCP Ports 1025-65535
No restrictions.
+
## Direct Port Access Firewall
For services with direct port access enabled:
- Configure **blacklist** or **whitelist** rules per port
- Available on ports 10-65435
- Protocols: TCP, UDP
+
## Port Modification
Contact `support@zerops.io` with Project ID + Organization ID to request changes to restricted ports.
+
## Gotchas
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
+
----------------------------------------
-# Guides > Local Development
+# Guides > Logging
+
-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.
----
-## Setup
-### Prerequisites
-- **zcli** installed: `npm i -g @zerops/zcli` or [docs.zerops.io/references/cli](https://docs.zerops.io/references/cli)
-- **VPN**: WireGuard (installed by zcli automatically on first `zcli vpn up`)
-- **Project-scoped token**: Create in Zerops GUI → Settings → Access Tokens → Custom access per project
-### Configuration
-```json
-// .mcp.json (in project root)
-{
- "mcpServers": {
- "zcp": {
- "command": "zcp",
- "env": { "ZCP_API_KEY": "" }
- }
- }
-}
-```
----
-## Workflow
-### 1. Connect to Zerops services
+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
+1. **Build logs** — output from build pipeline
+2. **Prepare runtime logs** — output from custom runtime image creation
+3. **Runtime/Database logs** — operational output (stdout/stderr)
+
+## Access Methods
+
+### GUI
+- Project detail → service → Logs section
+- Filter by severity, time range, container
+
+### CLI
```bash
-zcli vpn up
-```
-- All services accessible by hostname (e.g., `db`, `cache`)
-- One project at a time — switching disconnects the current
-- **Env vars NOT available via VPN** — use `.env` file instead
-### 2. Load credentials
-ZCP generates `.env` from `zerops_discover`:
+zcli service log # Runtime logs
+zcli service log --showBuildLogs # Build logs
```
-db_host=db
-db_port=5432
-db_password=
-db_connectionString=postgresql://db:@db:5432/db
-```
-How to load:
-| Runtime | Method |
-|---------|--------|
-| Node.js 20+ | `node --env-file .env app.js` |
-| Next.js, Vite, Nuxt | Automatic (reads `.env`) |
-| PHP/Laravel | Automatic (reads `.env`) |
-| Python | `python-dotenv` or `django-environ` |
-| Go | `godotenv.Load()` or `source .env && go run .` |
-| Java/Spring | `spring-dotenv` or `application.properties` |
-| Java/Spring | `spring-dotenv` or `application.properties` |
-### 3. Develop locally
-Start your dev server as usual — hot reload works against Zerops managed services over VPN.
-### 4. Deploy to Zerops
-```
-zerops_deploy targetService="appstage"
-```
-Uses `zcli push` under the hood. Blocks until build completes.
----
-## zerops.yml for Local Mode
-The same `zerops.yml` works for both local push and container deploy:
-```yaml
-zerops:
- - setup: appstage
- build:
- base: nodejs@22
- buildCommands:
- - npm ci
- - npm run build
- deployFiles: ./dist
- run:
- start: node dist/server.js
- ports:
- - port: 3000
- httpSupport: true
- envVariables:
- DB_URL: ${db_connectionString}
-```
-`${hostname_varName}` references are resolved by Zerops at container runtime — they work regardless of push source (local or container).
----
-## Connection Troubleshooting
-| Symptom | Diagnosis | Fix |
-|---------|-----------|-----|
-| `nc -zv db 5432` times out | VPN not connected | `zcli vpn up ` |
-| VPN connected, still timeout | Wrong project | `zcli vpn up ` |
-| Connected but auth fails | Stale .env | Regenerate from `zerops_discover includeEnvs=true` |
-| Service unreachable | Service stopped | `zerops_manage action="start" serviceHostname="db"` |
-| Service unreachable | Service stopped | `zerops_manage action="start" serviceHostname="db"` |
-### Diagnostic sequence
-1. `zerops_discover service="db"` — is service RUNNING?
-2. `nc -zv db 5432 -w 3` — network reachable?
-3. Compare `.env` vs `zerops_discover includeEnvs=true` — credentials current?
----
-## Multi-Project
-Each project directory has its own `.mcp.json` + `.zcp/state/`. VPN is one per machine — switch manually:
-```bash
-zcli vpn up # work on project A
-zcli vpn up # auto-disconnects A, connects B
-```
----
-## Gotchas
-1. **VPN = network only**: Env vars must come from `.env` file, not VPN connection
-2. **`.env` contains secrets**: Add to `.gitignore` immediately — never commit
-3. **Deploy = new container**: Local files on Zerops are lost on every deploy. Only `deployFiles` content persists
-4. **One VPN project at a time**: Connecting to project B disconnects project A
-5. **Object storage (S3)**: Uses HTTPS apiUrl — may work without VPN but not fully verified. Include VPN as fallback
-6. **zcli must be installed**: `zerops_deploy` requires zcli in PATH. Error message includes install link if missing
-
-----------------------------------------
-
-# Guides > Logging
-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
-1. **Build logs** — output from build pipeline
-2. **Prepare runtime logs** — output from custom runtime image creation
-3. **Runtime/Database logs** — operational output (stdout/stderr)
-## Access Methods
-### GUI
-- Project detail → service → Logs section
-- Filter by severity, time range, container
-### CLI
-```bash
-zcli service log # Runtime logs
-zcli service log --showBuildLogs # Build logs
-```
## Severity Filtering
Logs must output to **syslog format** for severity filtering to work. Plain stdout/stderr logs appear as "info" level.
+
## Log Forwarding
+
### Ready-Made Integrations
- **Better Stack** — cloud log management
- **Papertrail** — cloud log aggregation
- **ELK Stack** — self-hosted (Elasticsearch + Logstash + Kibana)
+
### ELK Stack Setup (Self-Hosted on Zerops)
+
Services needed:
- `elkstorage` — Elasticsearch
- `kibana` — UI
- `logstash` — Log collection (UDP syslog)
+
Multi-project forwarding: make Logstash public with firewall whitelist rules.
+
### Custom syslog-ng Configuration
+
**Critical**: Use source name `s_src` (not `s_sys`):
```
source s_src {
@@ -11039,9 +15817,11 @@ source s_src {
internal();
};
```
+
Certificate paths:
- System certs: `/etc/ssl/certs`
- Custom certs: `ca-file("/etc/syslog-ng/user.crt")`
+
## Gotchas
1. **Syslog format required**: Without syslog formatting, all logs appear as same severity — no filtering possible
2. **Build logs separate**: Use `--showBuildLogs` flag in CLI — not shown by default
@@ -11049,14 +15829,18 @@ Certificate paths:
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`
+
----------------------------------------
# Guides > Metrics
+
Zerops supports ELK (APM + logs) and Prometheus/Grafana stacks; expose `/metrics` endpoint and set `ZEROPS_PROMETHEUS_PORT` for auto-scraping.
+
## Deployment Modes
- **Local**: Monitoring services in the same project as your app
- **Global**: Dedicated observability project (recommended for multi-project)
+
## ELK Stack Services
| Service | Purpose |
|---------|---------|
@@ -11065,14 +15849,16 @@ Zerops supports ELK (APM + logs) and Prometheus/Grafana stacks; expose `/metrics
| `apmserver` | APM traces (made public via Zerops subdomain) |
| `logstash` | Log collection |
| `logstash` | Log collection |
+
### APM Configuration
```yaml
envVariables:
ELASTIC_APM_ACTIVE: "true"
ELASTIC_APM_SERVICE_NAME: my-app
ELASTIC_APM_SERVER_URL: https://apmserver.zerops.app
- ELASTIC_APM_SECRET_TOKEN:
+ ELASTIC_APM_SECRET_TOKEN:
```
+
## Prometheus + Grafana Stack Services
| Service | Purpose |
|---------|---------|
@@ -11082,27 +15868,35 @@ envVariables:
| `prometheusbackups` | S3 for Prometheus data |
| `prometheuslight` | Forwarder (in source project for cross-project) |
| `prometheuslight` | Forwarder (in source project for cross-project) |
+
### Custom Metrics
1. Expose HTTP `/metrics` endpoint in your app
2. Set env var: `ZEROPS_PROMETHEUS_PORT=8080` (comma-separated for multiple ports)
3. Prometheus auto-discovers and scrapes
+
## Built-in Metrics
- Service scaling & resource usage
- PostgreSQL (with `pg_stat_statements` extension)
- MariaDB
- Valkey
+
## Gotchas
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
+
----------------------------------------
# Guides > Networking
+
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.
+
---
+
## Architecture Overview
+
```
Internet
│
@@ -11110,33 +15904,49 @@ Internet
│
└─ Direct port ──→ L3/Core Balancer ──→ container VXLAN IP:port
```
+
**Per-project infrastructure:**
- **Private VXLAN network** — isolated overlay network shared by all services
- **L7 HTTP Balancer** — 2 HA containers, auto-scales, domain routing + SSL
- **L3 Core Balancer** — IP addresses and direct port access (TCP/UDP)
+
---
+
## Internal Networking (VXLAN)
+
Services in the same project communicate by **hostname and internal port**:
+
```
http://api:3000/health
http://postgres:5432
```
+
**Rules:**
- Always **`http://`** — never `https://` for internal traffic
- Isolated per project — no cross-project private networking
- Service discovery is automatic — no manual network config
- VPN uses same hostnames: `http://api:3000` from local machine (both `api` and `api.zerops` resolve — VPN sets up DNS search domain)
+
**Cross-service env vars**: prefix with hostname — e.g., `app_API_TOKEN`. Zerops auto-generates connection vars for managed services.
+
**DO NOT** use `https://` for service-to-service calls — SSL terminates at the L7 balancer, internal network is already isolated.
+
---
+
## L7 Balancer (HTTP/HTTPS)
+
The L7 balancer is **nginx-based**, deployed as 2 HA containers per project. It handles SSL/TLS termination (Let's Encrypt, auto-renewed), domain routing, round-robin load balancing with health checks, and connection pooling.
+
### Proxy Headers
+
The balancer forwards client info via standard headers:
- **`X-Forwarded-For`** / **`X-Real-IP`** — original client IP
- **`X-Forwarded-Proto`** — `https` (original protocol)
+
Your app receives plain HTTP but can inspect these headers for the real client info.
+
### Key Default Settings
+
| Parameter | Default | Range | Notes |
|-----------|---------|-------|-------|
| `worker_connections` | 4000 | 1024-65535 | Simultaneous connections per worker |
@@ -11148,8 +15958,11 @@ Your app receives plain HTTP but can inspect these headers for the real client i
| `send_timeout` | 2s | 1s-300s | Response transmission timeout |
| `proxy_buffering` | on | on/off | Buffer backend responses |
| `proxy_buffering` | on | on/off | Buffer backend responses |
+
**Zerops subdomain** balancer: fixed **50 MB** upload limit (not configurable).
+
### Advanced Routing Features (GUI)
+
| Feature | Description |
|---------|-------------|
| **Redirects** | 301/302/307/308 with `preservePath` and `preserveQuery` options |
@@ -11158,9 +15971,13 @@ Your app receives plain HTTP but can inspect these headers for the real client i
| **Basic Auth** | HTTP Basic Authentication per location |
| **Custom Content** | Return static content with custom status code and MIME type |
| **Custom Content** | Return static content with custom status code and MIME type |
+
---
+
## 502 Bad Gateway Diagnostic Checklist
+
Work through these steps **in order**:
+
1. **Binding address** — App bound to `0.0.0.0`? Binding `127.0.0.1`/`localhost` is the #1 cause
2. **Port match** — App listening on the port declared in `zerops.yml` `ports[]`?
3. **App running** — Check runtime logs (`zerops_logs`) for crash/startup errors
@@ -11168,15 +15985,22 @@ Work through these steps **in order**:
5. **Readiness check** — If configured, traffic only routes after it passes
6. **Service status** — Is the service ACTIVE? (check `zerops_discover`)
7. **Timeout settings** — For slow responses, increase `send_timeout` (default 2s)
+
**Common framework fixes:**
```bash
app.listen(3000, '0.0.0.0')
+
flask run --host=0.0.0.0
+
http.ListenAndServe(":8080", handler) // implicit 0.0.0.0
+
server.address=0.0.0.0
```
+
---
+
## Shared vs Dedicated IPv4
+
| Feature | Shared IPv4 | Dedicated IPv4 |
|---------|-------------|----------------|
| Cost | Free | $3 / 30 days |
@@ -11187,15 +16011,21 @@ server.address=0.0.0.0
| SNI routing | AAAA record used for verification | Not needed |
| Production use | No | Yes |
| Production use | No | Yes |
+
**Shared IPv4 SNI mechanism**: Zerops reverse-looks-up the domain's AAAA record to verify project ownership. Without it, routing fails silently.
+
---
+
## Cloudflare Integration Summary
+
- **SSL mode**: Always **Full (strict)** — "Flexible" causes redirect loops
- **Shared IPv4 + proxy**: **DO NOT** — reverse AAAA lookup breaks with Cloudflare proxy
- **Best setup**: IPv6-only AAAA record, Cloudflare proxied (handles IPv4 translation)
- **ACME challenge**: WAF skip rule for `/.well-known/acme-challenge/`
-- **Wildcard SSL**: `_acme-challenge.` CNAME to `.zerops.zone`
+- **Wildcard SSL**: `_acme-challenge.` CNAME to `.zerops.zone`
+
---
+
## Gotchas
1. **Binding localhost = 502**: The L7 balancer connects via VXLAN IP, not localhost — always bind `0.0.0.0`
2. **Internal HTTPS breaks things**: Service-to-service must use `http://` — the VXLAN network is already isolated
@@ -11204,13 +16034,18 @@ server.address=0.0.0.0
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
+
----------------------------------------
# Guides > Object Storage Integration
+
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
+
When you create an Object Storage service, Zerops auto-generates these env vars (prefix with hostname for cross-service access, e.g. `${storage_apiUrl}`):
+
| Variable | Description |
|----------|-------------|
| `apiUrl` | S3 endpoint URL — full `https://...` URL ready for any S3 SDK's `endpoint` option |
@@ -11223,7 +16058,9 @@ When you create an Object Storage service, Zerops auto-generates these env vars
| `serviceId` | Service ID (Zerops-generated) |
| `hostname` | Service hostname |
| `hostname` | Service hostname |
+
**Use `${storage_apiUrl}` as the S3 endpoint** — it carries the complete `https://` scheme and is what every S3 SDK's `endpoint` option expects. The `apiHost` variant is host-only; if a client library requires host separately, combine `https://${storage_apiHost}` manually — **never `http://`**. The object-storage gateway rejects plaintext HTTP with a 301 redirect to the HTTPS equivalent, and most S3 SDKs don't follow the redirect automatically. The symptom of a misconfigured endpoint is `UnknownError` or connection-refused on the first bucket call.
+
Reference them in zerops.yml `run.envVariables`:
```yaml
S3_ENDPOINT: ${storage_apiUrl}
@@ -11233,14 +16070,21 @@ S3_BUCKET: ${storage_bucketName}
S3_REGION: us-east-1
AWS_USE_PATH_STYLE_ENDPOINT: "true"
```
+
## Path Style Endpoint (Required)
+
Zerops uses MinIO which requires **path-style** URLs (not virtual-hosted):
+
```
https://endpoint.com/bucket-name/object-key
+
https://bucket-name.endpoint.com/object-key
```
+
**Every S3 client must be configured for path-style access.**
+
## Framework Integration
+
### PHP (Laravel — Flysystem)
```php
// config/filesystems.php
@@ -11255,8 +16099,10 @@ https://bucket-name.endpoint.com/object-key
],
```
Package: `league/flysystem-aws-s3-v3`
+
### Node.js (AWS SDK v3)
```javascript
+
const s3 = new S3Client({
endpoint: process.env.S3_ENDPOINT,
forcePathStyle: true, // REQUIRED
@@ -11268,6 +16114,7 @@ const s3 = new S3Client({
});
```
Package: `@aws-sdk/client-s3`
+
### Python (boto3)
```python
import boto3
@@ -11280,6 +16127,7 @@ s3 = boto3.client('s3',
)
```
Package: `boto3`
+
### Java (AWS SDK)
```java
S3Client s3 = S3Client.builder()
@@ -11294,7 +16142,9 @@ S3Client s3 = S3Client.builder()
.region(Region.US_EAST_1)
.build();
```
+
## import.yaml Definition
+
```yaml
services:
- hostname: storage
@@ -11303,15 +16153,20 @@ services:
objectStoragePolicy: public-read # predefined policy
priority: 10
```
+
**Predefined policies** (`objectStoragePolicy`):
- `private` — no anonymous access (documents, backups)
- `public-read` — anonymous list + get (media, avatars, static assets)
- `public-objects-read` — anonymous get only, no listing (direct links only)
- `public-write` — anonymous put only
- `public-read-write` — full anonymous access
+
**Custom policy**: use `objectStorageRawPolicy` with IAM Policy JSON instead (template var `{{ .BucketName }}` available).
+
Each service = one bucket (auto-named, immutable). Need multiple buckets? Create multiple services.
+
## When to Use Object Storage
+
| Scenario | Use Object Storage? |
|----------|-------------------|
| User uploads (avatars, documents) | Yes — lost on deploy |
@@ -11321,6 +16176,7 @@ Each service = one bucket (auto-named, immutable). Need multiple buckets? Create
| Logs | No — use Zerops logging |
| Database dumps | Yes — for backup storage |
| Database dumps | Yes — for backup storage |
+
## Gotchas
1. **`forcePathStyle: true` / `AWS_USE_PATH_STYLE_ENDPOINT: true` is REQUIRED**: Zerops uses MinIO which doesn't support virtual-hosted style
2. **Container filesystem is replaced on deploy**: Files on disk survive restarts but are lost when a new container is created (deploy, scale-up). Always use Object Storage for persistent data
@@ -11331,16 +16187,24 @@ Each service = one bucket (auto-named, immutable). Need multiple buckets? Create
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
+
----------------------------------------
# Guides > Php Tuning
+
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_*`)
+
Override any php.ini directive via `PHP_INI_{directive}` env vars in `run.envVariables` or via `zerops_env` API.
+
**Requires restart** to take effect. Reload writes config files (`/etc/php*/conf.d/overwrite.ini`) but FPM master does not re-read INI on reload.
+
### Zerops Platform Defaults
+
Zerops overrides several stock PHP values for production use:
+
| Directive | Zerops default | Stock PHP | Why |
|-----------|---------------|-----------|-----|
| `upload_max_filesize` | **1024M** | 2M | Generous upload limit (L7 balancer is the real gate) |
@@ -11352,7 +16216,9 @@ Zerops overrides several stock PHP values for production use:
| `date.timezone` | **UTC** | (empty) | Consistent timezone |
| `sendmail_path` | `/usr/sbin/sendmail -t -i` | (empty) | System sendmail wired |
| `sendmail_path` | `/usr/sbin/sendmail -t -i` | (empty) | System sendmail wired |
+
### Example
+
```yaml
zerops:
- setup: app
@@ -11365,11 +16231,17 @@ zerops:
PHP_INI_max_execution_time: 60
PHP_INI_max_input_vars: 5000
```
+
## PHP-FPM (`PHP_FPM_*`)
+
Configure FPM process management via `PHP_FPM_*` env vars. **Requires restart** — same as PHP_INI.
+
Config files are written to `/etc/php*/php-fpm.d/www.conf` by `zerops-zenv` at container startup.
+
### Dynamic Mode (default)
+
Pre-forks a pool of workers. Good for consistent traffic.
+
| Variable | Default |
|----------|---------|
| `PHP_FPM_PM` | `dynamic` |
@@ -11380,7 +16252,9 @@ Pre-forks a pool of workers. Good for consistent traffic.
| `PHP_FPM_PM_MAX_SPAWN_RATE` | `32` |
| `PHP_FPM_PM_MAX_REQUESTS` | `500` |
| `PHP_FPM_PM_MAX_REQUESTS` | `500` |
+
High-traffic example:
+
```yaml
envVariables:
PHP_FPM_PM_MAX_CHILDREN: 50
@@ -11389,8 +16263,11 @@ envVariables:
PHP_FPM_PM_MAX_SPARE_SERVERS: 15
PHP_FPM_PM_MAX_REQUESTS: 1000
```
+
### Ondemand Mode
+
Spawns workers only when requests arrive. Saves memory for low-traffic sites.
+
```yaml
envVariables:
PHP_FPM_PM: ondemand
@@ -11398,26 +16275,37 @@ envVariables:
PHP_FPM_PM_PROCESS_IDLE_TIMEOUT: 60s
PHP_FPM_PM_MAX_REQUESTS: 500
```
+
Available parameters for ondemand:
- `PHP_FPM_PM_MAX_CHILDREN` -- maximum child processes
- `PHP_FPM_PM_PROCESS_IDLE_TIMEOUT` -- idle timeout before termination (default: 60s)
- `PHP_FPM_PM_MAX_REQUESTS` -- requests per process before recycling (default: 500)
+
## Upload Limits (3-layer chain)
+
File uploads pass through three layers -- ALL must allow the size:
+
1. **L7 Balancer**: `client_max_body_size` = 512m (custom domain) / **50MB fixed** (subdomain)
2. **PHP**: `upload_max_filesize` = 1024M (Zerops default)
3. **PHP**: `post_max_size` = 1024M (Zerops default)
+
Zerops pre-configures generous PHP limits, so the **L7 balancer is typically the bottleneck**:
- Subdomain (zerops.app): hard 50MB cap, cannot be changed
- Custom domain: 512m default, configurable via custom Nginx template
+
## Extensions (Alpine)
-Install via `sudo apk add --no-cache php84-` — version prefix must match PHP major+minor (e.g. `php84-` for PHP 8.4). Sudo required — containers run as `zerops` user.
+
+Install via `sudo apk add --no-cache php84-` — version prefix must match PHP major+minor (e.g. `php84-` for PHP 8.4). Sudo required — containers run as `zerops` user.
+
Build and runtime are **separate containers with separate images**. The build base (`php@X`) is Alpine-minimal. The runtime base (`php-nginx@X`, `php-apache@X`) bundles more extensions but not all.
+
If a Composer dependency requires an extension that's missing from the build image:
- Install it in `build.prepareCommands` so Composer validates platform requirements properly
- If also needed at runtime, install in `run.prepareCommands` too (separate container, separate image)
- **Never** use `--ignore-platform-reqs` — it suppresses all platform checks, hiding real problems that crash at runtime
+
Common extensions not in the build base: `ext-pcntl`, `ext-posix` (needed by Horizon), `ext-gd`, `ext-intl`.
+
```yaml
build:
base: php@8.4
@@ -11430,25 +16318,34 @@ run:
prepareCommands:
- sudo apk add --no-cache php84-pcntl php84-posix
```
+
## Gotchas
+
- **Reload does NOT apply changes** -- `PHP_INI_*` and `PHP_FPM_*` both require restart. Zerops reload rewrites config files via `zerops-zenv` but does not signal FPM to re-read them.
- **Upload fails at 50MB on subdomain** -- this is the L7 balancer limit, not PHP. Use a custom domain for larger uploads.
- **`post_max_size` must be >= `upload_max_filesize`** -- PHP silently drops the POST body if it exceeds `post_max_size`, even if the file itself is under `upload_max_filesize`.
+
----------------------------------------
# Guides > Production Checklist
+
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
+
| Item | Dev | Production |
|------|-----|------------|
| Mode | `NON_HA` | `HA` (must recreate) |
| Backups | Optional | Enabled |
| Connection | Single primary | Primary + read replicas |
| Connection | Single primary | Primary + read replicas |
+
**HA is immutable** — cannot switch after creation. Delete and recreate with `mode: HA`.
+
## Application Services
+
| Item | Dev | Production |
|------|-----|------------|
| minContainers | 1 | 2+ |
@@ -11456,28 +16353,36 @@ Before going to production: (1) databases to HA mode, (2) minContainers: 2 on ap
| Logging | Console/debug | Structured (syslog) |
| Debug mode | Enabled | Disabled |
| Debug mode | Enabled | Disabled |
+
```yaml
- hostname: app
type: nodejs@22
minContainers: 2
maxContainers: 4
```
+
## Dev Services to Remove
+
### Mailpit → Production SMTP
```yaml
- hostname: mailpit
type: go@1
buildFromGit: https://github.com/zeropsio/recipe-mailpit
+
envVariables:
SMTP_HOST: smtp.sendgrid.net
SMTP_PORT: "587"
envSecrets:
SMTP_PASSWORD: your-production-key
```
+
### Adminer → Remove or Restrict
Remove entirely or disable `enableSubdomainAccess`. Use VPN + pgAdmin/DBeaver locally.
+
## File Storage
+
**Container filesystem survives restarts but is replaced on every deploy** — files stored on disk persist through reload/restart/stop+start but are lost on deploy or container replacement (scale-up/down).
+
| Use case | Solution |
|----------|----------|
| User uploads | Object Storage (S3) |
@@ -11485,14 +16390,18 @@ Remove entirely or disable `enableSubdomainAccess`. Use VPN + pgAdmin/DBeaver lo
| Temp files | Container disk (OK) |
| Build artifacts | Deploy via zerops.yaml |
| Build artifacts | Deploy via zerops.yaml |
+
```yaml
- hostname: storage
type: object-storage
objectStorageSize: 2
objectStoragePolicy: public-read
```
+
## Sessions & Cache
+
**File-based sessions break with multiple containers and are lost on deploy.**
+
| Use case | Solution |
|----------|----------|
| PHP sessions | Redis/Valkey |
@@ -11500,39 +16409,49 @@ Remove entirely or disable `enableSubdomainAccess`. Use VPN + pgAdmin/DBeaver lo
| Django sessions | Redis backend |
| Express sessions | Redis store |
| Express sessions | Redis store |
+
```yaml
- hostname: cache
type: valkey@7.2
mode: NON_HA # HA for production
```
+
## Framework-Specific Production Settings
+
### PHP/Laravel
- `APP_ENV: production`, `APP_DEBUG: "false"`
- Trusted proxies: `TRUSTED_PROXIES: 127.0.0.1,10.0.0.0/8`
- Sessions in Redis, not files
- Optimize: `php artisan config:cache && route:cache && view:cache`
+
### PHP/Symfony
- `APP_ENV: prod`
- `TRUSTED_PROXIES: 127.0.0.1,10.0.0.0/8`
- Logging via Monolog SyslogHandler
+
### Python/Django
- `DEBUG: "false"`
- `CSRF_TRUSTED_ORIGINS: https://your-domain.com`
- `ALLOWED_HOSTS: .zerops.app,your-domain.com`
- Static files via `collectstatic`
+
### Node.js
- `NODE_ENV: production`
- `HOST: 0.0.0.0`
- Health check endpoint at `/status` or `/health`
+
### Java/Spring
- `server.address: 0.0.0.0` (required — default binds localhost)
- Actuator health endpoints enabled
- JVM memory flags: `-Xmx512m` (match container limits)
+
### Elixir/Phoenix
- `PHX_SERVER: "true"` (required to start server in releases)
- `SECRET_KEY_BASE` generated via preprocessor
- `PHX_HOST` set to domain
+
## HA Checklist
+
| Item | Recommendation |
|------|---------------|
| Core package | **Serious Core** for production (better SLA, dedicated resources) |
@@ -11542,8 +16461,11 @@ Remove entirely or disable `enableSubdomainAccess`. Use VPN + pgAdmin/DBeaver lo
| Database mode | `mode: HA` for all managed services (immutable — plan before creation) |
| Min containers | `minContainers: 2` on all app services for zero-downtime deploys |
| Min containers | `minContainers: 2` on all app services for zero-downtime deploys |
+
## Health Check Pattern
+
Combined readiness + runtime health check for production services:
+
```yaml
zerops:
- setup: app
@@ -11559,7 +16481,9 @@ zerops:
path: /health
start: node server.js
```
+
Readiness check gates traffic during deploy. Health check runs continuously — unhealthy containers are restarted after 5-minute retry window.
+
## Gotchas
1. **HA is immutable**: Must delete and recreate service to switch modes
2. **Container filesystem survives restarts but is replaced on every deploy**: use external storage for persistent data
@@ -11568,12 +16492,16 @@ Readiness check gates traffic during deploy. Health check runs continuously —
5. **Debug mode leaks secrets**: Disable APP_DEBUG in production
6. **Missing health checks**: Load balancer can't route around unhealthy containers
+
----------------------------------------
# Guides > Public Access
+
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
+
### 1. Zerops Subdomains (`.zerops.app`)
- Shared HTTPS balancer (scalability bottleneck)
- Max upload: **50 MB**
@@ -11584,39 +16512,48 @@ Zerops offers three public access methods: zerops.app subdomains (dev only, 50MB
- **Port-specific subdomains**: If HTTP ports are defined in zerops.yml, each port gets its own subdomain: `{hostname}-{subdomainHost_prefix}-{port}.{subdomainHost_rest}`. Example: hostname `appdev`, subdomainHost `1df2.prg1.zerops.app`, port 3000 → actual URL `https://appdev-1df2-3000.prg1.zerops.app`. Port 80 omits the port suffix: `https://appdev-1df2.prg1.zerops.app`
- **Internal network fallback**: Every service is accessible internally via `http://{hostname}:{port}` (e.g., `http://appdev:3000`). Use this to verify the app is running when subdomain access is uncertain — `curl http://appdev:3000/health` from the ZCP container or any other service in the project
- Works for: nodejs, static, nginx, go, python, php, java, rust, dotnet, and all other runtime types
+
### 2. Custom Domains (Production)
- Per-project HTTPS balancer (2 containers, HA)
- Round-robin load balancing + health checks
- Full upload limit: 512 MB
- Requires IP address assignment:
+
| IP Type | Cost | Protocol | Notes |
|---------|------|----------|-------|
| Shared IPv4 | Free | HTTP/HTTPS only | Limited connections, shorter timeouts |
| Dedicated IPv4 | $3/30 days | All protocols | Non-refundable, auto-renews |
| IPv6 | Free | All protocols | Dedicated per project |
| IPv6 | Free | All protocols | Dedicated per project |
+
### 3. Direct Port Access
- Available for: Runtime services, PostgreSQL
- Port range: 10-65435 (80, 443 reserved)
- Protocols: TCP, UDP
- Configurable firewall: blacklist or whitelist per port
+
## DNS Setup (Custom Domain)
Point your domain to the project's IP:
- `A` record → Dedicated IPv4
- `AAAA` record → IPv6
- Shared IPv4: Requires **both A and AAAA** records (AAAA needed for SNI routing)
+
## Gotchas
1. **Shared IPv4 needs AAAA record**: Without AAAA, SNI routing fails — always add both A and AAAA
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
+
----------------------------------------
# Guides > Scaling
+
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
+
| Symptom | Scale type | Why |
|---------|-----------|-----|
| CPU/memory pressure on existing containers | Vertical (CPU/RAM) | More resources per container |
@@ -11624,7 +16561,9 @@ Zerops autoscales vertically (CPU/RAM/disk) and horizontally (container count).
| Disk filling up | Vertical (disk) | More storage per container |
| Latency-sensitive workload on SHARED CPU | CPU mode → DEDICATED | Guaranteed cores, no burstable throttling |
| Latency-sensitive workload on SHARED CPU | CPU mode → DEDICATED | Guaranteed cores, no burstable throttling |
+
## Applicability Matrix
+
| Service type | Vertical autoscaling | Horizontal scaling | Notes |
|---|---|---|---|
| **Runtime** (Node.js, Go, PHP, Python, Java, etc.) | Yes | Yes (1-10 containers) | Full autoscaling |
@@ -11635,38 +16574,55 @@ Zerops autoscales vertically (CPU/RAM/disk) and horizontally (container count).
| **Object storage** | No | No | Fixed size at creation, no verticalAutoscaling |
| **Docker** | No (manual, triggers VM restart) | Yes (VM count changeable, triggers restart) | No autoscaling at all |
| **Docker** | No (manual, triggers VM restart) | Yes (VM count changeable, triggers restart) | No autoscaling at all |
+
## Vertical Autoscaling
+
### CPU Modes
+
| Mode | Behavior | Best for |
|---|---|---|
| **SHARED** | Physical core shared with up to 10 tenants. Performance ranges 1/10 to 10/10 depending on neighbors | Dev, staging, low-traffic production |
| **DEDICATED** | Exclusive full physical core(s). Consistent performance | Production, CPU-intensive workloads |
| **DEDICATED** | Exclusive full physical core(s). Consistent performance | Production, CPU-intensive workloads |
+
- CPU mode can be changed **once per hour**
- **startCpuCoreCount**: cores allocated at container start (default: 2). Increase for apps with heavy initialization
+
### CPU Scaling Thresholds (DEDICATED mode only)
+
- **Min free CPU cores** (`minFreeCpuCores`): scale-up triggers when free capacity on a single core drops below this fraction, range 0.0-1.0 (default: 0.1 = 10%)
- **Min free CPU percent** (`minFreeCpuPercent`): scale-up triggers when total free capacity across all cores drops below this percentage, range 0-100 (default: 0, disabled)
+
### RAM Dual-Threshold System
+
RAM is monitored every **10 seconds**. Two independent thresholds control scale-up -- whichever provides **more free memory** wins:
+
| Threshold | Field | Default | Behavior |
|---|---|---|---|
| **Absolute** | `minFreeRamGB` | 0.0625 GB (64 MB) | Scale up when free RAM drops below this fixed amount |
| **Percentage** | `minFreeRamPercent` | 0% (disabled) | Scale up when free RAM drops below this % of granted RAM |
| **Percentage** | `minFreeRamPercent` | 0% (disabled) | Scale up when free RAM drops below this % of granted RAM |
+
Both thresholds serve dual purpose: prevent OOM crashes and preserve space for kernel disk caching. Swap is enabled as a safety net but does not replace proper threshold configuration.
+
**Higher wins example**: with 12 GB granted RAM, `minFreeRamGB=0.5` (500 MB buffer) and `minFreeRamPercent=5` (600 MB buffer) — the 600 MB threshold applies. As granted RAM grows, the percentage threshold automatically provides a larger buffer.
+
### Disk
- **Grows only -- never shrinks** (no scale-down). Set `minDisk = maxDisk` to disable.
+
### Resource Limits (Defaults)
+
| Resource | Min | Max |
|---|---|---|
| CPU cores | 1 | 8 |
| RAM | 0.125 GB | 48 GB |
| Disk | 1 GB | 250 GB |
| Disk | 1 GB | 250 GB |
+
PostgreSQL and MariaDB override RAM minimum to **0.25 GB**.
+
### Scaling Behavior Parameters
+
| Parameter | CPU | RAM | Disk |
|---|---|---|---|
| Collection interval | 10s | 10s | 10s |
@@ -11677,43 +16633,66 @@ PostgreSQL and MariaDB override RAM minimum to **0.25 GB**.
| Minimum step | 1 (0.1 cores) | 0.125 GB | 0.5 GB |
| Maximum step | 40 | 32 GB | 128 GB |
| Maximum step | 40 | 32 GB | 128 GB |
+
Scaling uses exponential growth: small increments initially, larger jumps under sustained high load.
+
**Scale-up behavior summary:**
- **RAM/Disk**: immediate scale-up when free resources drop below threshold (single measurement)
- **CPU**: requires 2 consecutive measurements below threshold (~20s window) to avoid spikes
- **Scale-down is conservative**: 3-5 consecutive measurements above threshold (60-300s depending on resource) — prevents flapping
+
### Spike Protection via minRam
+
Autoscaling reacts within 10-20 seconds. Compilation and package installation create RAM spikes faster than scaling can respond. Set `minRam` high enough to absorb the first spike WITHOUT relying on autoscaling:
+
- **Dev services** (compilation on container via SSH): `minRam` must cover the build tool peak — `npm install`, `go build`, `cargo build` spike within seconds
- **Stage/prod services** (pre-built artifacts): `minRam` only needs to cover the startup peak (JVM heap allocation, SSR warming)
+
Thresholds (`minFreeRamGB`, `minFreeRamPercent`) handle gradual load growth. They cannot protect against sub-10s spikes that exceed the total allocated RAM. See runtime guides for per-runtime `minRam` recommendations.
+
**Disabling autoscaling**: set **minimum = maximum** for any resource to pin it at a fixed value (e.g., `minRam: 2, maxRam: 2`).
+
## Horizontal Scaling
+
Applies to **runtimes and Linux containers only**. New containers are added when vertical scaling reaches configured maximums.
+
- **minContainers**: baseline always running (system range: 1-10)
- **maxContainers**: upper limit during peak (system range: 1-10)
- Set `minContainers = maxContainers` to disable horizontal autoscaling
+
**HA requirement**: applications must be stateless and handle distributed operation (no local file sessions, no local uploads).
+
### Managed Services (DB, Cache, Shared Storage)
+
Container count is **fixed by deployment mode**, set at creation, **immutable**:
+
| Mode | Containers | Use case |
|---|---|---|
| `NON_HA` | 1 | Development, non-critical |
| `HA` | 3 (on separate physical machines) | Production, automatic failover |
| `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.
+
PostgreSQL HA exposes read replica port **5433** for distributing SELECT queries.
+
## Configuring Thresholds via zerops_scale
+
Threshold parameters can be set via the `zerops_scale` MCP tool, not just import.yml:
+
```
zerops_scale serviceHostname="api" minFreeRamGB=0.5 minFreeRamPercent=5 minFreeCpuCores=0.2
```
+
All four threshold parameters (`minFreeRamGB`, `minFreeRamPercent`, `minFreeCpuCores`, `minFreeCpuPercent`) are optional and can be combined with any other scaling parameters in a single call.
+
## Docker Services
- Run in **VMs**, not containers. **No autoscaling** -- resources fixed at creation
- Changing resources or VM count triggers **VM restart** (downtime). Disk can only increase
- Consider runtime services or Linux containers if dynamic scaling is needed
+
## import.yml Syntax
+
```yaml
services:
# Runtime with full scaling
@@ -11732,6 +16711,7 @@ services:
minFreeRamPercent: 10
minDisk: 1
maxDisk: 20
+
# Managed DB (vertical only, no container settings)
- hostname: db
type: postgresql@16
@@ -11745,32 +16725,46 @@ services:
minDisk: 5
maxDisk: 100
```
+
## Strategy Presets
+
**Development** — SHARED CPU, min resources, 1 container. Cost-effective for dev/staging:
```
zerops_scale serviceHostname="api" cpuMode="SHARED" minCpu=1 maxCpu=2 minRam=0.25 maxRam=1 minContainers=1 maxContainers=1
```
+
**Production** — DEDICATED CPU, higher minimums, multiple containers for HA:
```
zerops_scale serviceHostname="api" cpuMode="DEDICATED" minCpu=2 maxCpu=8 minRam=2 maxRam=8 minContainers=2 maxContainers=6
```
+
**Burst workloads** — Wide autoscaling range, SHARED CPU:
```
zerops_scale serviceHostname="worker" cpuMode="SHARED" minCpu=1 maxCpu=8 minRam=1 maxRam=16 minContainers=1 maxContainers=10
```
+
## Common Mistakes
+
**DO NOT** add `verticalAutoscaling` to **object-storage** or **shared-storage** services in import.yml -- causes import failure. Object storage has a fixed `objectStorageSize` only. Shared storage is managed automatically.
+
**DO NOT** set `minContainers` or `maxContainers` for managed services (DB, cache, shared-storage) -- container count is fixed by `mode` (NON_HA=1, HA=3). Setting these causes import failure.
+
**DO NOT** use `DEDICATED` CPU for low-traffic or dev services -- wastes resources. Use `SHARED` and switch to `DEDICATED` only when consistent performance matters.
+
**DO NOT** set `minFreeRamGB: 0` and `minFreeRamPercent: 0` simultaneously -- the API rejects this with "Invalid custom autoscaling value". Always keep at least the default absolute threshold (0.0625 GB).
+
**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.
+
----------------------------------------
# Guides > Smtp
+
Only port **587** (STARTTLS) is allowed for outbound email — ports 25 and 465 are permanently blocked. Use an external email service.
+
## Port Configuration
| Port | Status | Protocol |
|------|--------|----------|
@@ -11778,7 +16772,9 @@ Only port **587** (STARTTLS) is allowed for outbound email — ports 25 and 465
| 465 | **Blocked** | Legacy SMTPS (deprecated) |
| **587** | **Allowed** | SMTP submission with STARTTLS |
| **587** | **Allowed** | SMTP submission with STARTTLS |
+
## Provider Configurations
+
| Provider | Host | Port | Username | Password |
|----------|------|------|----------|----------|
| Gmail | smtp.gmail.com | 587 | user@gmail.com | App password |
@@ -11788,6 +16784,7 @@ Only port **587** (STARTTLS) is allowed for outbound email — ports 25 and 465
| Mailgun | smtp.mailgun.org | 587 | postmaster@domain | Password |
| Amazon SES | `email-smtp.{region}.amazonaws.com` | 587 | Access key | Secret key |
| Amazon SES | `email-smtp.{region}.amazonaws.com` | 587 | Access key | Secret key |
+
## Configuration Example
```yaml
envVariables:
@@ -11795,36 +16792,105 @@ envVariables:
SMTP_PORT: "587"
SMTP_USER: apikey
envSecrets:
- SMTP_PASSWORD:
+ SMTP_PASSWORD:
```
+
## Gotchas
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
+
+----------------------------------------
+
+# Guides > Verify Web Agent Protocol
+
+
+Sub-agent dispatch protocol for end-to-end verification of a Zerops web
+service. The main agent reads `develop-verify-matrix` (atom) for which
+services need this protocol; the protocol body itself lives here so it
+ships only when fetched, not on every per-turn payload.
+
+Spawn one sub-agent per web-facing target. Substitute `{targetHostname}`
+and `{runtime}` with that service's values when constructing the prompt.
+
+---
+
+## Sub-agent dispatch prompt
+
+```
+Agent(model="sonnet", prompt="""
+Verify Zerops service "{targetHostname}" ({runtime}) works for end users.
+
+## Protocol
+1. `zerops_verify serviceHostname="{targetHostname}"` — infrastructure baseline
+2. If NOT healthy → VERDICT: FAIL (cite failed checks from zerops_verify response)
+3. `zerops_discover service="{targetHostname}"` — get subdomainUrl or connection info
+4. Determine reachable URL:
+ - subdomainUrl available → use it (public HTTPS)
+ - no subdomain, no custom domain → VERDICT: UNCERTAIN (cannot reach from outside)
+ - unreachable after timeout → VERDICT: UNCERTAIN
+5. `agent-browser open {url}`
+6. `agent-browser snapshot` — accessibility tree for AI analysis
+7. Evaluate: does the page render meaningful content?
+ - Interactive elements (buttons, links, forms)?
+ - Text content (headings, paragraphs)?
+ - Or empty/broken (empty root div, error page, blank screen)?
+8. If concerns: `agent-browser eval "JSON.stringify(Array.from(document.querySelectorAll('script[src]')).map(s=>s.src))"` for loaded scripts
+9. For SPAs: `agent-browser eval "window.__errors || []"` AND check if console has errors
+
+## Rules
+- zerops_verify unhealthy/degraded → always VERDICT: FAIL (never override infra checks)
+- HTTP 401/403 with rendered content (login page, auth challenge) → VERDICT: PASS (auth is working correctly)
+- HTTP 401/403 with empty body → VERDICT: UNCERTAIN (cannot determine if intentional)
+- zerops_verify healthy + page empty/broken → VERDICT: FAIL (cite what you see)
+- zerops_verify healthy + page renders real content → VERDICT: PASS
+- agent-browser unavailable or URL unreachable → VERDICT: UNCERTAIN
+
+## Output (mandatory format)
+### Infrastructure
+zerops_verify status and check summary
+
+### Application
+what you observed — DOM content, JS errors, visual state
+
+### Evidence
+accessibility tree excerpt or error details
+
+### VERDICT: PASS or FAIL or UNCERTAIN — one-line justification
+""")
+```
+
+
----------------------------------------
# Guides > Vpn
-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.
+
+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
```bash
-zcli vpn up # Connect
-zcli vpn up --auto-disconnect # Auto-disconnect on terminal close
-zcli vpn up --mtu 1350 # Custom MTU (default 1420)
+zcli vpn up # Connect
+zcli vpn up --auto-disconnect # Auto-disconnect on terminal close
+zcli vpn up --mtu 1350 # Custom MTU (default 1420)
zcli vpn down # Disconnect
```
+
## Behavior
- All services accessible via hostname (e.g., `db`, `api`) — `.zerops` suffix optional
- **One project at a time** — connecting to another disconnects the current
- Automatic reconnection with daemon
- **Environment variables NOT available** through VPN — use GUI or API to read them
+
## Hostname Resolution
- Both plain hostname (`db`) and suffixed (`db.zerops`) work — VPN configures a DNS search domain
- Plain hostname is resolved via the `.zerops` search domain automatically (e.g., `db` → `db.zerops`)
- Example: `postgresql://user:pass@db:5432/mydb` or `postgresql://user:pass@db.zerops:5432/mydb`
- Note: CLI tools like `dig`, `nslookup`, `host` bypass the system resolver and may show false NXDOMAIN — use `dscacheutil -q host -a name db` on macOS to verify, or just test with `nc -zv db 5432`
+
## Troubleshooting
+
| Problem | Solution |
|---------|----------|
| Interface already exists | `zcli vpn down` then `zcli vpn up` |
@@ -11833,21 +16899,29 @@ zcli vpn down # Disconnect
| Conflicting VPN | Use `--mtu 1350` |
| Ubuntu 25.* issues | Install AppArmor utilities |
| Ubuntu 25.* issues | Install AppArmor utilities |
+
## Gotchas
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.
+
----------------------------------------
# Guides > Zerops Yaml Advanced
+
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.
+
---
+
## Health Check Behavior
+
Health checks run **continuously** on every container after startup. Two types (mutually exclusive):
+
- **`httpGet`**: GET to `localhost:{port}{path}`. Success = 2xx. Runs **inside** the container. Use `host` for custom Host header, `scheme: https` only if app requires TLS.
- **`exec`**: Shell command, success = exit 0. Has access to all env vars. Use YAML `|` for multi-command scripts.
+
| Parameter | Purpose |
|-----------|---------|
| `failureTimeout` | Seconds of consecutive failures before container restart |
@@ -11855,11 +16929,17 @@ Health checks run **continuously** on every container after startup. Two types (
| `recoveryTimeout` | Seconds of success before restarted container receives traffic again |
| `execPeriod` | Interval in seconds between check attempts |
| `execPeriod` | Interval in seconds between check attempts |
+
**Failure sequence**: repeated failures -> `disconnectTimeout` removes from LB -> `failureTimeout` triggers restart -> `recoveryTimeout` gates traffic reconnection.
+
**DO NOT** configure both `httpGet` and `exec` in the same block.
+
---
+
## Readiness Check Behavior
+
Runs **only during deployments** to gate traffic switch to a new container.
+
```yaml
deploy:
readinessCheck:
@@ -11867,19 +16947,29 @@ deploy:
failureTimeout: 60
retryPeriod: 10
```
+
**How it works**: Checks the **new** container at `localhost`. Until it passes, traffic stays on the old container. After `failureTimeout`, deploy fails and the old container remains active.
+
**DO NOT** confuse with healthCheck -- readiness gates a deploy; healthCheck monitors continuously after.
+
> **Dev/stage distinction**: In dev+stage pairs, healthCheck and readinessCheck belong ONLY on the stage entry. Dev services use `start: zsc noop --silent` — the agent controls server lifecycle via SSH. Adding healthCheck to dev causes unwanted container restarts during iteration.
+
---
+
## temporaryShutdown
+
| Value | Behavior | Downtime |
|-------|----------|----------|
| `false` (default) | New containers start first, old removed after readiness | None (zero-downtime) |
| `true` | All old containers stop, then new ones start | Yes |
| `true` | All old containers stop, then new ones start | Yes |
+
Use `true` when: exclusive DB migration access needed, or brief downtime acceptable. Use `false` for: production web services, APIs, user-facing apps.
+
---
+
## Crontab Execution
+
```yaml
run:
crontab:
@@ -11888,11 +16978,17 @@ run:
workingDir: /var/www/html
allContainers: false
```
+
Parameters: `command` (required), `timing` (required, 5-field cron: `min hour dom mon dow`), `workingDir` (default `/var/www`), `allContainers` (`false` = one container, `true` = all containers).
+
Cron runs inside the runtime container with full env var access. When `allContainers: false`, Zerops picks **one** container (good for DB jobs). Use `true` for cache clearing or log rotation everywhere. Minimum granularity is 1 minute.
+
---
+
## startCommands (Background Processes)
+
Runs **multiple named processes** in parallel. **Mutually exclusive** with `start`.
+
```yaml
run:
startCommands:
@@ -11903,9 +16999,13 @@ run:
initCommands:
- litestream restore -if-replica-exists -if-db-not-exists $DB_NAME
```
+
Each entry: `command` (required), `name` (required), `workingDir` (optional), `initCommands` (optional, per-process init). **DO NOT** use both `start` and `startCommands`.
+
---
+
## initCommands vs prepareCommands
+
| Feature | `run.initCommands` | `run.prepareCommands` |
|---------|-------------------|----------------------|
| **When** | Every container start/restart | Only when building runtime image |
@@ -11914,19 +17014,28 @@ Each entry: `command` (required), `name` (required), `workingDir` (optional), `i
| **Deploy files** | Present in `/var/www` | **Not available** -- DO NOT reference app files |
| **Reruns on** | Restart, scaling, deploy | Only when commands change |
| **Reruns on** | Restart, scaling, deploy | Only when commands change |
+
---
+
## envReplace (Variable Substitution)
+
Replaces placeholders in deployed files with env var values at deploy time.
+
```yaml
run:
envReplace:
delimiter: "%%"
target: [./config/, ./templates/settings.json]
```
+
File containing `%%DATABASE_URL%%` gets the placeholder replaced with the actual value. Multiple delimiters supported: `delimiter: ["%%", "##"]`. Use for: secrets in config files, PEM certificates, frontend configs.
+
**Directory targets are NOT recursive** -- `./config/` processes only files directly in that directory. Specify subdirectories explicitly.
+
---
+
## routing (Static Services Only)
+
```yaml
run:
routing:
@@ -11938,13 +17047,18 @@ run:
- for: "/*"
values: { X-Frame-Options: "'DENY'" }
```
+
- **`cors`**: Sets Access-Control-Allow-Origin. `"*"` auto-converted to `'*'`
- **`redirects[]`**: `from` (wildcards `*`), `to`, `status`, `preservePath`, `preserveQuery`
- **`headers[]`**: `for` (path pattern), `values` (header key-value pairs)
- **`root`**: Custom root directory
+
**DO NOT** use on non-static services -- silently ignored.
+
---
+
## extends (Configuration Inheritance)
+
```yaml
zerops:
- setup: base
@@ -11954,7 +17068,9 @@ zerops:
extends: base
run: { envVariables: { NODE_ENV: production } }
```
+
Supports single parent (`extends: base`) or multiple parents (`extends: [base, logging]`) -- later parents override earlier ones:
+
```yaml
zerops:
- setup: base
@@ -11965,65 +17081,85 @@ zerops:
extends: [base, logging]
run: { envVariables: { NODE_ENV: production } }
```
+
Configuration is **merged at the section level** -- child values override parent values within each section (build, run, deploy), but unspecified sections inherit from parent. Must reference another `setup` name in the same file.
+
## Base Images
+
Available runtimes and versions are listed in **Service Stacks (live)** -- injected by `zerops_knowledge` and workflow responses. Some key rules:
+
- PHP: build `php@X`, run `php-nginx@X` or `php-apache@X` (different bases)
- Deno, Gleam: REQUIRES `os: ubuntu` (not available on Alpine)
- Static sites: build `nodejs@latest`, run `static`
- `@latest` = newest stable version
+
---
+
----------------------------------------
# Help > Contacts
+
:construction: **We apologize for any inconvenience, we are doing our best to finish this documentation ASAP to make your Zerops experience a blast!** :construction:
+
In the meantime, if you have any troubles setting up your application, or if you find a specific part of the documentation missing, don't hesitate to contact our team via:
+- [Discord (recommended)](https://discord.com/invite/WDvCZ54) — The fastest way to get help from our team and other community members.
+- [Report an issue](https://github.com/zeropsio/docs/issues/new/choose) — If you want to report an issue, please click here.
+- [Email](mailto:support@zerops.io) — Reach the team directly, this might take longer as the community won
+- [Twitter](https://x.com/zeropsio) — Reach out to us by direct messagining or by tagging @zeropsio in your tweets for a response.
+
+
----------------------------------------
# Help > Faq
+
Get quick answers to your related questions about Zerops from frequently asked questions we get asked.
+
### General
- Question: Where can I find the Zerops Dashboard GUI?
-Answer:
- You can access the Zerops Dashboard GUI directly at app.zerops.io.
-
- Question: How much does it cost to get started?
-Answer:
- It's free to get started, and no credit card is required! However, we
- recommend visiting our pricing page to explore the options that best suit your needs.
+
+ **Question: Where can I find the Zerops Dashboard GUI?**
+
+You can access the Zerops Dashboard GUI directly at [app.zerops.io](https://app.zerops.io).
+
+ **Question: How much does it cost to get started?**
+
+It's free to get started, and no credit card is required! However, we
+ recommend visiting our [pricing page](/company/pricing) to explore the options that best suit your needs.
+
We also have a calculator on our pricing page that can help you estimate the cost of your project.
-
- Question: Where are your servers located?
-Answer:
- Our infrastructure spans multiple regions. In Europe, we operate our own high-tier
- data center in Prague, Czech Republic, running on bare metal servers managed by
- vshosting's senior admin team — vshosting.eu,
+
+ **Question: Where are your servers located?**
+
+Our infrastructure spans multiple regions. In Europe, we operate our own high-tier
+ data center in **Prague**, Czech Republic, running on bare metal servers managed by
+ vshosting's senior admin team — [vshosting.eu](https://vshosting.eu/),
one of the largest providers of managed hosting in Europe. In the US, we have servers
- in New York, with additional US East Coast capacity on its way through a trusted
+ in **New York**, with additional US East Coast capacity on its way through a trusted
infrastructure partner.
- Stay tuned for updates on our Discord server and checkout our roadmap!
-
- Question: Why should I use Zerops over Self-Hosted PaaS?
-Answer:
- We have a detailed article discussing whether you should go for a Self-hosted PaaS → [The rise of self-hosted PaaS — is $5 VPS all you need?](https://zerops.io/article/the-rise-of-self-hosted-paa-s-is-5-vps-all-you-need).
-
- Question: How do I change my email?
-Answer:
- Navigate to the main menu in the Zerop GUI (with your icon) and add a new user with the selected email to your team.
-
- Question: I have more questions. Where can I reach out to get help?
-Answer:
- You can reach us on our Discord server for support. For additional contact options, please visit our contacts page.
-
+
+ Stay tuned for updates on our [Discord server](https://docs.zerops.io/discord) and checkout our [roadmap](https://zerops.io/#about)!
+
+ **Question: Why should I use Zerops over Self-Hosted PaaS?**
+
+We have a detailed article discussing whether you should go for a Self-hosted PaaS → [The rise of self-hosted PaaS — is $5 VPS all you need?](https://zerops.io/article/the-rise-of-self-hosted-paa-s-is-5-vps-all-you-need).
+
+ **Question: How do I change my email?**
+
+Navigate to the main menu in the Zerop GUI (with your icon) and add a new user with the selected email to your team.
+
+ **Question: I have more questions. Where can I reach out to get help?**
+
+You can reach us on our [Discord server](https://docs.zerops.io/discord) for support. For additional contact options, please visit our [contacts page](https://docs.zerops.io/help/contacts).
+
----------------------------------------
# Homepage
+
export const runtimes = [
{ name: "Node.js", link: "/nodejs/overview", icon: },
{ name: "PHP", link: "/php/overview", icon: },
@@ -12039,11 +17175,13 @@ export const runtimes = [
{ name: "Nginx", link: "/nginx/overview", icon: },
{ name: "Static", link: "/static/overview", icon: },
]
+
export const containers = [
{ name: "Ubuntu", link: "/ubuntu/overview", icon: },
{ name: "Alpine", link: "/alpine/overview", icon: },
{ name: "Docker", link: "/docker/overview", icon: },
]
+
export const databases = [
{ name: "PostgreSQL", link: "/postgresql/overview", icon: },
{ name: "MariaDB", link: "/mariadb/overview", icon: },
@@ -12057,58 +17195,109 @@ export const databases = [
{ name: "ClickHouse", link: "/clickhouse/overview", icon: },
{ name: "KeyDB", link: "/keydb/overview", icon: },
]
+
export const storages = [
{ name: "Object storage", link: "/object-storage/overview", icon: },
{ name: "Shared storage", link: "/shared-storage/overview", icon: },
]
+
+
+
Zerops is a **developer-first Platform-as-a-Service**, running on bare metal, with every part built from scratch. Zerops aims to be the perfect mix of **developer experience**, **flexibility**, **scalability** and **affordability**, making it a great fit for applications of any size, complexity and traffic.
+
## Natively supported services
+
### Runtimes & web servers
+
For these services Zerops provides pre-prepared build and runtime images and flexible pipeline that allows you to modify them and build your applications.
+
### Linux containers & VMs
+
These services can be deployed either as plain Linux containers or using Docker images, giving you flexibility to run any application or service.
+
### Databases, search engines & message brokers
+
These services are fully managed by Zerops and offered in highly available and single container modes.
+
### Storages
+
Fully managed S3 compatible storage running on a separate infrastructure and persistent disk that can be mounted to multiple services.
+
## Quicklinks
+
+- [zCLI](/references/cli)
+- [zerops.yaml](/zerops-yaml/specification)
+- [Import file](/references/import)
+
## Feature highlights
+
Four concepts that play together to make Zerops developer-first and live up to the claim "no matter the size or environment".
+
### ➡️ Custom dedicated infrastructure deployed with each project
+
Zerops is made of three levels: **project** -> **service** -> **container**. For each project Zerops deploys dedicated **core services**, these consist of:
+
- **L3 balancer** with a firewall and unique IP addresses assigned to it, this serves as the main entry point from the internet,
- **Logger** and **Statistics** containers that gather logs and resource metrics from all services inside the project and allow for log forwarding
- **L7 load balancer** that handles and routes http traffic, SSL termination and SSL certificates
+
User services (which consist of one or more containers) inside the project share a private network created with VXLAN, have resources isolated with cgroups and can securely communicate with each other simply by using the hostname and ports and read and reference each other's environment variables.
+
:::tip[**What does this mean for you?**]
+
You get a fully managed, professional infrastructure setup that will scale no matter how much traffic you get and deals with all the networking, balancing and security stuff, so you can just focus on your actual applications.
-Read more about the project infrastructure
+
+[Read more about the project infrastructure](/features/infrastructure)
+
:::
+
### ➡️ Granular resource configuration, autoscaling and high availability of services
+
Zerops has fully automatic horizontal and vertical scaling with configuration steps as small as 0.125 GB RAM and 1 CPU core. Your runtime services can go from a single container with 0.25 RAM and 1 CPU core to 10 containers each with 32 GB RAM and 10 CPU cores and then back in a matter of minutes. At the same time, all database and storage services are offered in well-crafted setups that go through performance optimizations while scaling and are available in both non-HA (single container) and high availability (multiple containers and balancers) modes.
+
:::tip[**What does this mean for you?**]
+
You won't ever overprovision or underprovision your resources and your services will always have the exact resources they need. There won't be any cutting corners like sharing too few CPU cores between too many services. You will be able to rely on professional, reliable and highly available database setups with auto-repairing abilities that will scale along with your applications.
-Read more about autoscaling and high availability
+
+[Read more about autoscaling and high availability](/features/scaling)
+
:::
+
### ➡️ Full Linux OS containers with a powerful, flexible build and deploy pipeline
+
Zerops uses Incus to create containers, which means that you get a full Linux OS, either Ubuntu or Alpine, depending on your choices. This provides the perfect middle ground between a containerized process (Docker) and a full-fledged VM (Proxmox). Zerops provides build and runtime bases for all the popular runtime technologies and a powerful and flexible pipeline that allows you to modify and cache both the build and runtime images. This circumvents the need for Docker registries. The pipeline can be triggered either automatically, by connecting the service with GitHub or GitLab repositories, or manually using our CLI - either for triggering from your machine, or from any existing CI/CD process.
+
:::tip[**What does this mean for you?**]
+
You get a built-in powerful and flexible pipeline to modify build and runtime images and deploy your code, without any downtime. It can be used standalone or easily plugged into any existing CI/CD process.
-Read more about the build and deploy pipeline
+
+[Read more about the build and deploy pipeline](/features/pipeline)
+
:::
+
### ➡️ Pricing model that doesn't get in the way of good development practices
+
"Simple and predictable pricing"... is what others say and what we actually do. In Zerops, cost per hardware resource (CPU, RAM, Disk) is 3-5x cheaper than with popular alternatives. And there are no plans, no feature tiers, no fees for seats. PaaS is just hardware with a cherry and bow on top, so why would we charge you for anything else but hardware resources?
+
:::tip[**What does this mean for you?**]
+
You get a powerful managed platform with all the best features unlocked for a price that's nearly on par with VPS. You can create as many environments as you need, even one for each developer working on a project, all with the same infrastructure as production, so they can utilize Zerops for their local development. No more "but it works on my machine".
+
:::
+
+
----------------------------------------
# Java > How To > Build Pipeline
+
Zerops provides a customizable build and runtime environment for your Java application.
+
## Add zerops.yaml to your repository
+
Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:
+
```yaml
zerops:
# define hostname of your service
@@ -12117,47 +17306,60 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: java@latest
+
# OPTIONAL. Set the operating system for the build environment.
# os: ubuntu
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Build your application
buildCommands:
- ./mvnw clean install
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles: target/app.jar
+
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
# cache: some_file
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: java@latest
+
# OPTIONAL. Sets the internal port(s) your app listens on:
ports:
# port number
- port: 8080
+
# OPTIONAL. Customize the runtime Java environment by installing additional
# dependencies to the base Java runtime environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Run one or more commands each time a new runtime container
# is started or restarted. These commands are triggered before
# your Java application is started.
# initCommands:
# - rm -rf ./cache
+
# REQUIRED. Your Java application start command
start: java -jar target/app.jar
```
+
The top-level element is always `zerops`.
+
### Setup
+
The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:
+
```yaml
zerops:
# definition for app service
@@ -12168,6 +17370,7 @@ zerops:
deploy: ...
# required
run: ...
+
# definition for api service
- setup: api
# optional
@@ -12177,11 +17380,17 @@ zerops:
# required
run: ...
```
+
Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.
+
## Build pipeline configuration
+
### base
+
_REQUIRED._ Sets the base technology for the build environment.
+
Following options are available for Java builds:
+
```yaml
zerops:
# hostname of your service
@@ -12192,13 +17401,19 @@ zerops:
base: java@latest
...
```
+
+
The base build environment contains {data.alpine.default}, the selected version
- of Java, Zerops command line tool, `git` and
+ of Java, [Zerops command line tool](/references/cli), `git` and
`wget`.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -12212,34 +17427,52 @@ zerops:
- zsc add nodejs@latest
...
```
+
See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).
+
To customize your build environment use the [prepareCommands](#preparecommands) attribute.
+
:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::
+
### os
+
_OPTIONAL._ Sets the operating system for the build environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customized.
:::
+
:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::
+
### prepareCommands
+
_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.
+
The base build environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- selected version of Java defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `git` and `wget`
+
To install additional packages or tools add one or more prepare commands:
+
```yaml
zerops:
# hostname of your service
@@ -12248,6 +17481,7 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: java@latest
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
prepareCommands:
@@ -12255,20 +17489,31 @@ zerops:
- curl something else
...
```
+
When the first build is triggered, Zerops will
+
1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order
+
The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.
+
:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/java/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### buildCommands
+
_OPTIONAL._ Defines build commands.
+
```yaml
zerops:
# hostname of your service
@@ -12277,96 +17522,138 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: java@latest
+
# OPTIONAL. Build your application
buildCommands:
- ./mvnw clean install
...
```
+
Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.
+
Before the build commands are triggered the build container contains:
+
1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code
+
#### Run build commands as a single shell instance
+
Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it. Suppose your `mvnw` executable file is in a `cmd` directory.
+
```yaml
buildCommands:
- |
cd cmd
./mvnw clean install
```
+
#### Run build commands as a separate shell instances
+
When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command. Suppose your `mvnw` executable file is in a `cmd` directory.
+
```yaml
buildCommands:
- cd cmd
- ./cmd/mvnw clean install
```
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/java/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the `-X` debug option.
+
```yaml
buildCommands:
- ./mvnw -X clean install
```
+
If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.
+
### deployFiles
-_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use `.deployignore` file.
+
+_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.
+
```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- app.jar
```
+
Determines files or folders produced by your build, which should be deployed to your runtime service containers.
+
The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.
+
The files/folders will be placed into `/var/www` folder in runtime, e.g. `./src/assets/fonts` would result in `/var/www/src/assets/fonts`.
+
#### Examples
+
Deploys a folder, and a file from the project root directory:
+
```yaml
deployFiles:
- api
- app.jar
```
+
Deploys the whole content of the build container:
+
```yaml
deployFiles: .
```
+
Deploys a folder, and a file in a defined path:
+
```yaml
deployFiles:
- ./path/to/file.txt
- ./path/to/dir/
```
+
#### How to use a wildcard in the path
+
Zerops supports the `~` character as a wildcard for one or more folders in the path.
+
Deploys all `file.txt` files that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/file.txt
```
+
Deploys all folders that are located in any path that begins with `/path/to/`
+
```yaml
deployFiles: ./path/to/~/
```
+
Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/
```
+
:::note Example
By default, `./src/assets/fonts` deploys to `/var/www/src/assets/fonts`, keeping the full path. Adding `~`, like `./src/assets/~fonts`, shortens it to `/var/www/fonts`
:::
#### .deployignore
-Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as `.gitignore`.
+
+Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as [`.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format).
+
To ignore a specific file or directory path, start the pattern with a forward slash (`/`). Without the leading slash, the pattern will match files with that name in any directory.
+
:::tip
For consistency, it's recommended to configure both your `.gitignore` and `.deployignore` files with the same patterns.
:::
+
Examples:
+
```yaml title="zerops.yaml"
zerops:
- setup: app
build:
deployFiles: ./
```
+
```text title=".deployignore"
/src/file.txt
```
@@ -12378,22 +17665,33 @@ This example above ignores `file.txt` in ANY directory named `src`, such as:
- `/src/file.txt`
- `/folder2/folder3/src/file.txt`
- `/src/src/file.txt`
+
:::note
-`.deployignore` file also works with `zcli service deploy` command.
+`.deployignore` file also works with [`zcli service deploy`](/references/zcli/commands#deploy) command.
:::
+
### cache
+
_OPTIONAL._ Defines which files or folders will be cached for the next build.
+
```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```
+
The cache attribute helps optimize build times by preserving specified files between builds.
+
The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).
+
Learn more about the [build cache system](/features/build-cache) in Zerops.
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the build environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -12402,6 +17700,7 @@ zerops:
build:
base: java@latest
…
+
# OPTIONAL. Defines the env variables for the build environment:
envVariables:
DB_NAME: db
@@ -12409,12 +17708,18 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/java/how-to/env-variables) in Zerops.
+
## Runtime configuration
+
### base
+
_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Java version for your runtime.
+
Following options are available for Java builds:
+
```yaml
zerops:
# hostname of your service
@@ -12424,18 +17729,25 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: java@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: java@latest
...
```
+
+
The base runtime environment contains {data.alpine.default}, the selected major
version of Java, Zerops command line tool, git` and `wget`.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -12445,6 +17757,7 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: java@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
@@ -12454,44 +17767,75 @@ zerops:
- zsc add nodejs@latest
...
```
+
See the full list of supported [run base environments](/zerops-yaml/base-list).
+
To customize your build environment use the `prepareCommands` attribute.
+
### os
+
_OPTIONAL._ Sets the operating system for the runtime environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customized.
:::
+
### ports
+
_OPTIONAL._ Specifies one or more internal ports on which your application will listen.
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
For example, to connect to a Java service with hostname = "app" and port = 8080 from another service of the same project, simply use `app:8080`. Read more about [how to access a Java service](/references/networking/internal-access#basic-service-communication).
+
Each port has following attributes:
-
- Parameter
- Description
-
- port
- Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
-
- protocol
- Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
-
- httpSupport
- Optional. httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of public access. httpSupport = true is available only in combination with the TCP protocol.
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
+
+
+
protocol
+
Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
+
+
+
httpSupport
+
Optional.httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). httpSupport = true is available only in combination with the TCP protocol.
+
+
+
+
### prepareCommands
+
_OPTIONAL._ Customizes the Java runtime environment by installing additional dependencies or tools to the runtime base environment.
+
+
The base Java environment contains {data.alpine.default}, the selected major
- version of Java, Zerops command line tool and
+ version of Java, [Zerops command line tool](/references/cli) and
`git` and `wget`. To install additional packages or tools add one or more
prepare commands:
+
+
```yaml
zerops:
# hostname of your service
@@ -12499,6 +17843,7 @@ zerops:
# ==== how to build your application ====
build:
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -12508,27 +17853,45 @@ zerops:
- curl something else
...
```
+
When the first deploy with a defined prepare attribute is triggered, Zerops will
+
1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order
+
:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/java/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.
+
#### Cache of your custom runtime environment
+
Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:
+
1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.
+
To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.
+
When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### Copy folders or files from your build container
+
+
The prepare runtime container contains {data.alpine.default}, the selected
- major version of Java, Zerops command line tool and `git` and `wget`.
+ major version of Java, [Zerops command line tool](/references/cli) and `git` and `wget`.
+
+
The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).
+
```yaml
zerops:
# hostname of your service
@@ -12537,6 +17900,7 @@ zerops:
build:
...
addToRunPrepare: ./runtime-config.yaml
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -12546,15 +17910,20 @@ zerops:
- curl something else
...
```
+
In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.
+
### initCommands
+
_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Run one or more commands each time a new runtime container
@@ -12563,22 +17932,35 @@ zerops:
initCommands:
- rm -rf ./cache
```
+
These commands are triggered in the runtime container before your Java application is started via the [start command](#start).
+
:::note
`run.initCommands` run in the `/var/www` directory.
:::
+
Use init commands to clean or initialise your application cache or similar operations.
+
:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/java/how-to/scaling) or when a runtime container is restarted).
+
Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::
+
#### Command exit code
+
If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/java/how-to/logs#runtime-log) to troubleshoot the error.
+
#### Single or separated shell instances
+
You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the runtime environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -12592,57 +17974,84 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/java/how-to/env-variables) in Zerops.
+
### start
+
_REQUIRED._ Defines the start command for your Java application.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Java application start command
start: java -jar target/app.jar
```
+
We recommend starting your Java application using `java -jar target/app.jar`.
+
### health check
+
_OPTIONAL._ Defines a health check.
+
`healthCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the health check to request a local URL using a HTTP GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Java application start command
start: java -jar target/app.jar
+
# OPTIONAL. Define a health check with a HTTP GET request option.
# Configures the check on http://127.0.0.1:80/status
healthCheck:
@@ -12650,30 +18059,47 @@ zerops:
port: 80
path: /status
```
+
#### exec
+
Configures the health check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
Defines a local command to be run.
- The command has access to the same environment variables as your Java application.
+
+ The command has access to the same [environment variables](/java/how-to/create#set-secret-environment-variables) as your Java application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Java application start command
start: java -jar target/app.jar
+
# OPTIONAL. Define a health check with a shell command.
healthCheck:
exec:
@@ -12682,13 +18108,18 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
### crontab
+
_OPTIONAL._ Defines cron jobs.
+
Setup cron jobs in the following format:
+
```yaml
zerops:
# define hostname of your service
- setup: app
+
# ==== how to run your application ====
run:
crontab:
@@ -12697,40 +18128,62 @@ zerops:
# REQUIRED. Sets the interval time to execute:
timing: "0 * * * *"
```
+
Read more about setting up [cron](/zerops-yaml/cron) in Zerops.
+
## Deploy configuration
+
### readiness check
+
_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/java/how-to/deploy-process#readiness-checks) in Zerops.
+
`readinessCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the readiness check to request a local URL using a http GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -12739,30 +18192,48 @@ zerops:
httpGet:
port: 80
path: /status
+
# ==== how to run your application ====
run: ...
```
+
Read more about how the [readiness check works](/java/how-to/deploy-process#readiness-checks) in Zerops.
+
#### exec
+
Configures the readiness check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
Defines a local command to be run.
- The command has access to the same environment variables as your Java application.
+
+ The command has access to the same [environment variables](/java/how-to/create#set-secret-environment-variables) as your Java application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -12774,8 +18245,10 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
Read more about how the [readiness check works](/java/how-to/deploy-process#readiness-checks) in Zerops.
+
----------------------------------------
# Java > How To > Build Process
@@ -12792,35 +18265,60 @@ Read more about how the [readiness check works](/java/how-to/deploy-process#read
# Java > How To > Create
+
Zerops provides a Java runtime service with extensive build support. Java runtime is highly scalable and customisable to suit both development and production.
+
## Create Java service using Zerops GUI
+
First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Java service:
+
+[Video: /vids/services/java.webm](/vids/services/java.webm)
+
### Choose Java version
+
Following Java versions are currently supported:
+
:::info
You can [change](/java/how-to/upgrade) the major version at any time later.
:::
+
### Set a hostname
+
Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.
+
#### Limitations:
+
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::
+
### Set secret environment variables
+
Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.
+
Setting the secret environment variables is optional. You can set them later in Zerops GUI.
+
Read more about [different types of env variables](/java/how-to/env-variables#service-env-variables) in Zerops.
+
## Create Java service using zCLI
+
zCLI is the Zerops command-line tool. To create a new Java service via the command-line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/java/how-to/create#create-a-project-description-file)
3. [Create a project with a Java and PostgreSQL service](#full-example)
+
### Create a project description file
+
Zerops uses a yaml format to describe the project infrastructure.
+
#### Basic example:
+
Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -12841,13 +18339,18 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes your future project infrastructure. The project will contain one Java version 1 service with default [auto scaling](/java/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/java/how-to/build-pipeline#ports). Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
#### Full example:
+
Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:
+
```yaml
# basic project data
project:
@@ -12892,98 +18395,143 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain a Java service and a [PostgreSQL](/postgresql/overview) service.
+
Java service with "app" hostname, the internal port(s) the service listens on will be defined later in the zerops.yaml. Java service will run on version 1 with a custom vertical and horizontal scaling. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
hostname
+
The unique service identifier.
-
+
The hostname of the new database will be set to the `hostname` value.
-
- Limitations:
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+ Limitations:
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
type
+
Specifies the service type and version.
-
+
See what [Java service types](/references/import-yaml/type-list#runtime-services) are currently supported.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto scaling parameters.
-
+
+
+
+
verticalAutoscaling
+
+ Optional. Defines [custom vertical auto scaling parameters](/java/how-to/create#set-auto-scaling-configuration).
+
All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
- minContainers
-
- Optional. Default = 1. Defines the minimum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
- cpuMode
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
- minCpu/maxCpu
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
- minRam/maxRam
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
- minDisk/maxDisk
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
minContainers
+
+ Optional. Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/java/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- maxContainers
-
- Defines the maximum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
maxContainers
+
+ Defines the maximum number of containers for [horizontal autoscaling](/java/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- envSecrets
-
- Optional. Defines one or more secret env variables as a key value map. See env variable restrictions.
-
+
+
+
+
envSecrets
+
+ Optional. Defines one or more secret env variables as a key value map. See env variable [restrictions](/java/how-to/env-variables#env-variable-restrictions).
+
+
+
+
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add Java service to an existing project
+
#### Example:
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -13004,33 +18552,38 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Java service version 1 with default [auto scaling](/java/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the import.yaml file is 100 kB.
+
----------------------------------------
# Java > How To > Customize Runtime
-Build tools: When you need Maven, Gradle, or other build tools not included by default',
- 'Native libraries: When your Java dependencies require system libraries that aren\'t in the default environment',
- 'Application servers: When you need Tomcat, Jetty, or other application servers',
- 'Different base OS: When you need Ubuntu instead of Alpine for specific compatibility requirements'
-]} />
+
----------------------------------------
@@ -13084,14 +18637,23 @@ Build tools: When you need Maven, Gradle, or other build tools not included by d
# Java > Overview
+
# Java overview
+
[Java ↗](https://www.java.com/en/) is a high-level, class-based, object-oriented programming language that is designed to have as few implementation dependencies as possible.
+
As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-java-hello-world), a **_recipe_**, containing the most simple Java web application. The repo will be used as a source from which the app will be built.
- This is the most bare-bones example of Java running in Zerops — as few libraries as possible,
+
+### 🚀 Feel free to deploy the recipe yourself
+
+This is the most bare-bones example of Java running in Zerops — as few libraries as possible,
just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.
-
+
+ [Deploy "java" recipe on Zerops](https://app.zerops.io/recipe/?lf=java)
+
1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-java-hello-world/blob/main/import-project/description.yaml)):
+
```yaml
project:
name: my-first-project
@@ -13103,97 +18665,162 @@ services:
buildFromGit: https://github.com/zeropsio/recipe-java-hello-world@main
enableSubdomainAccess: true
```
+
3. Click on **Import project** and wait until all pipelines have finished.
+
**That's it, your application is now up and running! :star: Let's check it works:**
+
1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://helloworld-24-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see
+
```
Hello, World!
```
+
:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::
+
## How to start
+
+- [Care for details?](/java/how-to/create) — Dive in all Zerops has to offer for your Java application.
+
## Feature Highlights
+
+- [Create Java service](/java/how-to/create) — Start with creating a Java service using GUI or zCLI.
+- [zerops.yaml](/java/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
+- [Scaling configuration](/java/how-to/scaling) — Set up scaling of your Java application so that it runs smoothly while using only necessary resources.
+
{" "}
+
+- [Customize build environment](/java/how-to/build-process#customize-build-environment)
+- [Customize runtime environment](/java/how-to/customize-runtime)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+
+- [FAQ](/java/faq) — Most common questions in one place.
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Kafka > Overview
+
Zerops provides a fully managed [Apache Kafka](https://kafka.apache.org/) messaging platform with automated scaling and zero infrastructure overhead, letting developers focus entirely on development.
+
## Supported Versions
+
Currently supported Kafka version:
+
Import configuration version:
+
+- `kafka@3.9`
+- `kafka@3.8`
+
## Service Configuration
+
Our Kafka implementation features optimized default settings designed for common use cases.
+
### Key Configuration
+
* **Client Connections:** Data brokers available on port `9092`
* **Authentication:** Secure SASL PLAIN with automatically generated credentials
* **Data Persistence:** Topic data stored indefinitely (no time or size limit)
* **Performance:** Optimized settings for reliability and throughput
+
### Resource Allocation
+
Zerops automatically allocates resources to your Kafka service based on demand:
+
* **Memory:** Up to 40GB RAM for high-performance message processing
* **Storage:** Up to 250GB for persistent storage of messages and logs
* **Auto-scaling:** Resources scale up and down automatically based on workload
+
## Deployment Modes
+
:::important
Deployment mode is selected during service creation and cannot be changed later.
:::
+
### High-Availability (HA) Setup
+
The recommended solution for production workloads and mission-critical data:
+
* Creates a multi-node Kafka cluster with 3 broker nodes
* Configures 6 partitions across the cluster
* Implements replication factor of 3 (each broker node has a copy of each partition)
* Default topic replication is also 3 (overridable by user application)
* Zerops automatically attempts to repair the cluster and data replication in case of a node failure
+
### Single Node Instance
+
Suitable for development and testing environments:
+
* Consists of 1 broker node
* Configures 3 partitions
* No data replication
* Lower resource requirements
+
:::note
Use for development or non-critical data only, as data loss may occur due to container volatility.
:::
+
## Authentication Management
+
Authentication credentials are automatically generated and managed by the platform using SASL PLAIN authentication.
+
**Access your credentials through:**
* The service access details in the Zerops GUI
* Environment variables in your service configuration:
* `user` - Username for authentication
* `password` - Generated secure password
* `port` - Kafka port (value: `9092`)
+
## Client Access
+
Client implementations differ, please refer to your chosen client's configuration manual for specific details.
+
### Access Methods
+
#### Seed Broker Connection
Connect to the Kafka cluster using the "seed" (or "bootstrap") broker server:
```
-:9092
+:9092
```
+
#### Specific Broker Access
To access a single specific broker or a list of all/some brokers:
```
-node-stable-1.db..zerops:9092,node-stable-2.db..zerops:9092,...
+node-stable-1.db..zerops:9092,node-stable-2.db..zerops:9092,...
```
+
## Best Practices
+
### Production Workloads
* Use HA mode for all production deployments
* Configure proper retention policies for your topics based on your data requirements
* Monitor consumer lag to ensure messages are being processed efficiently
* Use consumer groups to distribute processing load
+
### Development Environments
* Single node instances are suitable for development and testing
* Be aware of potential data loss in non-HA deployments
* Consider using smaller message sizes during development to reduce resource usage
+
## Support
+
For advanced configurations or custom requirements:
* Join our [Discord community](https://discord.gg/zerops)
* Contact support via [email](mailto:support@zerops.io)
@@ -13202,10 +18829,15 @@ For advanced configurations or custom requirements:
# Keydb > How To > Connect
+
## Copy access details from Zerops GUI
+
You will find the KeyDB access details under the **Access details** button in the project dashboard page.
+
The same information is available in the service detail page in the left menu under the **Peek access details** button.
+
### KeyDB access parameters:
+
| Parameter | Description |
| --------------------- | -------------------------------------------------------------------------------- |
| **Hostname** | The service hostname specified when the KeyDB service was created. |
@@ -13214,26 +18846,43 @@ The same information is available in the service detail page in the left menu un
This port is fixed for all KeyDB services and cannot be customized. |
| **Connection string** | The connection string for KeyDB service is:
`redis://{hostname}:6379` |
+
## Connect to KeyDB from runtime services of the same project
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
#### Example
+
To connect to KeyDB `database1` service, set
+
```
host = database1
```
+
You will find the password under the [**Access details**](#copy-access-details-from-zerops-gui) button in Zerops GUI.
+
:::caution
Do not use SSL/TLS protocols when connecting to KeyDB from other runtime services in the same project. Zerops KeyDB is not configured to support these protocols. The security is assured by the project private network. Due to security reasons Zerops doesn't allow exposing KeyDB service to the internet.
:::
+
## Use KeyDB environment variables
+
Zerops creates default environment variables for each KeyDB service to help you with connection from runtime services in the same project. To avoid the need to copy database access parameters manually, use environment variables in your [runtime service].
+
### Prefix the environment variable key
+
All services of the same project can reference environment variables from other services. To use an environment variable from one service in another service in the same project, you must prefix the environment variable key with the service hostname and underscore.
+
#### Example
+
To access the `connectionString` env variable of the `keydb1` service, use `keudb1_connectionString` as the env variable key.
+
### KeyDB environment variables
+
List of service environment variables is available in Zerops GUI. Go to a KeyDB service detail and choose **Environment variables** in the left menu.
+
Zerops creates following environment variables when the KeyDB service is created:
+
| Variable | Description |
| --------------------- | -------------------------------------------------------------------------------- |
| **Hostname** | The service hostname specified when the KeyDB service was created. |
@@ -13244,26 +18893,41 @@ This port is fixed for all KeyDB services and cannot be customized. |
| **serviceId** | ID of the KeyDB service. Generated by Zerops. |
| **Connection string** | The connection string for KeyDB service is:
`redis://{hostname}:6379` |
+
You can create own custom [environment variables](/features/env-variables) for the KeyDB service in Zerops GUI and use them in the same way as the default variables.
+
## Connect to KeyDB in Zerops remotely
+
:::caution
Due to security reasons Zerops doesn't allow exposing KeyDB service directly to the internet.
:::
+
### Start VPN connection
+
You can securely connect to KeyDB from your local workspace via Zerops VPN. Zerops VPN client is included into zCLI, the Zerops command-line tool. To start a VPN connection to the selected Zerops project, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Start the Zerops VPN](/references/networking/vpn#start-vpn)
+
### Access KeyDB through VPN
+
Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no [environment variables](#use-keydb-environment-variables) are available when connected through VPN. To connect to KeyDB in Zerops you have to copy the [access details](#copy-access-details-from-zerops-gui) manually from Zerops GUI.
+
:::caution
Do not use SSL/TLS protocols when connecting to KeyDB over VPN. Zerops KeyDB is not configured to support these protocols. The security is assured by the VPN.
:::
+
### Stop VPN connection
+
[Stop the Zerops VPN](/references/networking/vpn#stop-vpn) in zCLI.
+
### Connect to KeyDB from another Zerops project
+
All services of the same project share a **dedicated private network**. You can use the service hostname to connect from one service to another within the same project.
+
Different Zerops projects have no special connection. They can communicate with each other only via the internet. If you need to connect to a KeyDB service in a Zerops project from a runtime service in another project, you need to use the [Zerops VPN](#access-keydb-through-vpn). Due to security reasons Zerops doesn't allow exposing KeyDB service directly to the internet.
+
----------------------------------------
# Keydb > How To > Control
@@ -13274,44 +18938,70 @@ Different Zerops projects have no special connection. They can communicate with
# Keydb > How To > Create
+
[KeyDB ↗](https://docs.keydb.dev/) is a fully open source database, backed by Snap, and a faster drop in alternative to Redis.
+
## Create KeyDB using Zerops GUI
+
First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new KeyDB service:
+
### Choose KeyDB version
+
Following KeyDB versions are currently supported:
+
### Set a hostname
+
Enter a unique service identifier like `keydb`, `db` etc.
+
#### Limitations:
+
- Duplicate services with the same name within the same project are not allowed
- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::
+
### Configure auto scaling
+
Zerops automatically scales KeyDB services based on actual database usage. Configure the scaling parameters to match your database needs and control costs.
+
**CPU Mode**: Choose between shared (cost-effective) or dedicated (consistent performance).
+
**Resource Limits**: Set minimum and maximum resources for CPU, RAM, and disk to control costs and ensure performance.
+
**Deployment Mode**: Choose the reliability configuration for your KeyDB service:
+
- **Highly Available**: Multiple containers with redundancy across different physical machines. Recommended for production environments.
- **Single Container**: One container suitable for development and non-critical environments.
+
:::warning
Deployment mode cannot be changed after service creation.
:::
+
:::tip Learn More
For detailed scaling configuration, deployment mode details, and troubleshooting, see:
- [How Zerops scales KeyDB](/keydb/how-to/scale) - Database-specific scaling guide
- [Automatic Scaling and High Availability](/features/scaling) - Complete technical details
:::
+
## Create KeyDB using zCLI
+
zCLI is the Zerops command-line tool. To create a new KeyDB service via the command-line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](#create-a-project-description-file)
3. Create a project and a KeyDB service
+
### Create a project description file
+
Zerops uses a yaml format file to describe the project infrastructure.
+
#### Basic example
+
Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content:
+
```yaml
# basic project data
project:
@@ -13326,9 +19016,13 @@ services:
# mode of operation "HA"/"NON_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain one KeyDB service in single container mode with default [auto scaling](/keydb/how-to/scale) configuration. Hostname will be set to `keydb1`.
+
#### Full example
+
Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content:
+
```yaml
# basic project data
project:
@@ -13367,103 +19061,163 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain two KeyDB services.
+
The hostname of the first service will be set to `keydb1`. The highly available mode will be chosen and the custom [auto scaling configuration](/keydb/how-to/scale) will be set.
+
The hostname of the second service will be set to `keydb2`. The single container mode will be chosen and the default [auto scaling configuration](/keydb/how-to/scale) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
-
- Parameter
- Description
- Limitations
-
- name
- The name of the new project. Duplicates are allowed.
-
- description
- Optional. Description of the new project.
- Maximum 255 characters.
-
- tags
- Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
-
+
+
+
+
+
Parameter
+
Description
+
Limitations
+
+
+
+
+
name
+
The name of the new project. Duplicates are allowed.
+
+
+
+
description
+
Optional. Description of the new project.
+
Maximum 255 characters.
+
+
+
tags
+
Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
+
+
+
+
+
At least one service in `services:` section is required. You can create a project with multiple services. The example above contains only KeyDB services but you can create a `description.yaml` with [different types] of services.
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
hostname
+
The unique service identifier.
+
The hostname of the new database will be set to the `hostname` value.
- Limitations:
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+ Limitations:
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
type
+
Specifies the service type and version.
-
+
See what [KeyDB service types](/references/import-yaml/type-list#database-services) are currently supported.
-
- mode
-
+
+
+
+
mode
+
Defines the operation mode of KeyDB service.
- HA
-
+
+ HA
+
Creates a KeyDB cluster with 2 database containers. This mode is suited for production.
+
Zerops always keeps the 2 database containers on different physical machines. All your data is stored redundantly in 2 identical copies. In case of a failure of a container or the underlying physical machine, Zerops automatically disconnects the failed container from the cluster, creates a new container and syncs all data from the remaining copy. Finally the broken container is automatically deleted.
- NON_HA
-
+
+ NON_HA
+
Zerops will create a KeyDB database installed in a single container. Useful for non-essential data or dev environments.
+
Your data is stored only in a single container. If the container or the underlying physical machine fails, your data since the last backup are lost. Zerops doesn't provide any automatic repairs of single node KeyDB services.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto scaling parameters.
-
+
+
+
+
verticalAutoscaling
+
+ Optional. Defines [custom vertical auto scaling parameters](/keydb/how-to/scaling#configure-scaling).
+
All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
-:::caution
-The KeyDB service **hostname** and **mode** are fixed after the service is created. They can't be changed later.
-:::
-### Create a project based on the description.yaml
-When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
-```sh
-Usage:
- zcli project project-import importYamlPath [flags]
-Flags:
- -h, --help Help for the project import command.
+
+
+
+
- cpuMode
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
- minCpu/maxCpu
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
- minRam/maxRam
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
- minDisk/maxDisk
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
+
+:::caution
+The KeyDB service **hostname** and **mode** are fixed after the service is created. They can't be changed later.
+:::
+
+### Create a project based on the description.yaml
+
+When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
+```sh
+Usage:
+ zcli project project-import importYamlPath [flags]
+
+Flags:
+ -h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add KeyDB service to an existing project
+
#### Example
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```bash
# array of project services
services:
@@ -13475,208 +19229,317 @@ services:
# mode of operation "HA"/"NON_HA"
mode: NON_HA
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one KeyDB service in single container mode with default [auto scaling](/keydb/how-to/scale) configuration will be added to your project. Hostname of the new service will be set to `keydb1`.
+
The content of the `services:` section of `import.yaml` is identical to the [project description file](#create-a-project-description-file). The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the `import.yaml` file is 100 kB.
----------------------------------------
# Keydb > How To > Manage
+
## How to use a database management tool on your workstation
+
Do you already use a database management tool that supports KeyDB on your workstation? Connect it securely to KeyDB from your local workspace via Zerops VPN.
+
Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to KeyDB remotely](/keydb/how-to/connect#connect-to-keydb-in-zerops-remotely).
+
:::caution
Do not use SSL/TLS protocols when connecting to KeyDB over VPN. Zerops KeyDB is not configured to support these protocols. The security is assured by the VPN.
:::
+
## How to use KeyDB Client CLI on your workstation
+
If you use the [keydb-cli ↗](https://docs.keydb.dev/docs/keydbcli/) command-line client to manage your KeyDB on your local workspace, you can connect it securely to KeyDB via Zerops VPN.
+
Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to KeyDB remotely](/keydb/how-to/connect#connect-to-keydb-in-zerops-remotely).
+
Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no [environment variables](/keydb/how-to/connect#connect-to-keydb-in-zerops-remotely) are available when connected through VPN. To connect to KeyDB in Zerops you have to copy the [access details](/keydb/how-to/connect#connect-to-keydb-in-zerops-remotely) manually from Zerops GUI.
+
Use `keydb-cli` command to connect to KeyDB in Zerops:
+
```sh
keydb-cli -h [hostname]
```
+
:::caution
Do not use SSL/TLS protocols when connecting to KeyDB over VPN. Zerops KeyDB is not configured to support these protocols. The security is assured by the VPN.
:::
+
----------------------------------------
# Keydb > How To > Scale
+
Zerops automatically scales your KeyDB service based on actual database usage. When your database needs more power, resources increase. When demand drops, resources scale down to reduce costs.
+
:::tip Read More
For complete scaling details across all services, see [Automatic Scaling and High Availability](/features/scaling).
:::
+
## How KeyDB scaling works
+
KeyDB services use **vertical scaling** to adjust CPU, RAM, and disk resources within containers based on usage patterns. Unlike runtime services, KeyDB does not use horizontal scaling (adding/removing containers). Instead, KeyDB services use deployment modes for high availability.
+
## Configure scaling
+
You can configure scaling settings:
+
- **During service creation** - Set initial scaling parameters when [creating](/keydb/how-to/create) your KeyDB service
- **During import** - Define scaling configuration in your YAML import file using `verticalAutoscaling` parameters
- **After service creation** - Navigate to your KeyDB service and select **Automatic scaling configuration** to modify settings
+
### Basic settings
-
+
**CPU Mode**: Choose between shared (cost-effective, variable performance) or dedicated (consistent performance, higher cost). You can change CPU mode once per hour. See [pricing](https://zerops.io/#pricing) for costs.
+
**Resource limits**: Configure minimum and maximum resources for your KeyDB service:
+
- **Lower the maximum** to control costs and prevent over-scaling
- **Raise the minimum** when you need guaranteed baseline performance
- **Set minimum = maximum** to disable automatic scaling for that specific resource
+
**Deployment mode**: Choose the reliability configuration for your KeyDB service:
+
- **Single Container**: One container with vertical scaling only. Suitable for development environments.
- **Highly Available**: Multiple containers with built-in redundancy. Recommended for production environments.
+
:::warning
Deployment mode cannot be changed after service creation.
:::
+
When a container fails in HA mode, Zerops automatically replaces it with a new container on a different physical machine and synchronizes data from healthy copies.
+
### Advanced settings
+
**Start CPU cores**: Determines how many CPU cores are allocated during database startup. Increase this value if your KeyDB service starts slowly or requires more processing power during initialization.
+
**RAM thresholds**: Help prevent out-of-memory crashes by maintaining buffer space:
+
- **Absolute (GB)**: Maintains this amount of free RAM at all times
- **Percentage**: Keeps this percentage of total RAM free
+
Consider increasing these values if your database experiences memory-related issues.
-
+
:::info Read More
For detailed technical parameters and scaling behavior, see [Automatic Scaling and High Availability](/features/scaling#resource-scaling-behavior).
:::
+
## Monitor usage
+
Navigate to your KeyDB service and select **Service containers & Overview** to view:
- CPU, RAM, and disk usage over time
- Historical scaling events
- Container health status
+
## Technical details
+
Zerops monitors database usage and automatically adjusts resources based on predefined thresholds and timing parameters. The scaling behavior follows the same principles as other services in the platform.
+
For complete technical specifications including:
- Resource monitoring intervals and thresholds
- Scale-up and scale-down timing parameters
- Scaling increments and steps
- Detailed scaling behavior patterns
+
See [Resource Scaling Behavior](/features/scaling#resource-scaling-behavior) in the general scaling documentation.
+
## Common issues
+
**Out of memory errors**
- Increase minimum free RAM settings in your scaling configuration
- Consider raising the minimum RAM allocation
- Check for memory-intensive operations
+
**Higher than expected costs**
- Consider lowering your maximum resource limits
- Review scaling patterns in the monitoring dashboard
+
**Slow database startup**
- Increase the "Start CPU cores" setting
- Consider switching to dedicated CPU mode for consistent performance
+
*Need help? Join our [Discord community](https://discord.gg/zerops) for assistance!*
----------------------------------------
# Keydb > Overview
+
[KeyDB ↗](https://docs.keydb.dev/) is a fully open source database, a faster drop-in alternative to Redis. It offers enhanced performance, multithreading capabilities, and maintains full compatibility with Redis clients and APIs.
+
:::important
While KeyDB is available in Zerops, please note that KeyDB development has not been very active recently. For new Redis-compatible deployments, we recommend considering [Valkey](/valkey/overview) as the preferred alternative due to its active development and ongoing support.
:::
+
## Feature Highlights
+
+- [Create KeyDB service](/keydb/how-to/create) — Start with creating a KeyDB service using GUI or zCLI.
+- [Import config file](/keydb/how-to/create#full-example) — Use an example config file to import your KeyDB service.
+
### Connect to KeyDB service
+
+- [Manage KeyDB database](/keydb/how-to/manage)
+- [Connect from the same project](/keydb/how-to/connect#connect-to-keydb-from-runtime-services-of-the-same-project)
+- [Connect remotely](/keydb/how-to/connect#connect-to-keydb-in-zerops-remotely)
+
## Popular Guides
+
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your KeyDB service securely with Zerops VPN.
+
*Need help? Join our [Discord community](https://discord.gg/zeropsio).*
----------------------------------------
# Mariadb > How To > Backup
+
Zerops provides automated data backup for MariaDB services with full encryption and flexible management options.
+
For general backup information including configuration, scheduling, and management options, see the [Zerops Backups](/features/backup) documentation, which covers:
- Backup scheduling and retention policies
- Tagging system and storage quotas
- Manual backup creation and CLI tools
- Security and encryption details
+
This page focuses on MariaDB-specific backup details.
+
## MariaDB Backup Format
+
MariaDB backups are created using `mariabackup` and stored in `.xb.gz` format:
+
- **Format**: `.xb.gz` (single archive)
- **Tooling**: `mariabackup`
- **Compression**: Uses `xbstream` format, gzip compressed
- **Storage**: Encrypted and stored in isolated object storage
+
## Restoring MariaDB Backups
+
To restore a MariaDB backup, follow these steps:
+
:::tip
If the backup is large and the export/import has higher demands, consider scaling up the RAM in the container before starting. You can use [zsc](/references/zsc) to temporarily scale up:
```bash
zsc scale ram +2GB 10m
```
:::
+
### Step 1: Deploy the restore helper service
+
Import the [MariaDB restore recipe](https://github.com/zeropsio/recipe-mariadb-restore) as a service into the project where your MariaDB service is located.
+
Use the `zerops-import.yaml` file from the repository to import the service. See the [import documentation](/references/import) for details, or follow the steps in the [recipe README](https://github.com/zeropsio/recipe-mariadb-restore?tab=readme-ov-file#deploy-on-zerops).
+
### Step 2: Get the backup download URL
+
1. Navigate to your MariaDB service in the Zerops GUI
2. Go to the **Backups List & Configuration** section
3. Find the backup you want to restore
4. Click the **three dots menu** (⋮) on that backup
5. Select **Copy download link**
+
### Step 3: Run the backup script
+
Connect to the `mariadbrestore` service using the GUI terminal or via [VPN](/references/networking/vpn) and [SSH](/references/networking/ssh).
+
:::note
To use environment variables from your MariaDB service in the backup and restore commands, make sure the `envIsolation` project variable is set to `none`. See [Environment Variable Isolation](/features/env-variables#environment-variable-isolation) and [Referencing Variables](/features/env-variables#referencing-variables) for details.
:::
+
Run the backup script:
+
```bash
-backup.sh -d -u ""
+backup.sh -d -u ""
```
+
Verify the backup was created:
+
```bash
ls -lh backup.sql
```
+
:::note
You can also verify the backup file exists by checking the **File browser** in the `mariadbrestore` service.
:::
+
:::info
After the export completes, the terminal may become unresponsive. If this happens, refresh the terminal.
:::
+
### Step 4: Import data to the target database
+
Import the data to your target MariaDB database:
+
```bash
-mariadb -u -h -p < backup.sql
+mariadb -u -h -p < backup.sql
```
+
Alternatively, you can download the `backup.sql` dump file for later use or to restore to a database outside of Zerops.
+
## High Availability
+
For MariaDB services running in High Availability mode:
- Backups are created on a randomly selected healthy node
- Other nodes remain operational during the backup process
- Manual backups typically run on the primary node
+
## Best Practices
+
- Always create a manual backup with a protected tag before database migrations or major schema changes
- Test your restore process periodically in a non-production environment
- Monitor your backup storage usage in the Project Overview
- Use descriptive tags like `pre-migration-v2` for important snapshots
+
For additional best practices and troubleshooting, refer to the [main backup documentation](/features/backup).
----------------------------------------
# Mariadb > How To > Connect
+
## Default MariaDB database and user
+
Zerops creates a default database and a default user automatically when a new MariaDB service is [created](/mariadb/how-to/create).
+
#### Database
+
The default database name is identical to the service hostname. The default encoding is set to `utf8mb4`.
+
#### DB user
+
Default user name is identical to the service hostname. Default user password is generated randomly. You will find the password in [Zerops GUI](/mariadb/how-to/connect#copy-access-details-from-zerops-gui) or you can use the [environment variable](#use-mariadb-environment-variables).
+
:::info
Zerops creates a second DB user: `zps` for maintenance reasons with full privileges. Do not delete, change the password or remove privileges from this user, it will disrupt Zerops ability to maintain the database cluster.
:::
+
## Copy access details from Zerops GUI
+
You will find the MariaDB access details under the **Access details** button in the project dashboard page.
+
The same information is available in the service detail page in the left menu under the **Peek access details** button.
+
### MariaDB access parameters:
+
| Parameter | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Hostname** | The service hostname specified when the MariaDB service was created. |
@@ -13687,29 +19550,46 @@ This port is fixed for all MariaDB services and cannot be customized.
| **Password** | Zerops sets a random password when the service is created. |
| **Connection string** | The connection string for MariaDB service is:
`mysql://${user}:${password}@{hostname}:3306` |
+
## Connect to MariaDB from runtime services of the same project
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
#### Example
+
To connect to MariaDB `database1` service, set
+
```
host = database1
user = database1
password = **********
```
+
You will find the password under the [**Access details**](/mariadb/how-to/connect#copy-access-details-from-zerops-gui) button in Zerops GUI.
+
:::caution
Do not use SSL/TLS protocols when connecting to MariaDB from other runtime services in the same project. Zerops MariaDB is not configured to support these protocols. The security is assured by the project private network. Due to security reasons Zerops doesn't allow exposing MariaDB service to the internet.
:::
+
## Use MariaDB environment variables
+
Zerops creates default environment variables for each MariaDB service to help you with connection from runtime services in the same project. To avoid the need to copy database access parameters manually, use environment variables in your [runtime service].
+
### Prefix the environment variable key
+
All services of the same project can reference environment variables from other services. To use an environment variable from one service in another service in the same project, you must prefix the environment variable key with the service hostname and underscore.
+
#### Example
+
To access the `connectionString` env variable of the `mariadb1` service, use `mariadb1_connectionString` as the env variable key.
To access the `password` env variable of the `mariadb2` service, use `mariadb2_password` as the env variable key.
+
### MariaDB environment variables
+
List of service environment variables is available in Zerops GUI. Go to a MariaDB service detail and choose **Environment variables** in the left menu.
+
Zerops creates following environment variables when the MariaDB service is created:
+
| Variable | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Hostname** | The service hostname specified when the MariaDB service was created. |
@@ -13720,35 +19600,52 @@ This port is fixed for all MariaDB services and cannot be customized.
| **serviceId** | ID of the MariaDB service. Generated by Zerops. |
| **Connection string** | The connection string for MariaDB service is:
`mysql://${user}:${password}@{hostname}:3306`
+
Connection string contains [references](/mariadb/how-to/connect#mariadb-access-parameters) to `user` and `password` variables. Each time the `user` or `password` variable is updated, the `connectionString` variable is automatically updated as well. |
| **User** | Zerops creates a database user automatically when the service is created. The user name is always identical to the service hostname. |
| **Password** | Zerops sets a random password when the service is created. |
+
:::caution
When you change the value of the password env variable, only the env variable is updated, not the actual password of the MariaDB user. You have to update the password of the database user manually.
:::
:::caution
When you change the password of the default MariaDB user in the database, the new password is not synchronised to the password env variable. You have to update the `password` env variable manually.
:::
+
You can create own custom [environment variables](/features/env-variables) for the MariaDB service in Zerops GUI and use them in the same way as the default variables.
+
## Connect to MariaDB in Zerops remotely
+
:::caution
Due to security reasons Zerops doesn't allow exposing MariaDB service directly to the internet.
:::
+
### Start VPN connection
+
You can securely connect to MariaDB from your local workspace via Zerops VPN. Zerops VPN client is included into zCLI, the Zerops command-line tool. To start a VPN connection to the selected Zerops project, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Start the Zerops VPN](/references/networking/vpn#start-vpn)
+
### Access MariaDB through VPN
+
Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no [environment variables](#use-mariadb-environment-variables) are available when connected through VPN. To connect to MariaDB in Zerops you have to copy the [access details](#copy-access-details-from-zerops-gui) manually from Zerops GUI.
+
:::caution
Do not use SSL/TLS protocols when connecting to MariaDB over VPN. Zerops MariaDB is not configured to support these protocols. The security is assured by the VPN.
:::
+
### Stop VPN connection
+
[Stop the Zerops VPN](/references/networking/vpn#stop-vpn) in zCLI.
+
### Connect to MariaDB from another Zerops project
+
All services of the same project share a **dedicated private network**. You can use the service hostname to connect from one service to another within the same project.
+
Different Zerops projects have no special connection. They can communicate with each other only via the internet. If you need to connect to a MariaDB service in a Zerops project from a runtime service in another project, you need to use the [Zerops VPN](#access-mariadb-through-vpn). Due to security reasons Zerops doesn't allow exposing MariaDB service directly to the internet.
+
----------------------------------------
# Mariadb > How To > Control
@@ -13759,50 +19656,80 @@ Different Zerops projects have no special connection. They can communicate with
# Mariadb > How To > Create
+
MariaDB is the open source relational database loved by developers all over the world. Created by MySQL's original developers, MariaDB is compatible with MySQL and guaranteed to stay open source forever.
+
## Create MariaDB using Zerops GUI
+
:::note
If you're migrating from another database system such as MySQL, please review the [migration information](#migrating-from-other-database-systems) section first, as some critical settings must be configured at creation time.
:::
+
First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new MariaDB service:
+
+[Video: /vids/services/mariadb.webm](/vids/services/mariadb.webm)
+
### Choose MariaDB version
+
Following MariaDB versions are currently supported:
+
### Set a hostname
+
Enter a unique service identifier like `mariadb`, `sql`, `db` etc.
+
#### Limitations:
+
- Duplicate services with the same name within the same project are not allowed
- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::
+
### Configure auto scaling
+
Zerops automatically scales MariaDB services based on actual database usage. Configure the scaling parameters to match your database needs and control costs.
+
**CPU Mode**: Choose between shared (cost-effective) or dedicated (consistent performance).
+
**Resource Limits**: Set minimum and maximum resources for CPU, RAM, and disk to control costs and ensure performance.
+
**Deployment Mode**: Choose the reliability configuration for your MariaDB service:
+
- **Highly Available**: Multiple containers with redundancy across different physical machines. Recommended for production environments.
- **Single Container**: One container suitable for development and non-critical environments.
+
:::warning
Deployment mode cannot be changed after service creation.
:::
+
:::tip Learn More
For detailed scaling configuration, deployment mode details, and troubleshooting, see:
- [How Zerops scales MariaDB](/mariadb/how-to/scale) - Database-specific scaling guide
- [Automatic Scaling and High Availability](/features/scaling) - Complete technical details
:::
+
## Create MariaDB using zCLI
+
:::note
If you're migrating from another database system such as MySQL, please review the [migration information](#migrating-from-other-database-systems) section first, as some critical settings must be configured at creation time.
:::
+
zCLI is the Zerops command-line tool. To create a new MariaDB service via the command-line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](#create-a-project-description-file)
3. Create a project and a MariaDB service
+
### Create a project description file
+
Zerops uses a yaml format file to describe the project infrastructure.
+
#### Basic example
+
Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content:
+
```yaml
# basic project data
project:
@@ -13817,9 +19744,13 @@ services:
# mode of operation "HA"/"NON_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain one MariaDB 10.4 service in single container mode with default [auto scaling](/mariadb/how-to/scale) configuration. Hostname will be set to `mariadb1`.
+
#### Full example
+
Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content:
+
```yaml
# basic project data
project:
@@ -13861,112 +19792,169 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain two MariaDB 10.4 services.
+
The hostname of the first service will be set to `mariadb1`. The highly available mode will be chosen and the custom [auto scaling configuration](/mariadb/how-to/scale) will be set. The `lower_case_table_names` system variable will be set to "1".
+
The hostname of the second service will be set to `mariadb2`. The single container mode will be chosen and the default [auto scaling configuration](/mariadb/how-to/scale) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
-
- Parameter
- Description
- Limitations
-
- name
- The name of the new project. Duplicates are allowed.
-
- description
- Optional. Description of the new project.
- Maximum 255 characters.
-
- tags
- Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
-
+
+
+
+
+
Parameter
+
Description
+
Limitations
+
+
+
+
+
name
+
The name of the new project. Duplicates are allowed.
+
+
+
+
description
+
Optional. Description of the new project.
+
Maximum 255 characters.
+
+
+
tags
+
Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
+
+
+
+
+
At least one service in `services:` section is required. You can create a project with multiple services. The example above contains only MariaDB services but you can create a `description.yaml` with [different types] of services.
-
- Parameter
- Description
- Limitations
-
- hostname
- A unique service identifier like `mariadb`,`sql`, `db` etc.
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
- Specifies the service type and version.
-
+
+
+
+
+
Parameter
+
Description
+
Limitations
+
+
+
+
+
hostname
+
A unique service identifier like `mariadb`,`sql`, `db` etc.
+
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
type
+
Specifies the service type and version.
+
See what [MariaDB service types](/references/import-yaml/type-list#database-services) are currently supported.
-
- mode
- Defines the operation mode of MariaDB service.
-
- HA
-
+
+
+
+
mode
+
Defines the operation mode of MariaDB service.
+
+ HA
+
Zerops will create a MariaDB cluster with 3 database containers and 2
free database proxies. This mode is suited for production.
-
+
Zerops always keep the 3 database containers on different physical
machines. All your data is stored redundantly in 3 copies. In case of a
failure of a container or the underlying physical machine, Zerops
automatically disconnects the failed container from the cluster, creates
a new container and syncs all data from the remaining 2 copies. Finally
the broken container is automatically deleted.
-
- NON_HA
-
+
+ NON_HA
+
Zerops will create a MariaDB database installed in a single container.
Useful for non-essential data or dev environments.
-
+
Your data is stored only in a single container. If the container or the
underlying physical machine fails, your data since the last backup are
lost. Zerops doesn't provide any automatic repairs of single node
MariaDB services.
-
- verticalAutoscaling
- Defines custom vertical auto scaling parameters
-
+
+
+
+
verticalAutoscaling
+
Defines [custom vertical auto scaling parameters](/mariadb/how-to/scaling#configure-scaling)
+
All verticalAutoscaling attributes are optional. Not specified
attributes will be set to their default values.
-
- - cpuMode
- Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
- Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
- Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
- Set the minDisk or maxDisk in GB (float).
-
- envSecrets
- Defines [secret environment variables](/features/env-variables#2-secret-variables) for the service
-
-:::caution
-The MariaDB service **hostname** and **mode** are fixed after the service is created. They can't be changed later.
-:::
-### Create a project based on the description.yaml
-When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
-```sh
-Usage:
- zcli project project-import importYamlPath [flags]
-Flags:
- -h, --help Help for the project import command.
- --org-id string If you have access to more than one organization, you must specify the org ID for which the
+
+
+
+
- cpuMode
+
Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
- minCpu/maxCpu
+
Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
- minRam/maxRam
+
Set the minRam or maxRam in GB (float).
+
+
+
+
- minDisk/maxDisk
+
Set the minDisk or maxDisk in GB (float).
+
+
+
+
envSecrets
+
Defines [secret environment variables](/features/env-variables#2-secret-variables) for the service
+
+
+
+
+
+:::caution
+The MariaDB service **hostname** and **mode** are fixed after the service is created. They can't be changed later.
+:::
+
+### Create a project based on the description.yaml
+
+When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
+```sh
+Usage:
+ zcli project project-import importYamlPath [flags]
+
+Flags:
+ -h, --help Help for the project import command.
+ --org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add MariaDB service to an existing project
+
#### Example
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```bash
# array of project services
services:
@@ -13981,56 +19969,87 @@ services:
envSecrets:
lower_case_table_names: "1"
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one MariaDB 10.4 service in single container mode with default [auto scaling](/mariadb/how-to/scale) configuration will be added to your project. Hostname of the new service will be set to `mariadb1`. The `lower_case_table_names` system variable will be set to "1".
+
The content of the `services:` section of `import.yaml` is identical to the [project description file](#create-a-project-description-file). The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the `import.yaml` file is 100 kB.
+
## Migrating from other database systems
+
### Configure system variables
+
When migrating to MariaDB in Zerops from other database systems, you may need to configure specific system variables to maintain compatibility with your existing applications.
+
#### Setting `lower_case_table_names` for MySQL compatibility
+
The `lower_case_table_names` system variable determines how MariaDB handles table name case sensitivity:
-
- Value
- Table Name Storage
- Comparison Behavior
-
- 0
- Stored as specified (preserves case)
- Case-sensitive
-
- 1
- Stored in lowercase
- Case-insensitive
-
- 2
- Stored as specified (preserves case)
- Case-insensitive
-
+
+
+
+
+
Value
+
Table Name Storage
+
Comparison Behavior
+
+
+
+
+
0
+
Stored as specified (preserves case)
+
Case-sensitive
+
+
+
1
+
Stored in lowercase
+
Case-insensitive
+
+
+
2
+
Stored as specified (preserves case)
+
Case-insensitive
+
+
+
+
:::caution
This variable must be configured when the MariaDB instance is first created and cannot be changed afterward. This is a limitation of MariaDB itself, not specific to Zerops.
:::
+
When configuring this in Zerops:
+
- **Using GUI**: Set the `lower_case_table_names` parameter in the advanced options section when creating a new MariaDB service
- **Using YAML**: Include it in your service configuration under the `envSecrets` section (see examples in the [Create MariaDB using zCLI](#create-mariadb-using-zcli) section)
+
##### Migration considerations
+
If you're migrating from MySQL to MariaDB and your application relies on a specific table name case handling:
+
1. Determine the value used in your source MySQL installation
2. Configure the same value in your Zerops MariaDB configuration before initializing the database
3. For most migrations from MySQL 5.7, setting the value to "1" is recommended for compatibility
+
After deploying your MariaDB service, you can verify the settings with this SQL command:
+
```sql
SELECT @@lower_case_file_system, @@lower_case_table_names;
```
+
:::important
If you need to change this setting after the database has been initialized, you'll need to create a new MariaDB service with the correct configuration and migrate your data.
:::
@@ -14039,59 +20058,94 @@ If you need to change this setting after the database has been initialized, you'
# Mariadb > How To > Export Import Data
+
## Use Adminer to export or import data
+
[Adminer ↗](https://www.adminer.org) is an open source full-featured database management tool written in PHP.
+
1. [Install Adminer to Zerops](/mariadb/how-to/manage#how-to-install-adminer-to-zerops)
2. Use Adminer standard export or import functions
+
## Use phpMyAdmin to export or import data
+
[phpMyAdmin ↗](https://www.phpmyadmin.net) is a free software tool written in PHP, intended to handle the administration of MariaDB over the Web.
+
1. [Install phpMyAdmin to Zerops](/mariadb/how-to/manage#how-to-install-phpmyadmin-to-zerops)
2. Use phpMyAdmin standard export or import functions
+
## Use a database management tool on your workstation to export or import data
+
Do you already use a database management tool that supports MariaDB on your workstation? Connect it securely to MariaDB from your local workspace via Zerops VPN.
+
Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to MariaDB remotely](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely).
:::caution
Do not use SSL/TLS protocols when connecting to MariaDB over VPN. Zerops MariaDB is not configured to support these protocols. The security is assured by the VPN.
:::
+
Once the connection to MariaDB is established, use the standard export or import functions of your favourite management tool.
+
## Use mysql CLI to export or import data
+
If you are using the [mysql ↗](https://dev.mysql.com/doc/refman/8.1/en/mysql.html) command-line client to manage your MariaDB on your local workspace, you can connect it securely to MariaDB via Zerops VPN.
+
Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to MariaDB remotely](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely).
+
Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no [environment variables](/mariadb/how-to/connect#use-mariadb-environment-variables) are available when connected through VPN. To connect to MariaDB in Zerops you have to copy the [access details](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely) manually from Zerops GUI.
+
Use [mysql ↗](https://dev.mysql.com/doc/refman/8.1/en/mysql.html) command to connect to MariaDB in Zerops:
+
```sh
mysql -h [hostname] -u [user] -p [password] [database_name]
```
+
:::caution
Do not use SSL/TLS protocols when connecting to MariaDB over VPN. Zerops MariaDB is not configured to support these protocols. The security is assured by the VPN.
:::
+
To export your database data and structure, use the [mysqldump ↗](https://dev.mysql.com/doc/refman/8.1/en/mysqldump.html) command.
+
```sh
mysqldump -h [hostname] -u [user] –p [password] [database_name] > dumpfilename.sql
```
+
To import your database data and structure, use the `mysql` command.
+
```sh
mysql -h [hostname] -u [user] –p [password] [database_name] < dumpfilename.sql
```
+
----------------------------------------
# Mariadb > How To > Manage
+
## Default database and user
+
Zerops creates a default database and a default user automatically when a new MariaDB service is [created](/mariadb/how-to/create).
+
#### Database
+
The default database name is identical to the service hostname. The default encoding is set to `utf8mb4`.
+
#### DB user
+
Default user name is identical to the service hostname. Default user password is generated randomly. You will find the password in [Zerops GUI](/mariadb/how-to/connect#copy-access-details-from-zerops-gui) or you can use the [environment variable](/mariadb/how-to/connect#use-mariadb-environment-variables).
+
:::info
Zerops creates a second DB user: `zps` for maintenance reasons with full privileges. Do not delete, change the password or remove privileges from this user, it will disrupt Zerops ability to maintain the database cluster.
:::
+
## How to install Adminer to Zerops
+
[Adminer ↗](https://www.adminer.org) is a open source full-featured database management tool written in PHP.
+
### Single-click installation
+
To install Adminer into your project, open your project in Zerops GUI and select **import services** in the left menu.
+
Copy the following yaml file into the text area and start the import:
+
```yaml
services:
- # Service will be accessible through zCLI VPN under: http://adminer
@@ -14107,25 +20161,41 @@ services:
# Link to Zerops repository that contains Adminer code with Zerops build and deploy instructions.
buildFromGit: https://github.com/zeropsio/recipe-adminer@main
```
+
When the import is finished, Adminer will be running as a PHP service in your project.
+
## How to access Adminer
+
### Use Zerops VPN
+
By default Adminer service is private and is accessible from your local workstation over VPN.
+
You can securely connect to MariaDB from your local workspace via Zerops VPN. Zerops VPN client is included into zCLI, the Zerops command-line tool. To start a VPN connection to the selected Zerops project, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Start the Zerops VPN](/references/networking/vpn)
3. Type `http://adminer` into your browser
+
:::caution
Do not use https when connecting to Adminer via VPN.
:::
+
### Enable public access
+
You can enable the public access to the Adminer service via the [Zerops subdomain].
+
Or you can configure the [Public routing] on the Adminer service to make it accessible on your own domain.
+
## How to install phpMyAdmin to Zerops
+
[phpMyAdmin ↗](https://www.phpmyadmin.net) is a free software tool written in PHP, intended to handle the administration of MariaDB over the Web.
+
### Single-click installation
+
To install phpMyAdmin into your project, open your project in Zerops GUI and select **import services** in the left menu.
+
Copy the following yaml file into the text area and start the import:
+
```yaml
services:
- # Service will be accessible through zCLI VPN under: http://phpmyadmin
@@ -14141,240 +20211,393 @@ services:
# Link to Zerops repository that contains Adminer code with Zerops build and deploy instructions.
buildFromGit: https://github.com/zeropsio/recipe-phpmyadmin@main
```
+
When the import is finished, phpMyAdmin will be running as a PHP service in your project.
+
## How to access phpMyAdmin
+
### Use Zerops VPN
+
By default phpMyAdmin service is private and is accessible from your local workstation over VPN.
+
You can securely connect to MariaDB from your local workspace via Zerops VPN. Zerops VPN client is included into zCLI, the Zerops command-line tool. To start a VPN connection to the selected Zerops project, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Start the Zerops VPN](/references/networking/vpn)
3. Type `http://phpmyadmin` into your browser
+
:::caution
Do not use https when connecting to phpMyAdmin via VPN.
:::
+
### Enable public access
+
You can enable the public access to the phpMyAdmin service via the [Zerops subdomain].
+
Or you can configure the [Public routing] on the phpMyAdmin service to make it accessible on your own domain.
+
## How to use a database management tool on your workstation
+
Do you already use a database management tool that supports MariaDB on your workstation? Connect it securely to MariaDB from your local workspace via Zerops VPN.
+
Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to MariaDB remotely](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely).
+
:::caution
Do not use SSL/TLS protocols when connecting to MariaDB over VPN. Zerops MariaDB is not configured to support these protocols. The security is assured by the VPN.
:::
+
## How to use mysql CLI on your workstation
+
If you use the [mysql ↗](https://dev.mysql.com/doc/refman/8.1/en/mysql.html) command-line client to manage your MariaDB on your local workspace, you can connect it securely to MariaDB via Zerops VPN.
+
Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to MariaDB remotely](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely).
+
Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no [environment variables](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely) are available when connected through VPN. To connect to MariaDB in Zerops you have to copy the [access details](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely) manually from Zerops GUI.
+
Use `mysql` command to connect to MariaDB in Zerops:
+
```sh
mysql -h [hostname] -u [user] -p [password] [database_name]
```
+
:::caution
Do not use SSL/TLS protocols when connecting to MariaDB over VPN. Zerops MariaDB is not configured to support these protocols. The security is assured by the VPN.
:::
+
----------------------------------------
# Mariadb > How To > Scale
+
Zerops automatically scales your MariaDB service based on actual database usage. When your database needs more power, resources increase. When demand drops, resources scale down to reduce costs.
+
:::tip Read More
For complete scaling details across all services, see [Automatic Scaling and High Availability](/features/scaling).
:::
+
## How MariaDB scaling works
+
MariaDB services use **vertical scaling** to adjust CPU, RAM, and disk resources within containers based on usage patterns. Unlike runtime services, MariaDB does not use horizontal scaling (adding/removing containers). Instead, MariaDB services use deployment modes for high availability.
+
## Configure scaling
+
You can configure scaling settings:
+
- **During service creation** - Set initial scaling parameters when [creating](/mariadb/how-to/create) your MariaDB service
- **During import** - Define scaling configuration in your YAML import file using `verticalAutoscaling` parameters
- **After service creation** - Navigate to your MariaDB service and select **Automatic scaling configuration** to modify settings
+
### Basic settings
-
+
**CPU Mode**: Choose between shared (cost-effective, variable performance) or dedicated (consistent performance, higher cost). You can change CPU mode once per hour. See [pricing](https://zerops.io/#pricing) for costs.
+
**Resource limits**: Configure minimum and maximum resources for your MariaDB service:
+
- **Lower the maximum** to control costs and prevent over-scaling
- **Raise the minimum** when you need guaranteed baseline performance
- **Set minimum = maximum** to disable automatic scaling for that specific resource
+
**Deployment mode**: Choose the reliability configuration for your MariaDB service:
+
- **Single Container**: One container with vertical scaling only. Suitable for development environments.
- **Highly Available**: Multiple containers with built-in redundancy. Recommended for production environments.
+
:::warning
Deployment mode cannot be changed after service creation.
:::
+
When a container fails in HA mode, Zerops automatically replaces it with a new container on a different physical machine and synchronizes data from healthy copies.
+
### Advanced settings
+
**Start CPU cores**: Determines how many CPU cores are allocated during database startup. Increase this value if your MariaDB service starts slowly or requires more processing power during initialization.
+
**RAM thresholds**: Help prevent out-of-memory crashes by maintaining buffer space:
+
- **Absolute (GB)**: Maintains this amount of free RAM at all times
- **Percentage**: Keeps this percentage of total RAM free
+
Consider increasing these values if your database experiences memory-related issues.
-
+
:::info Read More
For detailed technical parameters and scaling behavior, see [Automatic Scaling and High Availability](/features/scaling#resource-scaling-behavior).
:::
+
## Monitor usage
+
Navigate to your MariaDB service and select **Service containers & Overview** to view:
- CPU, RAM, and disk usage over time
- Historical scaling events
- Container health status
+
## Technical details
+
Zerops monitors database usage and automatically adjusts resources based on predefined thresholds and timing parameters. The scaling behavior follows the same principles as other services in the platform.
+
For complete technical specifications including:
- Resource monitoring intervals and thresholds
- Scale-up and scale-down timing parameters
- Scaling increments and steps
- Detailed scaling behavior patterns
+
See [Resource Scaling Behavior](/features/scaling#resource-scaling-behavior) in the general scaling documentation.
+
## Common issues
+
**Out of memory errors**
- Increase minimum free RAM settings in your scaling configuration
- Consider raising the minimum RAM allocation
- Check for memory-intensive queries or operations
+
**Higher than expected costs**
- Consider lowering your maximum resource limits
- Review scaling patterns in the monitoring dashboard
+
**Slow database startup**
- Increase the "Start CPU cores" setting
- Consider switching to dedicated CPU mode for consistent performance
+
*Need help? Join our [Discord community](https://discord.gg/zerops) for assistance!*
----------------------------------------
# Mariadb > Overview
+
[MariaDB ↗](https://mariadb.org/) is one of the most popular open source relational databases. It’s made by the original developers of MySQL and guaranteed to stay open source.
+
## Feature Highlights
+
+- [Create MariaDB service](/mariadb/how-to/create) — Start with creating a MariaDB service using GUI or zCLI.
+- [Import config file](/mariadb/how-to/create#full-example) — Use an example config file to import your own app.
+
### Connect to MariaDB service
+
+- [Manage users and databases](/mariadb/how-to/manage)
+- [Connect from the same project](/mariadb/how-to/connect#connect-to-mariadb-from-runtime-services-of-the-same-project)
+- [Connect remotely](/mariadb/how-to/connect#connect-to-mariadb-in-zerops-remotely)
+
### Others
+
+- [Scale MariaDB service](/mariadb/how-to/scale)
+- [Export and import data](/mariadb/how-to/export-import-data)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+
+- [FAQ](/mariadb/faq) — Most common questions in one place.
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Mariadb > Tech Details > Cluster
+
The following description applies only to the [highly available mode](/features/scaling#highly-available-ha-mode) of the MariaDB service.
+
## Description of MariaDB cluster
+
MariaDB cluster in highly available mode contains 3 database containers and 2 free database proxies.
+
#### 1 write node + 2 read nodes
+
Zerops always keeps the 3 database containers on different physical machines. A MariaDB cluster node is installed in each database container. First a writer node is started followed by 2 read nodes. All your data is stored redundantly in 3 identical copies.
+
If the container with one of the reader nodes fails, Zerops disconnects it from the MariaDB cluster. Zerops then creates a new container with a MariaDB read node inside, connects it to the cluster and starts the synchronisation of the data to the new node. Finally the broken container is deleted.
+
If the container with the writer node fails, Zerops disconnects it from the MariaDB cluster and one of the read nodes is automatically promoted to the writer node. Zerops creates a new container with a MariaDB read node inside, connects it to the cluster and starts the synchronisation of the data to the new node. Finally the broken container is deleted.
+
#### 2 database proxies
+
Zerops uses [MaxScale 2.5 ↗](https://mariadb.com/kb/en/maxscale/), this database proxy is optimised specifically for MariaDB. MaxScale database proxy understands the mysql protocol. It forwards all **write requests** to the writer node and all **read requests** to read nodes.
+
Zerops creates 2 containers with MaxScale database proxy and connects them to the database cluster in the highly available infrastructure. Zerops always keep the 2 database proxies on different physical machines.
+
If a container with the database proxy fails, Zerops starts a new container automatically. Database proxy doesn't contain any data therefore the start of the new database proxy is fast.
+
## Synchronous vs. Asynchronous replication
+
#### Synchronous replication
+
Synchronous replication guarantees that when a change happens on the write node, it is replicated on the read nodes synchronously. Synchronous replication uses a distributed locking which proved to be very slow. The data replication from the write node to the read nodes takes some time and the write transactions must wait until the changed data is successfully replicated to all database nodes. In case one of the database nodes is overloaded, the whole cluster becomes very slow.
+
#### Asynchronous replication
+
Asynchronous replication gives no guarantees about the delay between applying changes on the write node and the propagation of changes to all read nodes. The delay is usually very short but when one of the read containers is overloaded the delay can be longer. The main benefit of the asynchronous replication is the performance. Write transaction is completed when the write node successfully commits the transaction locally and writes it to the write-ahead log that prevents the loss of data.
+
The downside of the asynchronous replication is no guarantee that the read nodes will always return the current data. In some cases a `SELECT` query that quickly follows the previous `COMMIT` may return old data. As mentioned above, the database proxy forwards all read requests to read nodes. When the read node processes the `SELECT` query before the replication of the previous transaction is finished, old data is returned.
+
Zerops uses the asynchronous replication in MariaDB cluster.
+
## How to deal with situations when old data is returned
+
#### Use explicit transactions
+
MariaDB cluster returns old data most often when you use the `SELECT` query right after the `COMMIT` in the same algorithm. This problem can be solved by moving the `SELECT` query into the transaction. All queries inside a `BEGIN..COMMIT` transaction are always executed against the write node.
+
#### Enable synchronous checks for SELECT queries
+
For a critical read that must have the most up-to-date data use the `wsrep_sync_wait` option:
+
```sh
SET SESSION wsrep_sync_wait=1;
SELECT ...;
SET SESSION wsrep_sync_wait=0;
```
+
When the `wsrep_sync_wait=1` option is used, the read node will synchronise data from the write node before executing the query. The read node will wait until all updates from the write node that were committed before the `SELECT` query was received and only then executes the query.
+
----------------------------------------
# Mariadb > Tech Details > Limitations
+
The following description applies only to the [highly available mode](/features/scaling#highly-available-ha-mode) of the MariaDB service.
+
#### InnoDB only
+
Only the InnoDB storage engine is supported.
+
#### Mandatory table primary key
+
All database tables should have a primary key. A multi-column primary key can also be used. `DELETE` operations are unsupported on tables without a primary key. Also, rows in tables without a primary key may appear in a different order on different nodes.
+
#### Limited locks support
+
No support for explicit locks, including `LOCK TABLES`, `FLUSH TABLES {explicit table list} WITH READ LOCK`, `GET_LOCK`, `RELEASE_LOCK`. These limitations can be overcome using transactions. Global locking operators like `FLUSH TABLES WITH READ LOCK` are supported.
+
#### Do not use local exports
+
Do not use `SELECT INTO OUTFILE` or `SELECT INTO DUMPFILE` commands. It will create a file on one of the database containers that will receive the request. Zerops doesn't support direct access into the MariaDB database containers so you won't be able to access the file. Learn more about [how to export and import MariaDB data](/mariadb/how-to/export-import-data).
+
[Full list of MariaDB cluster limitations ↗](https://mariadb.com/kb/en/mariadb-galera-cluster-known-limitations/)
+
----------------------------------------
# Meilisearch > Overview
+
Deploy and manage Meilisearch on a fully managed infrastructure. Get instant access to fast, typo-tolerant search with zero operational overhead.
+
## Supported Versions
+
Currently supported Meilisearch versions:
+
Import configuration version:
+
+- `meilisearch@1.20`
+- `meilisearch@1.10`
+
## Service Configuration
+
Our Meilisearch implementation runs as a **single-node** setup, as Meilisearch does not currently support cluster configurations.
+
### Environment Modes
+
:::note
Environment mode affects the availability of certain features and can impact your application's security. Choose carefully based on your use case.
:::
+
#### Production Mode (Default)
- Optimized for performance and security
- Search Preview (Mini-dashboard) disabled
- Recommended for production deployments
+
#### Development Mode
- Includes Search Preview (Mini-dashboard)
- Enhanced debugging capabilities
- Suitable for development and testing
+
To switch between modes:
1. Navigate to the **Environment variables** section in the Meilisearch service detail and scroll to the **Generated Variables**
2. Set the `environment` variable to either:
- `production` - for production mode (default)
- `development` - for development mode with Mini-dashboard
3. Restart the service to apply changes
+
### API Key Management
+
The service provides three pre-configured API keys, each with specific access levels:
+
#### `masterKey`
- Root access to your Meilisearch instance
- Use only for initial setup and key management
- **Never expose in application code or frontend**
+
#### `defaultSearchKey`
- Read-only search operations across all indices
- Safe for frontend implementations
- **Can be exposed in client-side code**
+
#### `defaultAdminKey`
- Full administrative access to all indices
- For backend operations and index management
- **Keep secure in backend services only**
+
[Custom API keys](https://www.meilisearch.com/docs/reference/api/keys) provide fine-grained access control for specific use cases. For example, you might create:
- Search-only keys for specific indices
- Temporary keys with expiration dates
- Keys with restricted actions for third-party integrations
+
## Network Architecture & Access
+
### Access Methods
+
#### Public HTTPS Access
When enabled, access via [Zerops subdomain](/references/networking/public-access#zerops-subdomain-access).
+
#### Internal Project Access
Services within the same project can reach Meilisearch directly:
```
http://{hostname}:7700
```
+
## Backup
+
Meilisearch backups are created using native dump commands:
+
- **Format**: `.dump` (standard Meilisearch dump)
- **Tooling**: Native dump command
- **Content**: Contains index data and settings
+
For backup configuration, scheduling, retention policies, and management options, see the [Zerops Backups](/features/backup) documentation.
+
### Restoring Backups
+
To restore a Meilisearch backup:
+
1. **Download** the backup file (`.dump`) from the Zerops UI
2. **Prepare** your target environment (clean existing indices or use a new instance)
3. **Restore** using the Meilisearch API. Use the dump import endpoint to restore your data. Follow the [official Meilisearch documentation](https://www.meilisearch.com/docs/learn/data_backup/dumps#importing-a-dump-in-self-hosted-instances) for detailed restore procedures.
+
For assistance with the restoration process, contact Zerops support.
+
## Quick Start Example
+
Here's a minimal example of implementing search in a React application:
+
```javascript
+
const MEILISEARCH_URL = process.env.zeropsSubdomain;
const SEARCH_KEY = process.env.defaultSearchKey;
+
function SearchComponent() {
const [results, setResults] = useState([]);
+
const handleSearch = async (query) => {
const response = await fetch(`${MEILISEARCH_URL}/indexes/products/search`, {
method: 'POST',
@@ -14387,55 +20610,73 @@ function SearchComponent() {
limit: 10
})
});
+
const data = await response.json();
setResults(data.hits);
};
+
return (
-
- handleSearch(e.target.value)}
+
);
}
```
+
## Best Practices
+
#### Security
- Store sensitive keys (`masterKey`, `defaultAdminKey`) securely in backend services
- Use `defaultSearchKey` or custom keys with minimal permissions for frontend
- Rotate custom keys periodically
+
#### Performance
- Implement debouncing for search inputs
- Cache frequently accessed search results
- Monitor response times and adjust index settings
- Use appropriate batch sizes for bulk operations
+
#### Error Handling
- Implement retry logic for temporary failures
- Set appropriate timeout values for your use case
- Handle rate limiting gracefully
+
## Troubleshooting
+
### Common Issues
+
#### Connection Problems
- Check if your instance is in the correct environment mode
- Ensure your API keys have the necessary permissions
- Confirm your service is running and healthy in the Zerops dashboard
+
#### Search Performance
- Review your index settings for optimal search performance
- Monitor your instance's resource usage
- Consider implementing client-side caching for frequent searches
+
#### API Key Issues
- Verify you're using the correct key type for your operation (search vs. admin)
- Check key permissions match your intended operations
- Ensure keys are properly formatted in your Authorization header
- Remember that master and admin keys should never be used in frontend code
+
## Learn More
+
- [Official Meilisearch Documentation](https://www.meilisearch.com/docs) - Comprehensive guide to all Meilisearch features and capabilities
- [API Reference](https://www.meilisearch.com/docs/reference/api/overview) - Detailed API specifications and usage examples
+
## Support
+
For advanced configurations or custom requirements:
- Join our [Discord community](https://discord.gg/zeropsio)
- Contact support via [email](mailto:support@zerops.io)
@@ -14444,90 +20685,141 @@ For advanced configurations or custom requirements:
# Nats > Overview
+
Zerops provides a fully managed [NATS](https://nats.io/) messaging system with automated scaling and zero infrastructure overhead, letting developers focus entirely on development.
+
## Supported Versions
+
Currently supported NATS version:
+
Import configuration version:
+
+- `nats@2.12`
+- `nats@2.10`
+
## Service Configuration
+
Our NATS implementation features optimized default settings designed for common use cases.
+
**Key configuration aspects** include:
- Standard protocol port `4222` for client connections
- HTTP monitoring interface `8222` for management
- Secure authentication with automatically generated credentials
- Optimized settings for performance and reliability
+
You can fine-tune your NATS service by adjusting **environment variables**:
+
### Available Configuration Options
+
:::note
If certain variables are not visible in your configuration, they may have been introduced after your service was created. Simply add them as [secret variables](/features/env-variables#2-secret-variables) to access the functionality.
:::
-
- Variable
- Description
-
- MAX_PAYLOAD
- Defines the maximum allowed message size for all NATS traffic. Default: 8MB, Maximum: 64MB. See NATS limits documentation for details.
-
- JET_STREAM_ENABLED
- Controls whether JetStream functionality is enabled. Default: 1 (enabled), Set to 0 to disable. See JetStream Configuration section below for more details.
-
+
+
+
+
+
Variable
+
Description
+
+
+
+
+
MAX_PAYLOAD
+
Defines the maximum allowed message size for all NATS traffic. Default: 8MB, Maximum: 64MB. See [NATS limits documentation](https://docs.nats.io/running-a-nats-service/configuration#limits) for details.
+
+
+
JET_STREAM_ENABLED
+
Controls whether JetStream functionality is enabled. Default: 1 (enabled), Set to 0 to disable. See [JetStream Configuration](#jetstream-configuration) section below for more details.
+
+
+
+
:::important
Configuration changes require a service **restart** to take effect. While NATS itself supports configuration hot-reload, this feature will be implemented in a future Zerops update.
:::
+
After restarting, check your service logs to confirm the changes were applied successfully.
+
### JetStream Configuration
+
The service includes [JetStream](https://docs.nats.io/nats-concepts/jetstream) functionality **enabled by default**, providing persistent storage capabilities for your messaging workloads:
- **Memory store**: Up to 40GB for high-performance message caching
- **File store**: Up to 250GB for persistent storage
- **Regular sync intervals**: Ensures data durability and consistency
+
:::note
In HA deployments, data persistence is further enhanced with 1-minute sync intervals across all nodes, ensuring robust data durability and high availability.
:::
+
This configuration provides a robust foundation for message persistence while balancing performance and reliability.
+
:::tip
Disabling JetStream can reduce resource utilization for applications that don't require message persistence.
:::
+
### Deployment Modes
+
:::warning
Deployment mode is selected during service creation and cannot be changed later.
:::
+
#### Non-HA Mode
- Suitable for development and testing
- Data persistence not guaranteed during node failures
- Lower resource requirements
+
#### HA Mode
- Creates a multi-node NATS cluster
- Configures routes between cluster nodes automatically
- Implements [NATS clustering](https://docs.nats.io/running-a-nats-service/configuration/clustering) for high availability
- Provides improved reliability compared to non-HA deployments
+
### Authentication Management
+
Authentication credentials are automatically generated and managed by the platform. The system creates a default user (`zerops`) with a secure 16-character password. You can access these credentials through:
- The service access details in the Zerops GUI
- Environment variables in your service configuration:
- `user` - Username for authentication (default: "zerops")
- `password` - Generated secure password
- `connectionString` - Complete connection string in the format `nats://${dbUser}:${dbPassword}@${hostname}:${port}`
+
## Health Monitoring
+
Zerops continuously monitors your NATS service health using built-in health checks:
+
- **HTTP Health Check**: The system checks the `/healthz` endpoint at port 8222
- **Self-Healing**: The platform automatically recovers unhealthy nodes when issues are detected
+
### Health Status
+
You can check the health status of your NATS service:
+
1. Through the Zerops GUI dashboard
2. By accessing the management interface at port `8222`
+
## Backup and Recovery
+
NATS backups are created using filesystem archival:
+
- **Format**: `.tar.gz` (archive of queue state)
- **Tooling**: Filesystem archival
- **Content**: Captures persistent message state
+
For backup configuration, scheduling, retention policies, and management options, see the [Zerops Backups](/features/backup) documentation.
+
### Restoring Backups
+
To restore a NATS backup:
+
1. **Download** the backup file (`.tar.gz`) from the Zerops UI
2. **Extract** the archive to access the queue state data
3. **Prepare** your target environment (clear existing data if needed)
4. **Restore** using NATS CLI commands via Zerops VPN or during deployment. Follow the [official NATS documentation](https://docs.nats.io/running-a-nats-service/nats_admin/jetstream_admin/disaster_recovery) for detailed restore procedures.
+
For assistance with the restoration process, contact Zerops support.
+
## Support
+
For advanced configurations or custom requirements:
- Join our [Discord community](https://discord.gg/zerops)
- Contact support via [email](mailto:support@zerops.io)
@@ -14536,25 +20828,33 @@ For advanced configurations or custom requirements:
# Nginx > Faq
- Question: How do I enable SEO optimization with prerender.io?
-Answer:
- Zerops provides built-in prerender.io support. Simply set the `PRERENDER_TOKEN` environment variable with your prerender.io service token. See our [prerender.io documentation](/nginx/how-to/env-variables#prerenderio-support) for details.
-
+
+ **Question: How do I enable SEO optimization with prerender.io?**
+
+Zerops provides built-in prerender.io support. Simply set the `PRERENDER_TOKEN` environment variable with your prerender.io service token. See our [prerender.io documentation](/nginx/how-to/env-variables#prerenderio-support) for details.
+
----------------------------------------
# Nginx > How To > Build Pipeline
+
Zerops provides a customizable build and runtime environment for your static content.
+
:::tip Two Deployment Approaches
You can use the Nginx service in two ways:
- **Runtime only**: Deploy pre-built static files directly (no build phase needed)
- **Build + Runtime**: Use a frontend framework (Node.js, PHP, Python, etc.) to build your application, then serve it with Nginx
+
The build phase is completely optional. If you already have built files, skip the build section and configure only the [runtime](#runtime-configuration).
+
If you just need to deploy your static content, use the [manual deploy](/nginx/how-to/trigger-pipeline#manual-deploy-using-zerops-cli) via Zerops CLI.
:::
+
## Add zerops.yaml to your repository
+
Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:
+
```yaml
zerops:
# define hostname of your service
@@ -14566,51 +20866,65 @@ zerops:
build:
# REQUIRED (if using build). Set the base technology for the build environment:
base: nodejs@latest
+
# OPTIONAL. Set the operating system for the build environment.
# os: ubuntu
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Build your application
buildCommands:
- npm i
- npm run build
+
# REQUIRED (if using build). Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- dist
- package.json
- node_modules
+
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: node_modules
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: nginx@latest
+
# OPTIONAL. Customize the runtime Nginx environment by installing additional
# dependencies to the base Nginx runtime environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Run one or more commands each time a new runtime container
# is started or restarted. These commands are triggered before
# your Nginx application is started.
# initCommands:
# - rm -rf ./cache
+
# OPTIONAL. Customize the folder that will be used as the root of the publicly
# accessible web server content. Enter the path relative to the /var/www folder.
documentRoot: public
+
# OPTIONAL. Sets the custom Nginx configuration. The file must be deployed in
# the runtime container. Enter the path to the file relative to the /var/www folder
siteConfigPath: site_config.tmpl
```
+
The top-level element is always `zerops`.
+
### Setup
+
The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:
+
```yaml
zerops:
# definition for app service
@@ -14621,6 +20935,7 @@ zerops:
deploy: ...
# required
run: ...
+
# definition for api service
- setup: api
# optional
@@ -14630,12 +20945,20 @@ zerops:
# required
run: ...
```
+
Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.
+
## Runtime configuration
+
### base
+
_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Nginx version for your runtime.
+
Following options are available for Nginx builds:
+
+- `nginx@1.22`, `nginx@latest`
+
```yaml
zerops:
# hostname of your service
@@ -14645,18 +20968,25 @@ zerops:
# REQUIRED (if using build). Sets the base technology for the build environment:
base: nodejs@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: nginx@latest
...
```
+
+
The base runtime environment contains {data.alpine.default}, the
- selected major version of Nginx, Zerops command line tool and `composer`, `git` and `wget`.
+ selected major version of Nginx, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -14666,6 +20996,7 @@ zerops:
# REQUIRED (if using build). Sets the base technology for the build environment:
base: nodejs@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
@@ -14675,52 +21006,86 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [run base environments](/zerops-yaml/base-list).
+
To customize your build environment use the `prepareCommands` attribute.
+
### os
+
_OPTIONAL._ Sets the operating system for the runtime environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customized.
:::
+
### ports
+
_OPTIONAL._ Specifies one or more internal ports on which your application will listen.
+
:::info
If no ports are specified, Zerops adds the port TCP 80 automatically.
:::
+
:::caution
If you want the web server to listen on other port(s) than `:80`, you must [customize](/nginx/how-to/customize-web-server) your web server configuration as well.
:::
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
For example, to connect to a Nginx static service with hostname = "app" and port = 80 from another service of the same project, simply use `app:80`. Read more about [how to access a Nginx static service](/references/networking/internal-access#basic-service-communication).
+
:::info
Do not use the port **:443**. All the incoming traffic is terminated on the Zerops internal balancer where the SSL certificate is installed and the request is forwarded to your Nginx static service as a **http://** on the port **:80**.
:::
+
Each port has following attributes:
-
- Parameter
- Description
-
- port
- Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
-
- protocol
- Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
-
- httpSupport
- Optional. httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of public access. httpSupport = true is available only in combination with the TCP protocol.
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
+
+
+
protocol
+
Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
+
+
+
httpSupport
+
Optional.httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). httpSupport = true is available only in combination with the TCP protocol.
+
+
+
+
### prepareCommands
+
_OPTIONAL._ Customizes the Nginx runtime environment by installing additional dependencies or tools to the runtime base environment.
+
+
The base Nginx environment contains {data.alpine.default}, the selected
- major version of Nginx, Zerops command line tool and `composer`, `git` and `wget`. To install
+ major version of Nginx, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`. To install
additional packages or tools add one or more prepare commands:
+
+
```yaml
zerops:
# hostname of your service
@@ -14728,6 +21093,7 @@ zerops:
# ==== how to build your application ====
build:
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -14737,28 +21103,45 @@ zerops:
- curl something else
...
```
+
When the first deploy with a defined prepare attribute is triggered, Zerops will
+
1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order
+
:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/nginx/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.
+
#### Cache of your custom runtime environment
+
Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:
+
1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.
+
To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.
-
+
When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances.
+
### Copy folders or files from your build container
+
+
The prepare runtime container contains {data.alpine.default}, the
- selected major version of Nginx, Zerops command line tool and `composer`, `git` and `wget`.
+ selected major version of Nginx, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`.
+
+
The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the build section of your chosen technology.
+
```yaml
zerops:
# hostname of your service
@@ -14767,6 +21150,7 @@ zerops:
build:
...
addToRunPrepare: ./runtime-config.yaml
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -14776,15 +21160,20 @@ zerops:
- curl something else
...
```
+
In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.
+
### initCommands
+
_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Run one or more commands each time a new runtime container
@@ -14793,48 +21182,71 @@ zerops:
initCommands:
- rm -rf ./cache
```
+
These commands are triggered in the runtime container before your Nginx application is started.
+
:::note
`run.initCommands` run in the `/var/www` directory.
:::
+
Use init commands to clean or initialise your application cache or similar operations.
+
:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/nginx/how-to/scaling) or when a runtime container is restarted).
+
Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands) attribute instead.
:::
+
#### Command exit code
+
If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/nginx/how-to/logs#runtime-log) to troubleshoot the error.
+
#### Single or separated shell instances
+
You can configure your `initCommands` to be run in a single shell instance or multiple shell instances.
+
### documentRoot
+
_OPTIONAL._ Customizes the folder that will be used as the root of the publicly accessible web server content.
+
:::info
By default, the document root is configured to `/var/www`.
:::
+
Customize the folder that will be used as the root of the publicly accessible web server content. Enter the path relative to the `/var/www` folder.
E.g. `documentRoot: public` will set the web server document root to `/var/www/public`.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the folder that will be used as the root of the publicly
# accessible web server content. Enter the path relative to the /var/www folder.
documentRoot: public
```
+
### siteConfigPath
+
_OPTIONAL._ Sets the custom Nginx configuration.
+
:::info
If you don't set your custom configuratiin Zerops applies the [default](/nginx/how-to/customize-web-server#default-nginx-configuration) configuration.
:::
+
The file must be deployed in the runtime container. Enter the path to the file relative to the `/var/www` folder.
Read more about the [web server customization](/nginx/how-to/customize-web-server).
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the runtime environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -14848,44 +21260,66 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/nginx/how-to/env-variables) in Zerops.
+
### health check
+
_OPTIONAL._ Defines a health check.
+
`healthCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the health check to request a local URL using a HTTP GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the folder that will be used as the root of the publicly
# accessible web server content. Enter the path relative to the /var/www folder.
documentRoot: public
+
# OPTIONAL. Define a health check with a HTTP GET request option.
# Configures the check on http://127.0.0.1:80/status
healthCheck:
@@ -14893,31 +21327,48 @@ zerops:
port: 80
path: /status
```
+
#### exec
+
Configures the health check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
Defines a local command to be run.
- The command has access to the same environment variables as your Nginx application.
+
+ The command has access to the same [environment variables](/nginx/how-to/create#set-secret-environment-variables) as your Nginx application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the folder that will be used as the root of the publicly
# accessible web server content. Enter the path relative to the /var/www folder.
documentRoot: public
+
# OPTIONAL. Define a health check with a shell command.
healthCheck:
exec:
@@ -14926,39 +21377,60 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
## Deploy configuration
+
### readiness check
+
_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/nginx/how-to/deploy-process#readiness-checks) in Zerops.
+
`readinessCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the readiness check to request a local URL using a http GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -14967,30 +21439,48 @@ zerops:
httpGet:
port: 80
path: /status
+
# ==== how to run your application ====
run: ...
```
+
Read more about how the [readiness check works](/nginx/how-to/deploy-process#readiness-checks) in Zerops.
+
#### exec
+
Configures the readiness check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
- Defines a local command to be run.
- The command has access to the same environment variables as your Nginx application.
- A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
-**Example:**
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
+ Defines a local command to be run.
+
+ The command has access to the same [environment variables](/nginx/how-to/create#set-secret-environment-variables) as your Nginx application.
+
+ A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
+
+
+
+
+
+**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -15002,6 +21492,7 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
Read more about how the [readiness check works](/nginx/how-to/deploy-process#readiness-checks) in Zerops.
----------------------------------------
@@ -15014,35 +21505,60 @@ Read more about how the [readiness check works](/nginx/how-to/deploy-process#rea
# Nginx > How To > Create
+
The Nginx static service contains the Nginx web server optimized for your static content. Nginx static service is highly scalable and customisable to suit both development and production.
+
## Create Nginx static service using Zerops GUI
+
First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Nginx static service:
+
+[Video: /vids/services/nginx-static.webm](/vids/services/nginx-static.webm)
+
### Choose Nginx version
+
Following Nginx versions are currently supported:
+
:::info
You can [change](/nginx/how-to/upgrade) the major version at any time later.
:::
+
### Set a hostname
+
Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.
+
#### Limitations:
+
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::
+
### Set secret environment variables
+
Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.
+
Setting the secret environment variables is optional. You can set them later in Zerops GUI.
+
Read more about [different types of env variables](/nginx/how-to/env-variables#service-env-variables) in Zerops.
+
## Create Nginx static service using zCLI
+
zCLI is the Zerops command-line tool. To create a new Nginx static service via the command-line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/nginx/how-to/create#create-a-project-description-file)
3. [Create a project with a Nginx and PostgreSQL service](#full-example)
+
### Create a project description file
+
Zerops uses a yaml format to describe the project infrastructure.
+
#### Basic example:
+
Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -15063,13 +21579,18 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes your future project infrastructure. The project will contain one Nginx version 8.1 service with default [auto scaling](/nginx/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/nginx/how-to/build-pipeline#ports). Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
#### Full example:
+
Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:
+
```yaml
# basic project data
project:
@@ -15108,110 +21629,187 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes your future project infrastructure. The project will contain an Nginx static service with `app` hostname. The internal port(s) the service listens on will be defined later in the [zerops.yaml](/nginx/how-to/build-pipeline#ports). Nginx static service will run on version 1.22 with a custom vertical and horizontal scaling. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
-
- Parameter
- Description
- Limitations
-
- name
- The name of the new project. Duplicates are allowed.
-
- description
- Optional. Description of the new project.
- Maximum 255 characters.
-
- tags
- Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
-
+
+
+
+
+
Parameter
+
Description
+
Limitations
+
+
+
+
+
name
+
The name of the new project. Duplicates are allowed.
+
+
+
+
description
+
Optional. Description of the new project.
+
Maximum 255 characters.
+
+
+
tags
+
Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
+
+
+
+
+
At least one service in `services:` section is required. You can create a project with multiple services. The example above contains an Nginx static service but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
+ hostname
+
+
The unique service identifier.
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
+ type
+
+
Specifies the service type and version.
-
+
See what [nginx service types](/references/import-yaml/type-list#runtime-services) are currently supported.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto scaling parameters.
+
+
+
+
+ verticalAutoscaling
+
+
+ Optional. Defines [custom vertical auto scaling parameters](/nginx/how-to/create#set-auto-scaling-configuration).
+
All verticalAutoscaling attributes are optional. Not specified
attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
- minContainers
-
- Optional. Default = 1. Defines the minimum number of containers
- for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
+ - cpuMode
+
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
+ - minCpu/maxCpu
+
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
+ - minRam/maxRam
+
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
+ - minDisk/maxDisk
+
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
+ minContainers
+
+
+ Optional. Default = 1. Defines the minimum number of containers
+ for [horizontal autoscaling](/nginx/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- maxContainers
-
- Defines the maximum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
+ maxContainers
+
+
+ Defines the maximum number of containers for [horizontal autoscaling](/nginx/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- envSecrets
-
- Optional. Defines one or more secret env variables as a key value
- map. See env variable restrictions.
-
+
+
+
+
+ envSecrets
+
+
+ Optional. Defines one or more secret env variables as a key value
+ map. See env variable [restrictions](/nginx/how-to/env-variables#env-variable-restrictions).
+
+
+
+
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add Nginx static service to an existing project
+
#### Example:
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -15232,98 +21830,146 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Nginx static service version 1.22 with default [auto scaling](/nginx/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the import.yaml file is 100 kB.
+
----------------------------------------
# Nginx > How To > Customize Runtime
+
## Build Custom Runtime Images
+
Zerops allows you to build custom runtime images (CRI) when the default base runtime images don't meet your Nginx Static application's requirements. This is an optional phase in the [build and deploy pipeline](/features/pipeline#runtime-prepare-phase-optional).
+
:::important
You should not include your application code in the custom runtime image, as your built/packaged code is deployed automatically into fresh containers.
:::
+
## Configuration
+
### Default Nginx Static Runtime Environment
+
The default Nginx Static runtime environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- Selected version of Nginx when the runtime service was created
- [zCLI](/references/cli)
- Git
+
### When You Need a Custom Runtime Image
+
If your Nginx Static service needs additional tools beyond the default environment (SSL management, monitoring, security tools, etc.), you'll need to build a custom runtime image.
+
Here are Nginx Static-specific examples of configuring custom runtime images in your `zerops.yml`:
+
### Basic Nginx Static Setup
-
+
For complete configuration details, see the [runtime prepare phase configuration guide](/features/pipeline#configuration).
+
## Process and Caching
+
### How Runtime Prepare Works
The runtime prepare process follows the same steps for all runtimes. See [how runtime prepare works](/features/pipeline#how-it-works) for the complete process details.
+
### Caching Behavior
Zerops caches custom runtime images to optimize deployment times. Learn about [custom runtime image caching](/features/pipeline#custom-runtime-image-caching) including when images are cached and reused.
+
### Build Management
For information about managing builds and deployments, see [managing builds and deployments](/features/pipeline#manage-builds-and-deployments).
+
:::warning
Shared storage mounts are not available during the runtime prepare phase.
:::
+
## Troubleshooting
+
If your `prepareCommands` fail, check the [prepare runtime log](/nginx/how-to/logs#prepare-runtime-log) for specific error messages.
----------------------------------------
# Nginx > How To > Customize Web Server
+
## Default Nginx configuration
+
The default Nginx static service has following configuration:
+
```
server {
listen 80 default_server;
listen [::]:80 default_server;
+
server_name _;
root {{.DocumentRoot}};
+
location / {
try_files $uri $uri/ /index.html;
}
+
access_log syslog:server=unix:/dev/log,facility=local1,tag=nginx,severity=info default_short;
error_log syslog:server=unix:/dev/log,facility=local1,tag=nginx,severity=error;
}
```
+
The configuration contains 2 variables:
-- **`{{.DocumentRoot}}`** is replaced by the `run.documentRoot` attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.
+
+- **`{{.DocumentRoot}}`** is replaced by the [`run.documentRoot`](/nginx/how-to/build-pipeline#documentroot) attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.
+
## Customize Nginx configuration
+
Follow these steps to customize the Nginx configuration in Nginx static service:
+
1. Create a **.tmpl** file with the Nginx configuration in your repository.
+
2. Optionally use following variables:
-- **`{{.DocumentRoot}}`** is replaced by the `run.documentRoot` attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.
+
+- **`{{.DocumentRoot}}`** is replaced by the [`run.documentRoot`](/nginx/how-to/build-pipeline#documentroot) attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.
+
Example:
+
```
root {{.DocumentRoot}};
```
+
- **`{{.Environment.ENV_NAME}}`** is replaced by the [env variable](/nginx/how-to/env-variables) value. The env variable must be either defined in [run.envVariables](/nginx/how-to/build-pipeline#envvariables) in `zerops.yaml` or set as a [secret](/nginx/how-to/env-variables#set-secret-env-variables-in-zerops-gui) or [generated](/nginx/how-to/env-variables#generated-env-variables) env variable in Zerops GUI.
+
:::caution
Use the **.tmpl** file extension to make Zerops interpret the file as a template. Zerops will replace the supported variables listed above.
:::
+
3. Check that your Nginx configuration is consistent with Zerops requirements:
+
- Do not use IP addresses in the `listen` directive
-- If you use other ports than `:80` in the `listen` directive, add them to the `run.ports` in your `zerops.yaml` as well.
+- If you use other ports than `:80` in the `listen` directive, add them to the [`run.ports`](/nginx/how-to/build-pipeline#ports) in your `zerops.yaml` as well.
- Do not use the port **:443**. All the incoming `https://` traffic is terminated on the Zerops internal balancer where the SSL certificate is installed and the request is forwarded to your Nginx static service as a **http://** on the port **:80**.
-4. Add the `siteConfigPath` to the run section of your `zerops.yaml`
+
+4. Add the [`siteConfigPath`](/nginx/how-to/build-pipeline#siteconfigpath) to the run section of your `zerops.yaml`
+
```yaml
zerops:
# define hostname of your service
@@ -15332,27 +21978,40 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: nodejs@latest
+
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- vendor
- public
+
# ==== how to run your application ====
run:
documentRoot: public
+
# OPTIONAL. Sets the custom Nginx or Apache configuration. The file must be deployed in the runtime container. Enter the path to the file relative to the /var/www folder
siteConfigPath: site_config.tmpl
```
-5. Ensure that the `build.deployFiles` contains the folder with the `siteConfigPath` or add the path to the Nginx config file to the `deployFiles` list. Zerops will deploy the file to the runtime container(s).
+
+5. Ensure that the [`build.deployFiles`](/nginx/how-to/build-pipeline#deployfiles) contains the folder with the `siteConfigPath` or add the path to the Nginx config file to the `deployFiles` list. Zerops will deploy the file to the runtime container(s).
+
6. [Trigger](/nginx/how-to/trigger-pipeline) the build & deploy pipeline.
+
## SEO & Prerender Support
+
Single Page Applications and JavaScript-heavy sites render content client-side, which most crawlers can't process—they see an empty page instead of your content. This affects traditional search engines, social media platforms, and AI tools like ChatGPT, Perplexity, and Claude.
+
### Built-in Prerender.io Integration
+
The default Nginx configuration includes automatic [Prerender.io](https://prerender.io) support. When enabled, it detects crawler requests (including AI crawlers) and serves them pre-rendered HTML while your users get the full interactive experience.
+
### Setup
+
To enable prerender support:
+
1. Set the `PRERENDER_TOKEN` environment variable with your Prerender.io token (see [environment variables](/nginx/how-to/env-variables#prerenderio-support))
2. Optionally set `PRERENDER_HOST` if using a custom prerender server
+
The Nginx configuration will automatically handle the rest—no additional configuration needed.
----------------------------------------
@@ -15365,27 +22024,40 @@ The Nginx configuration will automatically handle the rest—no additional confi
# Nginx > How To > Env Variables
+
## Prerender.io Support
+
Zerops provides built-in prerender.io support for SEO optimization. Configure it using these environment variables:
-
- Variable
- Required
- Description
- Default
-
- PRERENDER_TOKEN
- Yes
- Your prerender.io service token
- -
-
- PRERENDER_HOST
- No
- Prerender service host
- service.prerender.io
-
+
+
+
+
+
Variable
+
Required
+
Description
+
Default
+
+
+
+
+
PRERENDER_TOKEN
+
Yes
+
Your prerender.io service token
+
-
+
+
+
PRERENDER_HOST
+
No
+
Prerender service host
+
service.prerender.io
+
+
+
+
:::tip
Set `PRERENDER_TOKEN` as a secret environment variable in Zerops GUI for security.
:::
+
Example in zerops.yaml:
```yaml
zerops:
@@ -15435,36 +22107,68 @@ zerops:
# Nginx > Overview
+
The Nginx static service contains the [Nginx ↗](https://nginx.org/) web server optimized for your static content.
+
## How to start
+
+- [Care for details?](/nginx/how-to/create) — Dive in all Zerops has to offer for your Nginx application.
+
## Feature Highlights
+
+- [Create Nginx static service](/nginx/how-to/create) — Start with creating a Nginx static service using GUI or zCLI.
+- [zerops.yaml](/nginx/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
+- [Scaling configuration](/nginx/how-to/scaling) — Set up scaling of your Nginx application so that it runs smoothly while using only necessary resources.
+- [SEO Optimization](/nginx/how-to/env-variables#prerenderio-support) — Built-in prerender.io support for better SEO.
+
{" "}
+
+- [Customize build environment](/nginx/how-to/create)
+- [Customize runtime environment](/nginx/how-to/customize-runtime)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+
+- [FAQ](/nginx/faq) — Most common questions in one place.
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Nodejs > Faq
- Question: Why is my Node.js build timing out or hanging on interactive prompts?
-Answer:
- If your build process seems to be hanging or timing out, check your logs for interactive prompts that are waiting for input, such as:
+
+ **Question: Why is my Node.js build timing out or hanging on interactive prompts?**
+
+If your build process seems to be hanging or timing out, check your logs for interactive prompts that are waiting for input, such as:
```
? The modules directory at "/build/source/node_modules" will be removed and reinstalled from scratch. Proceed? (Y/n) ‣ true
```
+
Set the environment variable `CI: true` to resolve the problem. This allows the installation to proceed automatically without requiring manual confirmation.
-
+
----------------------------------------
# Nodejs > How To > Build Pipeline
+
Zerops provides a customizable build and runtime environment for your Node.js application.
+
## Add zerops.yaml to your repository
+
Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:
+
```yaml
zerops:
# define hostname of your service
@@ -15473,51 +22177,65 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: nodejs@latest
+
# OPTIONAL. Set the operating system for the build environment.
# os: ubuntu
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Build your application
buildCommands:
- npm i
- npm run build
+
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- dist
- package.json
- node_modules
+
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: node_modules
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: nodejs@latest
+
# OPTIONAL. Sets the internal port(s) your app listens on:
ports:
# port number
- port: 3000
+
# OPTIONAL. Customize the runtime Node.js environment by installing additional
# dependencies to the base Node.js runtime environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Run one or more commands each time a new runtime container
# is started or restarted. These commands are triggered before
# your Node.js application is started.
# initCommands:
# - rm -rf ./cache
+
# REQUIRED. Your Node.js application start command
start: npm start
```
+
The top-level element is always `zerops`.
+
### Setup
+
The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:
+
```yaml
zerops:
# definition for app service
@@ -15528,6 +22246,7 @@ zerops:
deploy: ...
# required
run: ...
+
# definition for api service
- setup: api
# optional
@@ -15537,11 +22256,22 @@ zerops:
# required
run: ...
```
+
Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.
+
## Build pipeline configuration
+
### base
+
_REQUIRED._ Sets the base technology for the build environment.
+
Following options are available for Node.js builds:
+
+- `nodejs@24`, `nodejs@latest`
+- `nodejs@22`
+- `nodejs@20`
+- `nodejs@18`
+
```yaml
zerops:
# hostname of your service
@@ -15552,12 +22282,18 @@ zerops:
base: nodejs@latest
...
```
+
+
The base build environment contains {data.alpine.default}, the selected
- major version of Node.js, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
+ major version of Node.js, [Zerops command line tool](/references/cli), `npm`, `yarn`, `git` and `npx` tools.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -15571,34 +22307,52 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).
+
To customize your build environment use the [prepareCommands](#preparecommands) attribute.
+
:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::
+
### os
+
_OPTIONAL._ Sets the operating system for the build environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customized.
:::
+
:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::
+
### prepareCommands
+
_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.
+
The base build environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- selected version of Node.js defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `npm`, `yarn`, `git` and `npx` tools
+
To install additional packages or tools add one or more prepare commands:
+
```yaml
zerops:
# hostname of your service
@@ -15607,6 +22361,7 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: nodejs@latest
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
prepareCommands:
@@ -15614,20 +22369,31 @@ zerops:
- curl something else
...
```
+
When the first build is triggered, Zerops will
+
1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order
+
The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.
+
:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/nodejs/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### buildCommands
+
_OPTIONAL._ Defines build commands.
+
```yaml
zerops:
# hostname of your service
@@ -15636,42 +22402,59 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: nodejs@latest
+
# OPTIONAL. Build your application
buildCommands:
- npm i
- npm run build
...
```
+
Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.
+
Before the build commands are triggered the build container contains:
+
1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code
+
#### Run build commands as a single shell instance
+
Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.
+
```yaml
buildCommands:
- |
npm i
npm run build
```
+
#### Run build commands as a separate shell instances
+
When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.
+
```yaml
buildCommands:
- npm i
- npm run build
```
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/nodejs/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option.
+
```yaml
buildCommands:
- npm i --verbose
- npm run build
```
+
If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.
+
### deployFiles
-_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use `.deployignore` file.
+
+_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.
+
```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
@@ -15680,56 +22463,81 @@ deployFiles:
- package.json
- node_modules
```
+
Determines files or folders produced by your build, which should be deployed to your runtime service containers.
+
The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.
+
The files/folders will be placed into `/var/www` folder in runtime, e.g. `./src/assets/fonts` would result in `/var/www/src/assets/fonts`.
+
#### Examples
+
Deploys a folder, and a file from the project root directory:
+
```yaml
deployFiles:
- dist
- package.json
```
+
Deploys the whole content of the build container:
+
```yaml
deployFiles: .
```
+
Deploys a folder, and a file in a defined path:
+
```yaml
deployFiles:
- ./path/to/file.txt
- ./path/to/dir/
```
+
#### How to use a wildcard in the path
+
Zerops supports the `~` character as a wildcard for one or more folders in the path.
+
Deploys all `file.txt` files that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/file.txt
```
+
Deploys all folders that are located in any path that begins with `/path/to/`
+
```yaml
deployFiles: ./path/to/~/
```
+
Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/
```
+
:::note Example
By default, `./src/assets/fonts` deploys to `/var/www/src/assets/fonts`, keeping the full path. Adding `~`, like `./src/assets/~fonts`, shortens it to `/var/www/fonts`
:::
#### .deployignore
-Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as `.gitignore`.
+
+Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as [`.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format).
+
To ignore a specific file or directory path, start the pattern with a forward slash (`/`). Without the leading slash, the pattern will match files with that name in any directory.
+
:::tip
For consistency, it's recommended to configure both your `.gitignore` and `.deployignore` files with the same patterns.
:::
+
Examples:
+
```yaml title="zerops.yaml"
zerops:
- setup: app
build:
deployFiles: ./
```
+
```text title=".deployignore"
/src/file.txt
```
@@ -15741,22 +22549,33 @@ This example above ignores `file.txt` in ANY directory named `src`, such as:
- `/src/file.txt`
- `/folder2/folder3/src/file.txt`
- `/src/src/file.txt`
+
:::note
-`.deployignore` file also works with `zcli service deploy` command.
+`.deployignore` file also works with [`zcli service deploy`](/references/zcli/commands#deploy) command.
:::
+
### cache
+
_OPTIONAL._ Defines which files or folders will be cached for the next build.
+
```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```
+
The cache attribute helps optimize build times by preserving specified files between builds.
+
The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).
+
Learn more about the [build cache system](/features/build-cache) in Zerops.
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the build environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -15765,6 +22584,7 @@ zerops:
build:
base: nodejs@latest
…
+
# OPTIONAL. Defines the env variables for the build environment:
envVariables:
NODE_ENV: production
@@ -15773,12 +22593,23 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/nodejs/how-to/env-variables) in Zerops.
+
## Runtime configuration
+
### base
+
_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Node.js version for your runtime.
+
Following options are available for Node.js builds:
+
+- `nodejs@24`, `nodejs@latest`
+- `nodejs@22`
+- `nodejs@20`
+- `nodejs@18`
+
```yaml
zerops:
# hostname of your service
@@ -15788,18 +22619,25 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: nodejs@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: nodejs@latest
...
```
+
+
The base runtime environment contains {data.alpine.default}, the
selected major version of Node.js, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -15809,6 +22647,7 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: nodejs@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
@@ -15818,43 +22657,74 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [run base environments](/zerops-yaml/base-list).
+
To customize your build environment use the `prepareCommands` attribute.
+
### os
+
_OPTIONAL._ Sets the operating system for the runtime environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customized.
:::
+
### ports
+
_OPTIONAL._ Specifies one or more internal ports on which your application will listen.
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
For example, to connect to a Node.js service with hostname = "app" and port = 3000 from another service of the same project, simply use `app:3000`. Read more about [how to access a Node.js service](/references/networking/internal-access#basic-service-communication).
+
Each port has following attributes:
-
- Parameter
- Description
-
- port
- Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
-
- protocol
- Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
-
- httpSupport
- Optional. httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of public access. httpSupport = true is available only in combination with the TCP protocol.
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
+
+
+
protocol
+
Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
+
+
+
httpSupport
+
Optional.httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). httpSupport = true is available only in combination with the TCP protocol.
+
+
+
+
### prepareCommands
+
_OPTIONAL._ Customises the Node.js runtime environment by installing additional dependencies or tools to the runtime base environment.
+
+
The base Node.js environment contains {data.alpine.current} the selected
- major version of Node.js, Zerops command line tool and `npm`, `yarn`, `git` and `npx` tools. To install
+ major version of Node.js, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools. To install
additional packages or tools add one or more prepare commands:
+
+
```yaml
zerops:
# hostname of your service
@@ -15862,6 +22732,7 @@ zerops:
# ==== how to build your application ====
build:
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -15871,27 +22742,45 @@ zerops:
- curl something else
...
```
+
When the first deploy with a defined prepare attribute is triggered, Zerops will
+
1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order
+
:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/nodejs/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.
+
#### Cache of your custom runtime environment
+
Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:
+
1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.
+
To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.
+
When the custom runtime cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### Copy folders or files from your build container
+
+
The prepare runtime container contains {data.alpine.current}, the
- selected major version of Node.js, Zerops command line tool and `npm`, `yarn`, `git` and `npx` tools.
+ selected major version of Node.js, [Zerops command line tool](/references/cli) and `npm`, `yarn`, `git` and `npx` tools.
+
+
The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).
+
```yaml
zerops:
# hostname of your service
@@ -15900,6 +22789,7 @@ zerops:
build:
...
addToRunPrepare: ./runtime-config.yaml
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -15909,15 +22799,20 @@ zerops:
- curl something else
...
```
+
In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.
+
### initCommands
+
_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Run one or more commands each time a new runtime container
@@ -15926,22 +22821,35 @@ zerops:
initCommands:
- rm -rf ./cache
```
+
These commands are triggered in the runtime container before your Node.js application is started via the [start command](#start).
+
:::note
`run.initCommands` run in the `/var/www` directory.
:::
+
Use init commands to clean or initialise your application cache or similar operations.
+
:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/nodejs/how-to/scaling) or when a runtime container is restarted).
+
Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::
+
#### Command exit code
+
If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/nodejs/how-to/logs#runtime-log) to troubleshoot the error.
+
#### Single or separated shell instances
+
You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the runtime environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -15956,57 +22864,84 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/nodejs/how-to/env-variables) in Zerops.
+
### start
+
_REQUIRED._ Defines the start command for your Node.js application.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Node.js application start command
start: npm start
```
+
We recommend starting your Node.js application using `npm start`.
+
### health check
+
_OPTIONAL._ Defines a health check.
+
`healthCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the health check to request a local URL using a HTTP GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Node.js application start command
start: npm start
+
# OPTIONAL. Define a health check with a HTTP GET request option.
# Configures the check on http://127.0.0.1:80/status
healthCheck:
@@ -16014,30 +22949,47 @@ zerops:
port: 80
path: /status
```
+
#### exec
+
Configures the health check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
Defines a local command to be run.
- The command has access to the same environment variables as your Node.js application.
+
+ The command has access to the same [environment variables](/nodejs/how-to/create#set-secret-environment-variables) as your Node.js application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Node.js application start command
start: npm start
+
# OPTIONAL. Define a health check with a shell command.
healthCheck:
exec:
@@ -16046,13 +22998,18 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
### crontab
+
_OPTIONAL._ Defines cron jobs.
+
Setup cron jobs in the following format:
+
```yaml
zerops:
# define hostname of your service
- setup: app
+
# ==== how to run your application ====
run:
crontab:
@@ -16061,72 +23018,112 @@ zerops:
# REQUIRED. Sets the interval time to execute:
timing: "0 * * * *"
```
+
Read more about setting up [cron](/zerops-yaml/cron) in Zerops.
+
## Deploy configuration
+
### readiness check
+
_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/nodejs/how-to/deploy-process#readiness-checks) in Zerops.
+
`readinessCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the readiness check to request a local URL using a http GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
-**Example:**
-```yaml
-zerops:
- # hostname of your service
- - setup: app
- # ==== how to build your application ====
- build: ...
- # ==== how to deploy your application ====
- deploy:
- # OPTIONAL. Define a readiness check with a HTTP GET request option.
- # Configures the check on http://127.0.0.1:80/status
- readinessCheck:
- httpGet:
- port: 80
- path: /status
- # ==== how to run your application ====
- run: ...
-```
-Read more about how the [readiness check works](/nodejs/how-to/deploy-process#readiness-checks) in Zerops.
-#### exec
-Configures the readiness check to run a local command.
-Following attributes are available:
-
- Parameter
- Description
-
- command
-
- Defines a local command to be run.
- The command has access to the same environment variables as your Node.js application.
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
+**Example:**
+
+```yaml
+zerops:
+ # hostname of your service
+ - setup: app
+ # ==== how to build your application ====
+ build: ...
+
+ # ==== how to deploy your application ====
+ deploy:
+ # OPTIONAL. Define a readiness check with a HTTP GET request option.
+ # Configures the check on http://127.0.0.1:80/status
+ readinessCheck:
+ httpGet:
+ port: 80
+ path: /status
+
+ # ==== how to run your application ====
+ run: ...
+```
+
+Read more about how the [readiness check works](/nodejs/how-to/deploy-process#readiness-checks) in Zerops.
+
+#### exec
+
+Configures the readiness check to run a local command.
+Following attributes are available:
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
+ Defines a local command to be run.
+
+ The command has access to the same [environment variables](/nodejs/how-to/create#set-secret-environment-variables) as your Node.js application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -16138,8 +23135,10 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
Read more about how the [readiness check works](/nodejs/how-to/deploy-process#readiness-checks) in Zerops.
+
----------------------------------------
# Nodejs > How To > Build Process
@@ -16156,34 +23155,58 @@ Read more about how the [readiness check works](/nodejs/how-to/deploy-process#re
# Nodejs > How To > Create
+
Zerops provides a powerful Node.js runtime service with extensive build support. The Node.js runtime is highly scalable and customizable to suit your development and production needs. With just a few clicks or commands, you can have a production-ready Node.js environment up and running in no time.
+
## Create a Node.js service using Zerops GUI
+
First, set up a project in the Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu under the **Services** section. From there, you can add a new Node.js service:
+
+[Video: /vids/services/nodejs.webm](/vids/services/nodejs.webm)
+
### Choose a Node.js version
+
Zerops supports the following Node.js versions:
+
:::info
You can easily [upgrade](/nodejs/how-to/upgrade) the major version at any time later.
:::
+
### Set a hostname
+
Enter a unique service identifier like "app", "cache", "gui", etc. Duplicate services with the same name within the same project are not allowed.
+
#### Limitations:
+
- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::
+
### Set secret environment variables
+
Add environment variables with sensitive data, such as passwords, tokens, salts, certificates, etc. These will be securely saved inside Zerops and added to your runtime service upon start.
+
Setting secret environment variables is optional. You can always set them later in the Zerops GUI.
+
Read more about the [different types of environment variables](/nodejs/how-to/env-variables#service-env-variables) in Zerops.
+
## Create a Node.js service using zCLI
+
zCLI is the Zerops command-line tool. To create a new Node.js service via the command line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/nodejs/how-to/create#create-a-project-description-file)
3. [Create a project with a Node.js and PostgreSQL service](#full-example)
+
### Create a project description file
+
Zerops uses a YAML format to describe the project infrastructure.
+
#### Basic example:
+
Create a directory called `my-project`. Inside the `my-project` directory, create a `description.yaml` file with the following content:
```yaml
# basic project data
@@ -16205,13 +23228,18 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes your future project infrastructure. The project will contain one Node.js version 20 service with default [auto scaling](/nodejs/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/nodejs/how-to/build-pipeline#ports). Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
#### Full example:
+
Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:
+
```yaml
# basic project data
project:
@@ -16256,114 +23284,172 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain a Node.js service and a [PostgreSQL](/postgresql/overview) service.
+
Node.js service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/nodejs/how-to/build-pipeline#ports). Node.js service will run on version 20 with a custom vertical and horizontal scaling. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
-
- Parameter
- Description
- Limitations
-
- name
- The name of the new project. Duplicates are allowed.
-
- description
- Optional. Description of the new project.
- Maximum 255 characters.
-
- tags
- Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
-
+
+
+
+
+
Parameter
+
Description
+
Limitations
+
+
+
+
+
name
+
The name of the new project. Duplicates are allowed.
+
+
+
+
description
+
Optional. Description of the new project.
+
Maximum 255 characters.
+
+
+
tags
+
Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
+
+
+
+
+
At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Node.js and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
hostname
+
The unique service identifier.
-
+
The hostname of the new database will be set to the `hostname` value.
-
- Limitations:
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+ Limitations:
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
type
+
Specifies the service type and version.
-
+
See what [Node.js service types](/references/import-yaml/type-list#runtime-services) are currently supported.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto scaling parameters.
-
+
+
+
+
verticalAutoscaling
+
+ Optional. Defines [custom vertical auto scaling parameters](/nodejs/how-to/create#set-auto-scaling-configuration).
+
All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
- minContainers
-
- Optional. Default = 1. Defines the minimum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
- cpuMode
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
- minCpu/maxCpu
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
- minRam/maxRam
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
- minDisk/maxDisk
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
minContainers
+
+ Optional. Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/nodejs/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- maxContainers
-
- Defines the maximum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
maxContainers
+
+ Defines the maximum number of containers for [horizontal autoscaling](/nodejs/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- envSecrets
-
- Optional. Defines one or more secret env variables as a key value map. See env variable restrictions.
-
+
+
+
+
envSecrets
+
+ Optional. Defines one or more secret env variables as a key value map. See env variable [restrictions](/nodejs/how-to/env-variables#env-variable-restrictions).
+
+
+
+
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add Node.js service to an existing project
+
#### Example:
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -16384,33 +23470,38 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Node.js service version 20 with default [auto scaling](/nodejs/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the import.yaml file is 100 kB.
+
----------------------------------------
# Nodejs > How To > Customize Runtime
-System packages for processing: When your app processes images, videos, or files (requiring packages like sudo apk add imagemagick, sudo apk add ffmpeg)',
- 'Global Node.js tools: When you need CLI tools or utilities available system-wide (like pm2 for process management)',
- 'Native dependencies: When your npm packages require system libraries that aren\'t in the default environment',
- 'Different base OS: When you need Ubuntu instead of Alpine for specific compatibility requirements'
-]} />
+
----------------------------------------
@@ -16464,123 +23555,213 @@ System packages for processing: When your app processes images, videos, or files
# Nodejs > Overview
+
[Node.js ↗](https://nodejs.org/en) is an asynchronous event-driven JavaScript runtime, which is designed to build scalable network applications.
+
As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-nodejs), a **_recipe_**, containing the most simple Node.js web application. The repo will be used as a source from which the app will be built.
- This is the most bare-bones example of Node.js app running in Zerops — as few libraries as possible,
+
+### 🚀 Feel free to deploy the recipe yourself
+
+This is the most bare-bones example of Node.js app running in Zerops — as few libraries as possible,
just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.
-
+
+ [Deploy "node-js" recipe on Zerops](https://app.zerops.io/recipe/?lf=node-js)
+
1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
+
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-nodejs/blob/main/zerops-project-import.yaml)):
+
```yaml
project:
name: recipe-nodejs
tags:
- zerops-recipe
+
services:
- hostname: api
type: nodejs@20
enableSubdomainAccess: true
buildFromGit: https://github.com/zeropsio/recipe-nodejs
+
- hostname: db
type: postgresql@16
mode: NON_HA
priority: 1
```
+
3. Click on **Import project** and wait until all pipelines have finished.
+
**That's it, your application is now up and running! :star: Let's check it works:**
+
1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://helloworld-24-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see
+
```
Hello, World!
```
+
:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::
+
## How to start
+
It doesn't matter whether it's your first curious introduction to Zerops, you have already mastered the basics and are looking for a tiny detail or inspiration. Below, choose a section that fits your needs:
+
+- [Care for details?](/nodejs/how-to/create) — Dive in all Zerops has to offer for your Node.js application.
+- [Node.js recipes](https://github.com/zeropsio?q=nodejs&type=all&language=&sort=) — Get inspired by already existing repositories, ready to be imported to Zerops.
+
## Feature Highlights
+
+- [Create Node.js service](/nodejs/how-to/create) — Start with creating a Node.js service using GUI or zCLI.
+- [zerops.yaml](/nodejs/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
+- [Scaling configuration](/nodejs/how-to/scaling) — Set up scaling of your Node.js application so that it runs smoothly while using only necessary resources.
+
{" "}
+
+- [Customize build environment](/nodejs/how-to/build-process#customize-build-environment)
+- [Customize runtime environment](/nodejs/how-to/customize-runtime)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+
+- [FAQ](/nodejs/faq) — Most common questions in one place.
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Object Storage > How To > Access
+
Zerops Object storage is powered by [MinIO](https://min,io), a high-performance, S3 compatible object store. Object storage services are operated on an independent infrastructure separated from your other project services. You can access the object storage from any service hosted in Zerops or remotely over the internet.
+
## Object storage bucket
+
Zerops creates one bucket automatically for each new Object storage service.
+
:::note
Each Object storage service can only contain one bucket. If your application needs multiple buckets, add more Object storage services.
:::
+
#### Name
+
Bucket is created with a name based on the selected service name and a random prefix. The name of the bucket cannot be changed later.
+
#### Access policy
+
The bucket's access policy was defined when the Object storage service was created. You can [change it] later in Zerops GUI.
+
#### Quota
+
The bucket quota size was defined when the Object storage service was created. You can [change it] later in Zerops GUI.
+
## Copy access details from Zerops GUI
+
You will find the Object storage access details under the **Access details** button in the project dashboard page.
+
The same information is available in the service detail page under the **Access & bucket details** menu.
-
+
### Object storage access parameters
-
- Parameter
- Description
-
- API URL
- URL of the Object storage service
-
- Bucket Name
- Bucket is created with a name based on the selected service name and a random prefix. The name of the bucket is fixed and cannot be changed later.
-
- Access Key ID
- The S3 Access Key ID
-
- Secret Key
- The S3 Secret Key
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
API URL
+
URL of the Object storage service
+
+
+
Bucket Name
+
Bucket is created with a name based on the selected service name and a random prefix. The name of the bucket is fixed and cannot be changed later.
+
+
+
Access Key ID
+
The S3 Access Key ID
+
+
+
Secret Key
+
The S3 Secret Key
+
+
+
+
## Use Object storage environment variables
+
Zerops creates default environment variables for each Object storage service to help you with connection from any runtime services in the same project. To avoid the need to copy Object storage access parameters manually, use environment variables in your runtime service.
+
### Prefix the environment variable key
+
All services of the same project can reference environment variables from other services. To use an environment variable from one service in another service in the same project, you must prefix the environment variable key with the service name and underscore.
+
#### Example
+
To access the `bucketName` env variable of the `upload` service, use `upload_bucketName` as the env variable key. To access the `secretAccessKey` env variable of the `storage` service, use `storage_secretAccessKey` as the env variable key.
+
### Object storage environment variables
+
List of service environment variables is available in Zerops GUI. Go to an Object storage service detail and choose **Environment variables** in the left menu.
-
+
Zerops creates following environment variables when the Object storage service is created:
-
- Variable
- Description
-
- apiUrl
- URL of the Object storage service
-
- accessKeyId
- The S3 Access Key ID
-
- secretAccessKey
- The S3 Secret Key
-
- bucketName
- Bucket is created with a name based on the selected service name and a random prefix. The name of the bucket is fixed and cannot be changed later.
-
- quotaGBytes
- The bucket quota in GB.
-
- projectId
- ID of the project. Generated by Zerops.
-
- serviceId
- ID of the Object storage service. Generated by Zerops.
-
- hostname
- The name of the Object storage service.
-
+
+
+
+
+
Variable
+
Description
+
+
+
+
+
apiUrl
+
URL of the Object storage service
+
+
+
accessKeyId
+
The S3 Access Key ID
+
+
+
secretAccessKey
+
The S3 Secret Key
+
+
+
bucketName
+
Bucket is created with a name based on the selected service name and a random prefix. The name of the bucket is fixed and cannot be changed later.
+
+
+
quotaGBytes
+
The bucket quota in GB.
+
+
+
projectId
+
ID of the project. Generated by Zerops.
+
+
+
serviceId
+
ID of the Object storage service. Generated by Zerops.
+
+
+
hostname
+
The name of the Object storage service.
+
+
+
+
----------------------------------------
@@ -16592,63 +23773,101 @@ Zerops creates following environment variables when the Object storage service i
# Object Storage > How To > Create
+
Zerops provides a S3 compatible Object storage service to store your files. Zerops Object storage is powered by [MinIO](https://min.io), a high-performance, S3 compatible object store. MinIO is built for large scale AI/ML, data lake and database workloads.
+
## Create Object storage service using Zerops GUI
+
First, set up a project in Zerops GUI and add a runtime service. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Object storage service:
+
+[Video: /vids/services/object-storage.webm](/vids/services/object-storage.webm)
+
### Set a name
+
Enter a unique service identifier like `storage`,`s3` etc. Duplicate services with the same name in the same project are forbidden.
+
#### Limitations:
+
maximum 25 characters
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::note
The name is fixed after the service is created. It can't be changed later.
:::
+
### Object storage bucket
+
Zerops creates one bucket automatically for each new Object storage service.
+
:::note
Each Object storage service can only contain one bucket. If your application needs multiple buckets, add more Object storage services.
:::
+
#### Name
+
Bucket will be created with a name based on the given service name and a random prefix. The name of the bucket cannot be changed later.
+
#### Access policy
+
Select one of the basic policy templates:
-
- Template
- Description
-
- Public read
-
+
+
+
+
+
Template
+
Description
+
+
+
+
+
Public read
+
Allows anyone:
-
- to read the bucket's location `(s3:GetBucketLocation)`
- to list all bucket's objects `(s3:ListBucket)`
- to get any object of the bucket `(s3:GetObject)`
-
- Public objects read
-
+
+
to read the bucket's location `(s3:GetBucketLocation)`
+
to list all bucket's objects `(s3:ListBucket)`
+
to get any object of the bucket `(s3:GetObject)`
+
+
+
+
+
Public objects read
+
Allows anyone:
-
- to read the bucket's location `(s3:GetBucketLocation)`
- to get any object of the bucket `(s3:GetObject)`
-
- Public read write
-
+
+
to read the bucket's location `(s3:GetBucketLocation)`
+
to get any object of the bucket `(s3:GetObject)`
+
+
+
+
+
Public read write
+
Allows anyone:
-
- to read the bucket's location `(s3:GetBucketLocation)`
- to list all bucket's objects `(s3:ListBucket)`
- to get any object of the bucket `(s3:GetObject)`
- to create a new object in the bucket `(s3:PutObject,s3:ListMultipartUploadParts, s3:AbortMultipartUpload, s3:ListBucketMultipartUploads)`
- to delete any object of the bucket `(s3:DeleteObject)`
-
- Public write
- Allows anyone to create objects in the bucket `(PutObject action)`
-
- Private
- Denies the access to unauthenticated users.
-
+
+
to read the bucket's location `(s3:GetBucketLocation)`
+
to list all bucket's objects `(s3:ListBucket)`
+
to get any object of the bucket `(s3:GetObject)`
+
to create a new object in the bucket `(s3:PutObject,s3:ListMultipartUploadParts, s3:AbortMultipartUpload, s3:ListBucketMultipartUploads)`
+
to delete any object of the bucket `(s3:DeleteObject)`
+
+
+
+
+
Public write
+
Allows anyone to create objects in the bucket `(PutObject action)`
+
+
+
Private
+
Denies the access to unauthenticated users.
+
+
+
+
Or you can set your own access policy in the [IAM Policy JSON format](https://min.io/docs/minio/linux/administration/identity-access-management/policy-based-access-control.html#policy-document-structure).
+
#### Example:
+
```yaml
{
'Version': '2012-10-17',
@@ -16669,171 +23888,250 @@ Or you can set your own access policy in the [IAM Policy JSON format](https://mi
],
}
```
+
:::tip
The `{{ .BucketName }}` variable will be replaced by the bucket name.
:::
+
The bucket's policy can be changed later in Zerops GUI.
+
#### Quota
+
Set the bucket quota size in GB. The quota must be set manually. It can be changed later in Zerops GUI. Zerops doesn't support Object storage autoscaling. You can set the bucket quota from 1 to 100 GB.
-
+
## Create Object storage using zCLI
+
zCLI is the Zerops command-line tool. To create a new Object storage service via the command-line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](#create-a-project-description-file)
3. Create a project and an Object storage service
+
### Create a project description file
+
Zerops uses a yaml format file to describe the project infrastructure.
+
#### Example
+
Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content:
+
```yaml
# basic project data
project:
# project name
name: my-project
+
# optional: project description
description: A project with an Object storage
+
# optional: project tags
tags:
- DEMO
- ZEROPS
+
# array of project services
services:
- # service name
hostname: upload
+
# service type
type: objectstorage
+
# Object storage size in GB
objectStorageSize: 73
+
# Choose object storage policy from a predefined list
objectStoragePolicy: public-write
+
# Or define a custom policy
objectStorageRawPolicy:
```
+
The yaml file describes your future project infrastructure. The project will contain one Object storage service named `upload`. The bucket quota will be set to 73 GB and the bucket access policy will be set to `public-write`.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
-
- Parameter
- Description
- Limitations
-
- name
- The name of the new project. Duplicates are allowed.
- Maximum 255 characters
-
- description
- Optional. Description of the new project.
-
- tags
- Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
-
+
+
+
+
+
Parameter
+
Description
+
Limitations
+
+
+
+
+
name
+
The name of the new project. Duplicates are allowed.
+
Maximum 255 characters
+
+
+
description
+
Optional. Description of the new project.
+
+
+
+
tags
+
Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
+
+
+
+
+
At least one service in `services:` section is required. You can create a project with multiple services. The example above contains only Object storage service but you can create a description.yaml with different types of services.
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
hostname
+
The unique service identifier.
-
- Limitations:
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+ Limitations:
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
type
+
Specifies the Object storage type objectstorage and version.
-
+
Set type: `objectstorage`
-
- Limitations:
-
+
+ Limitations:
+
Currently `objectstorage` or `object-storage` is available.
-
- objectStorageSize
-
+
+
+
+
objectStorageSize
+
The size of the bucket quota in GB.
-
- Limitations:
-
+
+ Limitations:
+
Set a whole number between 1 and 100.
-
- objectStoragePolicy
-
- Optional. Either `objectStoragePolicy` or `objectStorageRawPolicy` is required.
-
+
+
+
+
objectStoragePolicy
+
+ Optional. Either `objectStoragePolicy` or `objectStorageRawPolicy` is required.
+
Set one of allowed values:
-
- `public-read`
- `public-objects-read`
- `public-read-write`
- `public-write`
- `private`
-
- Read more about the basic policy templates.
-
- objectStorageRawPolicy
-
- Optional. Either `objectStoragePolicy` or `objectStorageRawPolicy` is required.
-
- Set your own access policy in the IAM Policy JSON format.
-
+
+
`public-read`
+
`public-objects-read`
+
`public-read-write`
+
`public-write`
+
`private`
+
+ Read more about [the basic policy templates](#access-policy).
+
+
+
+
objectStorageRawPolicy
+
+ Optional. Either `objectStoragePolicy` or `objectStorageRawPolicy` is required.
+
+ Set your own access policy in the [IAM Policy JSON format](https://min.io/docs/minio/linux/administration/identity-access-management/policy-based-access-control.html#policy-document-structure).
+
The `{{ .BucketName }}` variable will be replaced by the bucket name.
-
+
+
+
+
+
Zerops creates one bucket automatically for each new Object storage service.
+
:::note
Each Object storage service can only contain one bucket. If your application needs multiple buckets, add more Object storage services.
:::
+
Bucket will be created with a name based on the given service name and a random prefix. The name of the bucket cannot be changed later.
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add Object service to an existing project
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```yaml
# array of project services
services:
- # service name
hostname: upload
+
# service type
type: objectstorage
+
# Object storage size in GB
objectStorageSize: 73
+
# Choose object storage policy from a predefined list
objectStoragePolicy: public-write
+
# Or define a custom policy
objectStorageRawPolicy:
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Object storage service named upload will be created. The bucket quota will be set to 73 GB and the bucket access policy will be set to `public-write`.
+
The content of the `services:` section of `import.yaml` is identical to the [project description file]. The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the `import.yaml` file is 100 kB.
+
#### Example
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```bash
# array of project services
services:
@@ -16843,55 +24141,76 @@ services:
# service type
type: objectstorage
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Object storage service in the single container mode with default auto scaling configuration will be added to your project. Hostname of the new service will be set to `storage`.
+
The content of the `services:` section of `import.yaml` is identical to the [project description file](#create-a-project-description-file). The `import.yaml` never contains the `project:` section because the project already exists.
+
----------------------------------------
# Object Storage > How To > Curl File
+
This guide explains how to download a single file from a private Object Storage bucket using cURL and a bash script with Zerops object storage.
+
## Prerequisites
+
- Access to Zerops Object Storage
- Storage credentials (`ACCESS_KEY_ID` and `SECRET_ACCESS_KEY`)
- Bash environment
- OpenSSL and cURL installed
+
:::caution
Store your storage credentials securely and never commit them to version control.
:::
+
## Script
+
Save this script as `download-storage.sh`:
+
```bash
#!/bin/bash
+
server="${3:-storage-prg1.zerops.io}"
file_path=$2
bucket=$1
set -eu pipefail
+
contentType="application/octet-stream"
dateValue=`date -R`
signature_string="GET\n\n${contentType}\n${dateValue}\n/${bucket}/${file_path}"
+
signature_hash=`echo -en ${signature_string} | openssl sha1 -hmac ${SECRET_ACCESS_KEY} -binary | base64`
+
curl -sSo ${file_path} \
-H "Date: ${dateValue}" \
-H "Content-Type: ${contentType}" \
-H "Authorization: AWS ${ACCESS_KEY_ID}:${signature_hash}" \
"https://${server}/${bucket}/${file_path}"
+
```
+
## Usage
+
1. Make the script executable:
```bash
chmod +x download-storage.sh
```
+
2. Set your storage credentials as environment variables:
```bash
export ACCESS_KEY_ID=your-access-key
export SECRET_ACCESS_KEY=your-secret-key
```
+
3. Run the script:
```bash
./download-storage.sh my-bucket file.pdf
```
+
## Troubleshooting
+
- **Permission Denied**: Check your `ACCESS_KEY_ID` and `SECRET_ACCESS_KEY`
- **File Not Found**: Verify bucket name and file path
- **Script Error**: Ensure the script has execute permissions
@@ -16900,23 +24219,35 @@ export SECRET_ACCESS_KEY=your-secret-key
# Object Storage > How To > Update Bucket
+
Zerops creates one bucket automatically for each new Object storage service.
+
:::note
Each Object storage service can only contain one bucket. If your application needs multiple buckets, add more Object storage services.
:::
+
To change the bucket size or the access policy, go to the **Access & bucket details** in the Object service detail in Zerops GUI, scroll down and click on the **Configure bucket quota size and access policy** button.
-
+
### Quota
+
Set the bucket quota size in GB. The quota must be set manually. It can be changed later in Zerops GUI. Zerops doesn't support Object storage autoscaling. You can set the bucket quota from 1 to 100 GB.
+
### Access policy
+
Zerops creates one bucket automatically for each new Object storage service.
+
:::note
Each Object storage service can only contain one bucket. If your application needs multiple buckets, add more Object storage services.
:::
+
#### Name
+
Bucket will be created with a name based on the given service name and a random prefix. The name of the bucket cannot be changed later.
+
#### Access policy
+
Select one of the basic policy templates:
+
| Template | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Public read | Allows anyone:
to read the bucket's location `(s3:GetBucketLocation)`
to list all bucket's objects `(s3:ListBucket)`
to get any object of the bucket `(s3:GetObject)`
|
@@ -16925,8 +24256,11 @@ Select one of the basic policy templates:
| Public write | Allows anyone to create objects in the bucket `(PutObject action)` |
| Private | Denies the access to unauthenticated users. |
| Private | Denies the access to unauthenticated users. |
+
Or you can set your own access policy in the [IAM Policy JSON format](https://min.io/docs/minio/linux/administration/identity-access-management/policy-based-access-control.html#policy-document-structure).
+
#### Example:
+
```yaml
{
'Version': '2012-10-17',
@@ -16947,29 +24281,53 @@ Or you can set your own access policy in the [IAM Policy JSON format](https://mi
],
}
```
+
:::tip
The `{{ .BucketName }}` variable will be replaced by the bucket name.
:::
+
----------------------------------------
# Object Storage > Overview
+
Zerops Object storage is powered by [MinIO ↗](https://min.io/), a high-performance, open-source S3 compatible object store. MinIO is built for large scale AI/ML, data lake and database workloads.
+
## Feature Highlights
+
+- [Create Object Storage](/object-storage/how-to/create) — Create your first storage bucket with our step-by-step guide.
+- [Customize Object Storage buckets](/object-storage/how-to/update-bucket) — Configure Object Storage to meet your application needs.
+- [Access Object storage](/object-storage/how-to/access#copy-access-details-from-zerops-gui) — Simplify configuration with environment variables.
+
## Popular Guides
+
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+- [FAQ](/nodejs/faq) — Most common questions in one place.
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
+
----------------------------------------
# Php > How To > Build Pipeline
+
Zerops provides a customizable build and runtime environment for your PHP application.
+
## Add zerops.yaml to your repository
+
Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:
+
```yaml
zerops:
# define hostname of your service
@@ -16978,49 +24336,63 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: php-apache@latest
+
# OPTIONAL. Set the operating system for the build environment.
# os: ubuntu
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Build your application
buildCommands:
- composer install
+
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- vendor
- public
+
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
# cache: vendor
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: php-apache@latest
+
# OPTIONAL. Customize the runtime PHP environment by installing additional
# dependencies to the base PHP runtime environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# OPTIONAL. Run one or more commands each time a new runtime container
# is started or restarted. These commands are triggered before
# your PHP application is started.
# initCommands:
# - rm -rf ./cache
+
# OPTIONAL. Customize the folder that will be used as the root of the publicly
# accessible web server content. Enter the path relative to the /var/www folder.
documentRoot: public
+
# OPTIONAL. Sets the custom Nginx or Apache configuration. The file must be deployed in
# the runtime container. Enter the path to the file relative to the /var/www folder
siteConfigPath: site_config.tmpl
```
+
The top-level element is always `zerops`.
+
### Setup
+
The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:
+
```yaml
zerops:
# definition for app service
@@ -17031,6 +24403,7 @@ zerops:
deploy: ...
# required
run: ...
+
# definition for api service
- setup: api
# optional
@@ -17040,11 +24413,22 @@ zerops:
# required
run: ...
```
+
Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.
+
## Build pipeline configuration
+
### base
+
_REQUIRED._ Sets the base technology for the build environment.
+
Following options are available for PHP builds:
+
+- `php@8.5`, `php@latest`
+- `php@8.4`
+- `php@8.3`
+- `php@8.1`
+
```yaml
zerops:
# hostname of your service
@@ -17055,12 +24439,18 @@ zerops:
base: php-apache@latest
...
```
+
+
The base build environment contains {data.alpine.default}, the selected
- major version of PHP, Zerops command line tool, `composer`, `git` and `wget`.
+ major version of PHP, [Zerops command line tool](/references/cli), `composer`, `git` and `wget`.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -17074,34 +24464,52 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).
+
To customise your build environment use the [prepareCommands](#preparecommands) attribute.
+
:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::
+
### os
+
_OPTIONAL._ Sets the operating system for the build environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customised.
:::
+
:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::
+
### prepareCommands
+
_OPTIONAL._ Customises the build environment by installing additional dependencies or tools to the base build environment.
+
The base build environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- selected version of PHP defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `composer`, `git` and `wget`
+
To install additional packages or tools add one or more prepare commands:
+
```yaml
zerops:
# hostname of your service
@@ -17110,6 +24518,7 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: php-apache@latest
+
# OPTIONAL. Customise the build environment by installing additional packages
# or tools to the base build environment.
prepareCommands:
@@ -17117,20 +24526,31 @@ zerops:
- curl something else
...
```
+
When the first build is triggered, Zerops will
+
1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order
+
The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.
+
:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/php/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### buildCommands
+
_OPTIONAL._ Defines build commands.
+
```yaml
zerops:
# hostname of your service
@@ -17139,40 +24559,57 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: php-apache@latest
+
# OPTIONAL. Build your application
buildCommands:
- composer install
...
```
+
Build commands are optional. Zerops triggers each command in the defined order in a dedicated build container, running from the `/build/source` directory.
+
Before the build commands are triggered the build container contains:
+
1. base environment defined by the [base](#base) attribute
2. optional customisation of the base environment defined in the [prepareCommands](#preparecommands) attribute
3. your application code
+
#### Run build commands as a single shell instance
+
Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.
+
```yaml
buildCommands:
- |
composer install --optimize-autoloader --no-dev
php artisan env
```
+
#### Run build commands as a separate shell instances
+
When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.
+
```yaml
buildCommands:
- composer install --optimize-autoloader --no-dev
- php artisan env
```
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/php/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the verbose option.
+
```yaml
buildCommands:
- composer install -v
```
+
If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase.
+
### deployFiles
-_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use `.deployignore` file.
+
+_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.
+
```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
@@ -17180,56 +24617,81 @@ deployFiles:
- vendor
- public
```
+
Determines files or folders produced by your build, which should be deployed to your runtime service containers.
+
The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.
+
The files/folders will be placed into `/var/www` folder in runtime, e.g. `./src/assets/fonts` would result in `/var/www/src/assets/fonts`.
+
#### Examples
+
Deploys a folder, and a file from the project root directory:
+
```yaml
deployFiles:
- public
- file.txt
```
+
Deploys the whole content of the build container:
+
```yaml
deployFiles: .
```
+
Deploys a folder, and a file in a defined path:
+
```yaml
deployFiles:
- ./path/to/file.txt
- ./path/to/dir/
```
+
#### How to use a wildcard in the path
+
Zerops supports the `~` character as a wildcard for one or more folders in the path.
+
Deploys all `file.txt` files that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/file.txt
```
+
Deploys all folders that are located in any path that begins with `/path/to/`
+
```yaml
deployFiles: ./path/to/~/
```
+
Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/
```
+
:::note Example
By default, `./src/assets/fonts` deploys to `/var/www/src/assets/fonts`, keeping the full path. Adding `~`, like `./src/assets/~fonts`, shortens it to `/var/www/fonts`
:::
#### .deployignore
-Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as `.gitignore`.
+
+Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as [`.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format).
+
To ignore a specific file or directory path, start the pattern with a forward slash (`/`). Without the leading slash, the pattern will match files with that name in any directory.
+
:::tip
For consistency, it's recommended to configure both your `.gitignore` and `.deployignore` files with the same patterns.
:::
+
Examples:
+
```yaml title="zerops.yaml"
zerops:
- setup: app
build:
deployFiles: ./
```
+
```text title=".deployignore"
/src/file.txt
```
@@ -17241,22 +24703,33 @@ This example above ignores `file.txt` in ANY directory named `src`, such as:
- `/src/file.txt`
- `/folder2/folder3/src/file.txt`
- `/src/src/file.txt`
+
:::note
-`.deployignore` file also works with `zcli service deploy` command.
+`.deployignore` file also works with [`zcli service deploy`](/references/zcli/commands#deploy) command.
:::
+
### cache
+
_OPTIONAL._ Defines which files or folders will be cached for the next build.
+
```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```
+
The cache attribute helps optimize build times by preserving specified files between builds.
+
The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).
+
Learn more about the [build cache system](/features/build-cache) in Zerops.
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the build environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -17265,6 +24738,7 @@ zerops:
build:
base: php-apache@latest
…
+
# OPTIONAL. Defines the env variables for the build environment:
envVariables:
PHP_ENV: production
@@ -17273,12 +24747,28 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/php/how-to/env-variables) in Zerops.
+
## Runtime configuration
+
### base
+
_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current PHP version for your runtime.
+
Following options are available for PHP builds:
+
+- `php-apache@8.5`, `php-apache@latest`
+- `php-apache@8.4`
+- `php-apache@8.3`
+- `php-apache@8.1`
+
+- `php-nginx@8.5`, `php-nginx@latest`
+- `php-nginx@8.4`
+- `php-nginx@8.3`
+- `php-nginx@8.1`
+
```yaml
zerops:
# hostname of your service
@@ -17288,18 +24778,25 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: php-apache@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: php-apache@latest
...
```
+
+
The base runtime environment contains {data.alpine.default}, the
- selected major version of PHP, Zerops command line tool and `composer`, `git` and `wget`.
+ selected major version of PHP, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -17309,6 +24806,7 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: php-apache@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
@@ -17318,52 +24816,86 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [run base environments](/zerops-yaml/base-list).
+
To customise your build environment use the `prepareCommands` attribute.
+
### os
+
_OPTIONAL._ Sets the operating system for the runtime environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customised.
:::
+
### ports
+
_OPTIONAL._ Specifies one or more internal ports on which your application will listen.
+
:::info
If no ports are specified, Zerops adds the port TCP 80 automatically.
:::
+
:::caution
If you want the web server to listen on other port(s) than `:80`, you must [customize](/php/how-to/customize-web-server) your web server configuration as well.
:::
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
For example, to connect to a PHP service with hostname = "app" and port = 80 from another service of the same project, simply use `app:80`. Read more about [how to access a PHP service](/references/networking/internal-access#basic-service-communication).
+
:::info
Do not use the port **:443**. All the incoming traffic is terminated on the Zerops internal balancer where the SSL certificate is installed and the request is forwarded to your PHP+Nginx / PHP+Apache service as a **http://** on the port **:80**.
:::
+
Each port has following attributes:
-
- Parameter
- Description
-
- port
- Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
-
- protocol
- Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
-
- httpSupport
- Optional. httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of public access. httpSupport = true is available only in combination with the TCP protocol.
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
+
+
+
protocol
+
Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
+
+
+
httpSupport
+
Optional.httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). httpSupport = true is available only in combination with the TCP protocol.
+
+
+
+
### prepareCommands
+
_OPTIONAL._ Customises the PHP runtime environment by installing additional dependencies or tools to the runtime base environment.
+
+
The base PHP environment contains {data.alpine.default}, the selected
- major version of PHP, Zerops command line tool and `composer`, `git` and `wget`. To install
+ major version of PHP, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`. To install
additional packages or tools add one or more prepare commands:
+
+
```yaml
zerops:
# hostname of your service
@@ -17371,6 +24903,7 @@ zerops:
# ==== how to build your application ====
build:
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -17380,28 +24913,45 @@ zerops:
- curl something else
...
```
+
When the first deploy with a defined prepare attribute is triggered, Zerops will
+
1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order
+
:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/php/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.
+
#### Cache of your custom runtime environment
+
Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:
+
1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.
+
To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.
-
+
When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### Copy folders or files from your build container
+
+
The prepare runtime container contains {data.alpine.default}, the
- selected major version of PHP, Zerops command line tool and `composer`, `git` and `wget`.
+ selected major version of PHP, [Zerops command line tool](/references/cli) and `composer`, `git` and `wget`.
+
+
The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).
+
```yaml
zerops:
# hostname of your service
@@ -17410,6 +24960,7 @@ zerops:
build:
...
addToRunPrepare: ./runtime-config.yaml
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -17419,15 +24970,20 @@ zerops:
- curl something else
...
```
+
In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.
+
### initCommands
+
_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Run one or more commands each time a new runtime container
@@ -17436,48 +24992,71 @@ zerops:
initCommands:
- rm -rf ./cache
```
+
These commands are triggered in the runtime container before your PHP application is started.
+
:::note
`run.initCommands` run in the `/var/www` directory.
:::
+
Use init commands to clean or initialise your application cache or similar operations.
+
:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/php/how-to/scaling) or when a runtime container is restarted).
+
Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::
+
#### Command exit code
+
If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/php/how-to/logs#runtime-log) to troubleshoot the error.
+
#### Single or separated shell instances
+
You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands).
+
### documentRoot
+
_OPTIONAL._ Customizes the folder that will be used as the root of the publicly accessible web server content.
+
:::info
By default, the document root is configured to `/var/www`.
:::
+
Customize the folder that will be used as the root of the publicly accessible web server content. Enter the path relative to the `/var/www` folder.
E.g. `documentRoot: public` will set the web server document root to `/var/www/public`.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the folder that will be used as the root of the publicly
# accessible web server content. Enter the path relative to the /var/www folder.
documentRoot: public
```
+
### siteConfigPath
+
_OPTIONAL._ Sets the custom Nginx or Apache configuration.
+
:::info
By default, the default [nginx](/php/how-to/customize-web-server#default-nginx-configuration) or [Apache](/php/how-to/customize-web-server#default-apache-configuration) web server configuration is set.
:::
+
The file must be deployed in the runtime container. Enter the path to the file relative to the `/var/www` folder.
Read more about the [web server customization](/php/how-to/customize-web-server).
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the runtime environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -17492,44 +25071,66 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/php/how-to/env-variables) in Zerops.
+
### health check
+
_OPTIONAL._ Defines a health check.
+
`healthCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the health check to request a local URL using a HTTP GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the folder that will be used as the root of the publicly
# accessible web server content. Enter the path relative to the /var/www folder.
documentRoot: public
+
# OPTIONAL. Define a health check with a HTTP GET request option.
# Configures the check on http://127.0.0.1:80/status
healthCheck:
@@ -17537,31 +25138,48 @@ zerops:
port: 80
path: /status
```
+
#### exec
+
Configures the health check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
Defines a local command to be run.
- The command has access to the same environment variables as your PHP application.
+
+ The command has access to the same [environment variables](/php/how-to/create#set-secret-environment-variables) as your PHP application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the folder that will be used as the root of the publicly
# accessible web server content. Enter the path relative to the /var/www folder.
documentRoot: public
+
# OPTIONAL. Define a health check with a shell command.
healthCheck:
exec:
@@ -17570,13 +25188,18 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
### crontab
+
_OPTIONAL._ Defines cron jobs.
+
Setup cron jobs in the following format:
+
```yaml
zerops:
# define hostname of your service
- setup: app
+
# ==== how to run your application ====
run:
crontab:
@@ -17585,40 +25208,62 @@ zerops:
# REQUIRED. Sets the interval time to execute:
timing: "0 * * * *"
```
+
Read more about setting up [cron](/zerops-yaml/cron) in Zerops.
+
## Deploy configuration
+
### readiness check
+
_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/php/how-to/deploy-process#readiness-checks) in Zerops.
+
`readinessCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the readiness check to request a local URL using a http GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
-**Example:**
-```yaml
-zerops:
- # hostname of your service
- - setup: app
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
+**Example:**
+
+```yaml
+zerops:
+ # hostname of your service
+ - setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -17627,30 +25272,48 @@ zerops:
httpGet:
port: 80
path: /status
+
# ==== how to run your application ====
run: ...
```
+
Read more about how the [readiness check works](/php/how-to/deploy-process#readiness-checks) in Zerops.
+
#### exec
+
Configures the readiness check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
Defines a local command to be run.
- The command has access to the same environment variables as your PHP application.
+
+ The command has access to the same [environment variables](/php/how-to/create#set-secret-environment-variables) as your PHP application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -17662,8 +25325,10 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
Read more about how the [readiness check works](/php/how-to/deploy-process#readiness-checks) in Zerops.
+
----------------------------------------
# Php > How To > Build Process
@@ -17680,35 +25345,58 @@ Read more about how the [readiness check works](/php/how-to/deploy-process#readi
# Php > How To > Create
+
Zerops provides 2 PHP services with an included web server: **PHP+Nginx** and **PHP+Apache**. PHP runtime is highly scalable and customisable to suit both development and production.
+
## Create PHP service using Zerops GUI
+
First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new PHP service:
+
### Choose PHP version
+
Following PHP versions are currently supported:
+
:::info
You can [change](/php/how-to/upgrade) the major version at any time later.
:::
+
### Set a hostname
+
Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.
+
#### Limitations:
+
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::
+
### Set secret environment variables
+
Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.
+
Setting the secret environment variables is optional. You can set them later in Zerops GUI.
+
Read more about [different types of env variables](/php/how-to/env-variables#service-env-variables) in Zerops.
+
## Create PHP service using zCLI
+
zCLI is the Zerops command-line tool. To create a new PHP service via the command-line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/php/how-to/create#create-a-project-description-file)
3. [Create a project with a PHP and PostgreSQL service](#full-example)
+
### Create a project description file
+
Zerops uses a yaml format to describe the project infrastructure.
+
#### Basic example:
+
Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -17729,13 +25417,18 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes your future project infrastructure. The project will contain one PHP version 8.1 service with default [auto scaling](/php/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/php/how-to/build-pipeline#ports). Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
#### Full example:
+
Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:
+
```yaml
# basic project data
project:
@@ -17780,114 +25473,172 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain a PHP service and a [PostgreSQL](/postgresql/overview) service.
+
PHP service with "app" hostname, the internal port(s) the service listens on will be defined later in the [zerops.yaml](/php/how-to/build-pipeline#ports). PHP service will run on version 8.1 with a custom vertical and horizontal scaling. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
-
- Parameter
- Description
- Limitations
-
- name
- The name of the new project. Duplicates are allowed.
-
- description
- Optional. Description of the new project.
- Maximum 255 characters.
-
- tags
- Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
-
+
+
+
+
+
Parameter
+
Description
+
Limitations
+
+
+
+
+
name
+
The name of the new project. Duplicates are allowed.
+
+
+
+
description
+
Optional. Description of the new project.
+
Maximum 255 characters.
+
+
+
tags
+
Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
+
+
+
+
+
At least one service in `services:` section is required. You can create a project with multiple services. The example above contains PHP and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
hostname
+
The unique service identifier.
-
+
The hostname of the new service will be set to the `hostname` value.
-
- Limitations:
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+ Limitations:
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
type
+
Specifies the service type and version.
-
+
See what [PHP service types](/references/import-yaml/type-list#runtime-services) are currently supported.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto scaling parameters.
-
+
+
+
+
verticalAutoscaling
+
+ Optional. Defines [custom vertical auto scaling parameters](/php/how-to/create#set-auto-scaling-configuration).
+
All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
- minContainers
-
- Optional. Default = 1. Defines the minimum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
- cpuMode
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
- minCpu/maxCpu
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
- minRam/maxRam
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
- minDisk/maxDisk
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
minContainers
+
+ Optional. Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/php/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- maxContainers
-
- Defines the maximum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
maxContainers
+
+ Defines the maximum number of containers for [horizontal autoscaling](/php/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- envSecrets
-
- Optional. Defines one or more secret env variables as a key value map. See env variable restrictions.
-
+
+
+
+
envSecrets
+
+ Optional. Defines one or more secret env variables as a key value map. See env variable [restrictions](/php/how-to/env-variables#env-variable-restrictions).
+
+
+
+
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add PHP service to an existing project
+
#### Example:
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -17908,35 +25659,42 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one PHP service version 8.1 with default [auto scaling](/php/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the import.yaml file is 100 kB.
+
----------------------------------------
# Php > How To > Customize Runtime
-System packages for processing: When your app processes images, videos, or files (requiring packages like sudo apk add --no-cache imagemagick)',
- 'PHP extensions: When you need additional PHP extensions not included by default',
- 'Native dependencies: When your Composer packages require system libraries that aren\'t in the default environment',
- 'Different base OS: When you need Ubuntu instead of Alpine for specific compatibility requirements'
-]} />
+
## Overwrite php.ini files
+
You can override PHP configuration directives by setting environment variables in your `zerops.yaml` file.
+
Here's an example of how to adjust PHP's `post_max_size` directive:
```yaml
zerops:
@@ -17946,17 +25704,24 @@ zerops:
run:
# REQUIRED. Sets the base technology for the runtime environment:
base: php-nginx@8.3
+
# OPTIONAL. Defines the env variables for the runtime:
envVariables:
PHP_INI_post_max_size: 10M
```
+
:::info
After updating PHP-FPM configuration in your `zerops.yaml` file, you need to restart or reload the app for the changes to take effect.
:::
+
## PHP-FPM
+
### Default PHP-FPM configuration
+
PHP-FPM (FastCGI Process Manager) uses the **dynamic** process management mode by default. In this mode, the system automatically adjusts the number of PHP processes based on current load.
+
The default PHP-FPM configuration uses these values:
+
- `PHP_FPM_PM` = `dynamic`
- `PHP_FPM_PM_MAX_CHILDREN` = `20`
- `PHP_FPM_PM_START_SERVERS` = `2`
@@ -17964,7 +25729,9 @@ The default PHP-FPM configuration uses these values:
- `PHP_FPM_PM_MAX_SPARE_SERVERS` = `3`
- `PHP_FPM_PM_MAX_SPAWN_RATE` = `32`
- `PHP_FPM_PM_MAX_REQUESTS` = `500`
+
### Dynamic mode
+
To adjust the dynamic mode settings, add the desired environment variables to the run section:
```yaml
zerops:
@@ -17980,7 +25747,9 @@ zerops:
PHP_FPM_PM_MAX_SPARE_SERVERS: 10
PHP_FPM_PM_MAX_REQUESTS: 1000
```
+
### Ondemand mode
+
The **ondemand** mode is ideal for applications with lower traffic, where processes are created only when requests arrive. To enable ondemand mode:
```yaml
zerops:
@@ -17995,10 +25764,13 @@ zerops:
PHP_FPM_PM_PROCESS_IDLE_TIMEOUT: 60s
PHP_FPM_PM_MAX_REQUESTS: 500
```
+
**Available parameters for ondemand mode:**
+
- `PHP_FPM_PM_MAX_CHILDREN` – maximum number of child processes
- `PHP_FPM_PM_PROCESS_IDLE_TIMEOUT` – time after which idle processes are terminated (default: `60s`)
- `PHP_FPM_PM_MAX_REQUESTS` – number of requests each process handles before being recycled (default: `500`)
+
:::info
After updating PHP-FPM configuration in your `zerops.yaml` file, you need to restart or reload the app for the changes to take effect.
:::
@@ -18007,61 +25779,91 @@ After updating PHP-FPM configuration in your `zerops.yaml` file, you need to res
# Php > How To > Customize Web Server
+
## PHP + Nginx
+
### Default Nginx configuration
+
The default PHP+Nginx service has following Nginx configuration:
+
```
server {
listen 80;
listen [::]:80;
+
server_name _;
+
# Be sure that you set up the correct document root!
root {{.DocumentRoot}};
+
location ~ \.php {
try_files _ @backend;
}
+
location / {
# use this for pretty url
try_files $uri /$uri /index.html /index.php$is_args$args;
}
+
location @backend {
fastcgi_pass unix:{{.PhpSocket}};
fastcgi_split_path_info ^(.+\.php)(/.*)$;
include fastcgi_params;
+
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_param DOCUMENT_ROOT $realpath_root;
internal;
}
+
access_log syslog:server=unix:/dev/log,facility=local1,tag=nginx,severity=info default_short;
error_log syslog:server=unix:/dev/log,facility=local1,tag=nginx,severity=error;
}
```
+
The configuration contains 2 variables:
-- **`{{.DocumentRoot}}`** is replaced by the `run.documentRoot` attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.
+
+- **`{{.DocumentRoot}}`** is replaced by the [`run.documentRoot`](/php/how-to/build-pipeline#documentroot) attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.
+
- **`{{.PhpSocket}}`** is replaced by a path to the PHP socket based on the PHP version.
+
### Customize Nginx configuration
+
Follow these steps to customize the Nginx configuration in PHP+Nginx service:
+
1. Create a **.tmpl** file with the Apache configuration in your repository.
+
2. Optionally use following variables:
-- **`{{.DocumentRoot}}`** is replaced by the `run.documentRoot` attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.
+
+- **`{{.DocumentRoot}}`** is replaced by the [`run.documentRoot`](/php/how-to/build-pipeline#documentroot) attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.
+
Example:
+
```
root {{.DocumentRoot}};
```
+
- **`{{.PhpSocket}}`** is replaced by a path to the PHP socket based on the PHP version.
+
Example:
+
```
fastcgi_pass unix:{{.PhpSocket}};
```
+
- **`{{.Environment.ENV_NAME}}`** is replaced by the [env variable](/php/how-to/env-variables) value. The env variable must be either defined in [run.envVariables](/php/how-to/build-pipeline#envvariables-1) in `zerops.yaml` or set as a [secret](/php/how-to/env-variables#set-secret-env-variables-in-zerops-gui) or [generated](/php/how-to/env-variables#generated-env-variables) env variable in Zerops GUI.
+
:::caution
Use the **.tmpl** file extension to make Zerops interpret the file as a template. Zerops will replace the supported variables listed above.
:::
+
3. Check that your Nginx configuration is consistent with Zerops requirements:
+
- Do not use IP addresses in the `listen` directive
-- If you use other ports than `:80` in the `listen` directive, add them to the `run.ports` in your `zerops.yaml` as well.
+- If you use other ports than `:80` in the `listen` directive, add them to the [`run.ports`](/php/how-to/build-pipeline#ports) in your `zerops.yaml` as well.
- Do not use the port **:443**. All the incoming `https://` traffic is terminated on the Zerops internal balancer where the SSL certificate is installed and the request is forwarded to your PHP+Nginx service as a **http://** on the port **:80**.
-4. Add the `siteConfigPath` to the run section of your `zerops.yaml`
+
+4. Add the [`siteConfigPath`](/php/how-to/build-pipeline#siteconfigpath) to the run section of your `zerops.yaml`
+
```yaml
zerops:
# define hostname of your service
@@ -18070,63 +25872,84 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: php-nginx@latest
+
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- vendor
- public
+
# ==== how to run your application ====
run:
documentRoot: public
+
# OPTIONAL. Sets the custom Nginx or Apache configuration. The file must be deployed in the runtime container. Enter the path to the file relative to the /var/www folder
siteConfigPath: site_config.tmpl
```
-5. Ensure that the `build.deployFiles` contains the folder with the `siteConfigPath` or add the path to the Nginx config file to the `deployFiles` list. Zerops will deploy the file to the runtime container(s).
+
+5. Ensure that the [`build.deployFiles`](/php/how-to/build-pipeline#deployfiles) contains the folder with the `siteConfigPath` or add the path to the Nginx config file to the `deployFiles` list. Zerops will deploy the file to the runtime container(s).
+
6. [Trigger](/php/how-to/trigger-pipeline) the build & deploy pipeline.
+
## PHP + Apache
+
### Default Apache configuration
+
The default PHP+Apache service has following Apache configuration:
+
```
- ServerName localhost
- DocumentRoot {{.DocumentRoot}}
- DirectoryIndex index.htm index.html index.shtml index.php index.phtml
-
- Options -Indexes
- Options FollowSymLinks
- AllowOverride All
- Require all granted
-
- SetHandler "proxy:unix:{{.PhpSocket}}|fcgi://localhost/"
-
+
+
+
ErrorLog "| /usr/bin/logger -tapache -plocal1.err"
CustomLog "| /usr/bin/logger -tapache -plocal1.notice" combined
+
```
+
The configuration contains 2 variables:
-- **`{{.DocumentRoot}}`** is replaced by the `run.documentRoot` attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.
+
+- **`{{.DocumentRoot}}`** is replaced by the [`run.documentRoot`](/php/how-to/build-pipeline#documentroot) attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.
+
- **`{{.PhpSocket}}`** is replaced by a path to the PHP socket based on the PHP version.
+
### Customize Apache configuration
+
Follow these steps to customize the Apache configuration in PHP+Apache service:
+
1. Create a **.tmpl** file with the Nginx configuration in your repository.
+
2. Optionally use following variables:
-- **`{{.DocumentRoot}}`** is replaced by the `run.documentRoot` attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.
+
+- **`{{.DocumentRoot}}`** is replaced by the [`run.documentRoot`](/php/how-to/build-pipeline#documentroot) attribute from the `zerops.yaml`. If the attribute is not specified, the default value `/var/www` is used.
+
Example:
+
```
DocumentRoot {{.DocumentRoot}};
```
+
- **`{{.PhpSocket}}`** is replaced by a path to the PHP socket based on the PHP version.
+
Example:
+
```
- SetHandler "proxy:unix:{{.PhpSocket}}|fcgi://localhost/"
+
```
+
- **`{{.Environment.ENV_NAME}}`** is replaced by the [env variable](/php/how-to/env-variables) value. The env variable must be either defined in [run.envVariables](/php/how-to/build-pipeline#envvariables-1) in `zerops.yaml` or set as a [secret](/php/how-to/env-variables#set-secret-env-variables-in-zerops-gui) or [generated](/php/how-to/env-variables#generated-env-variables) env variable in Zerops GUI.
+
:::caution
Use the **.tmpl** file extension to make Zerops interpret the file as a template. Zerops will replace the supported variables listed above.
:::
+
3. Check that your Apache configuration is consistent with Zerops requirements:
-- Do not use IP addresses in the `` directive
-- If you use other ports than `:80` in the `` directive, add them to the `run.ports` in your `zerops.yaml` as well.
+
+- Do not use IP addresses in the `` directive
+- If you use other ports than `:80` in the `` directive, add them to the [`run.ports`](/php/how-to/build-pipeline#ports) in your `zerops.yaml` as well.
Do not use the port **:443**. All the incoming `https://` traffic is terminated on the Zerops internal balancer where the SSL certificate is installed and the request is forwarded to your PHP+Apache service as a **http://** on the port **:80**.
-4. Add the `siteConfigPath` to the run section of your `zerops.yaml`.
+
+4. Add the [`siteConfigPath`](/php/how-to/build-pipeline#siteconfigpath) to the run section of your `zerops.yaml`.
+
```yaml
zerops:
# define hostname of your service
@@ -18135,20 +25958,26 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: php-apache@latest
+
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- vendor
- public
+
# ==== how to run your application ====
run:
documentRoot: public
+
# OPTIONAL. Sets the custom Nginx or Apache configuration. The file must be deployed in the runtime container. Enter the path to the file relative to the /var/www folder
siteConfigPath: site_config.tmpl
```
-5. Ensure that the `build.deployFiles` contains the folder with the `siteConfigPath` or add the path to the Apache config file to the `deployFiles` list. Zerops will deploy the file to the runtime container(s).
+
+5. Ensure that the [`build.deployFiles`](/php/how-to/build-pipeline#deployfiles) contains the folder with the `siteConfigPath` or add the path to the Apache config file to the `deployFiles` list. Zerops will deploy the file to the runtime container(s).
+
6. [Trigger](/php/how-to/trigger-pipeline) the build & deploy pipeline.
+
----------------------------------------
# Php > How To > Deploy Process
@@ -18201,13 +26030,21 @@ zerops:
# Php > Overview
+
[PHP ↗](https://www.php.net/), a popular general-purpose scripting language that is especially suited to web development.
+
As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-php-hello-world), a **_recipe_**, containing the most simple PHP web application. The repo will be used as a source from which the app will be built.
- This is the most bare-bones example of PHP running in Zerops — as few libraries as possible,
+
+### 🚀 Feel free to deploy the recipe yourself
+
+This is the most bare-bones example of PHP running in Zerops — as few libraries as possible,
just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.
-
+
+ [Deploy "php" recipe on Zerops](https://app.zerops.io/recipe/?lf=php)
+
1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-php-hello-world/blob/main/import-project/description.yaml)):
+
```yaml
project:
name: my-first-project
@@ -18219,195 +26056,293 @@ services:
buildFromGit: https://github.com/zeropsio/recipe-php-hello-world@main
enableSubdomainAccess: true
```
+
3. Click on **Import project** and wait until all pipelines have finished.
+
**That's it, your application is now up and running! :star: Let's check it works:**
+
1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://helloworld-24-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see
+
```
Hello, World!
```
+
:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::
+
## How to start
+
+- [Care for details?](/php/how-to/create) — Dive in all Zerops has to offer for your PHP application.
+
## Feature Highlights
+
+- [Create PHP service](/php/how-to/create) — Start with creating a PHP service using GUI or zCLI.
+- [zerops.yaml](/php/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
+- [Scaling configuration](/php/how-to/scaling) — Set up scaling of your PHP application so that it runs smoothly while using only necessary resources.
+
{" "}
+
+- [Customize build environment](/php/how-to/build-process#customize-build-environment)
+- [Customize runtime environment](/php/how-to/customize-runtime)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+
+- [FAQ](/php/faq) — Most common questions in one place.
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Postgresql > Faq
- Question: How do I properly use PostgreSQL in HA mode?
-Answer:
- In High Availability (HA) mode, PostgreSQL runs on multiple containers with a primary node and replicas. To get the most out of this setup:
+
+ **Question: How do I properly use PostgreSQL in HA mode?**
+
+In High Availability (HA) mode, PostgreSQL runs on multiple containers with a primary node and replicas. To get the most out of this setup:
+
- Use port `5432` for all write operations (INSERT, UPDATE, DELETE) — this always routes to the primary node
- Use port `5433` for read operations (SELECT) — this distributes queries across all replicas, improving performance
+
The read replica port (`5433`) is only available in HA mode. If you're running PostgreSQL in single container (NON_HA) mode, only port `5432` is available.
+
See [Connection Parameters](/postgresql/how-to/connect#connection-parameters) for all available ports and environment variables.
-
- Question: Why is my connection to PostgreSQL from third-party software failing?
-Answer:
- *One possible cause:*
+
+ **Question: Why is my connection to PostgreSQL from third-party software failing?**
+
+*One possible cause:*
+
The connection string in Zerops always starts with `postgresql://`. While the official PostgreSQL documentation
states that both `postgresql://` and `postgres://` URIs are valid, some software requires the shorter `postgres://`
version.
-
+
To resolve this, create your own environment variable with the correct URI. For example, if your PostgreSQL service is named `db`, use the following format:
-
+
```
postgres://${db_user}:${db_password}@${db_hostname}:${db_port}
```
-
+
----------------------------------------
# Postgresql > How To > Backup
+
Zerops provides automated data backup for PostgreSQL services with full encryption and flexible management options.
+
For general backup information including configuration, scheduling, and management options, see the [Zerops Backups](/features/backup) documentation, which covers:
- Backup scheduling and retention policies
- Tagging system and storage quotas
- Manual backup creation and CLI tools
- Security and encryption details
+
This page focuses on PostgreSQL-specific backup details.
+
## PostgreSQL Backup Format
+
PostgreSQL backups are created using `pg_dump` and stored in `.zip` format:
+
- **Format**: `.zip` (containing per-schema `.dump` files)
- **Tooling**: `pg_dump`
- **Compression**: Custom format (`-Fc`), schema files named `schemaName.dump`
- **Storage**: Encrypted and stored in isolated object storage
+
## Restoring PostgreSQL Backups
+
To restore a PostgreSQL backup:
+
1. **Download** the backup file (`.zip`) from the Zerops UI
2. **Extract** the zip file to access the individual schema dump files
3. **Prepare** your target environment (clean existing data or use a new instance)
4. **Restore** using PostgreSQL native tools. Follow the [official PostgreSQL backup documentation](https://www.postgresql.org/docs/current/backup-dump.html) for detailed restore procedures, or use web-based management tools like phpMyAdmin or Adminer as described in [PostgreSQL Management](/postgresql/how-to/manage).
+
For assistance with the restoration process, contact Zerops support.
+
## High Availability
+
For PostgreSQL services running in High Availability mode:
- Backups are created on a randomly selected healthy node
- Other nodes remain operational during the backup process
- Manual backups typically run on the primary node
+
## Best Practices
+
- Always create a manual backup with a protected tag before database migrations or major schema changes
- Test your restore process periodically in a non-production environment
- Monitor your backup storage usage in the Project Overview
- Use descriptive tags like `pre-migration-v2` for important snapshots
- Consider the order of schema restoration if you have dependencies between schemas
+
For additional best practices and troubleshooting, refer to the [main backup documentation](/features/backup).
----------------------------------------
# Postgresql > How To > Connect
+
This guide covers how to connect to your PostgreSQL database in Zerops, both from services within the same project and from outside the Zerops environment.
+
## Connection Options Overview
+
Zerops provides several ways to connect to PostgreSQL:
+
1. **Internal connections** - Between services in the same Zerops project (via private network)
2. **Remote connections**:
- **VPN access** - From your local machine via Zerops VPN
- **Direct IP access** - Enables external applications to connect using TLS encryption by opening public ports on IPv6 (available by default) or IPv4 (requires add-on activation if not already enabled)
+
## Connection Details
+
You'll find PostgreSQL connection details in the service detail page under the **Peek access details** button (shows hostname, port, user, password, and connection string).
+
The full list of connection-related environment variables is available in the service detail under **Environment variables**.
+
### Connection Parameters
-
- Parameter
- Internal
- External (TLS)
- Env Variable
-
- Hostname
- Service hostname
- Public IP address
- `hostname`
-
- Port (primary)
- 5432
- 6432 (via pgBouncer)
- `port` / `portTls`
-
- Port (replicas, HA only)
- 5433
- N/A
- `portReplicas`
-
- User
- Identical to hostname
- Same as internal
- `user`
-
- Password
- Generated at creation
- Same as internal
- `password`
-
- Connection string (primary)
- `postgresql://${user}:${password}@${hostname}:5432/${dbName}`
- Same format with TLS port
- `connectionString` / `connectionTlsString`
-
- Connection string (replicas, HA only)
- `postgresql://${user}:${password}@${hostname}:5433/${dbName}`
- N/A
- `connectionStringReplicas`
-
- Database name
- db
- Same as internal
- `dbName`
-
+
+
+
:::tip
If you're running PostgreSQL in High Availability (HA) mode, configure your application to route read queries to port **5433**. This distributes the load across all replicas, reducing pressure on the primary node and improving overall throughput.
:::
+
:::warning
Zerops creates a system user named `zps` with full privileges for maintenance purposes. Do not delete, change the password, or remove privileges from this user, as it will disrupt Zerops' ability to maintain the database cluster.
:::
+
:::info
For more information about default PostgreSQL setup, users, and databases, see [Manage PostgreSQL Users and Databases](/postgresql/how-to/manage).
:::
+
## Connect from Services in the Same Project
+
All services within a Zerops project share a dedicated private network. There are two ways to implement connections between services in the same project:
+
### Method 1: Direct Connection Parameters
+
You can directly use the connection parameters from Peek Access Details:
+
```
host = database1
port = 5432
user = database1
password = ********** (find under Peek Access Details)
```
+
For read operations in HA mode, use port `5433` instead of `5432` with the same credentials.
+
### Method 2: Environment Variables (Recommended)
+
For better maintainability, Zerops creates environment variables for each PostgreSQL service that you can use in your application configuration. List of service environment variables is available in Zerops GUI. Go to a PostgreSQL service detail and choose **Environment variables**.
+
To use variables from one service in another, prefix the variable name with the service hostname and underscore - to access the `connectionString` variable of `postgresql1`, use `postgresql1_connectionString`.
+
For read-only connections (HA mode only), use the `connectionStringReplicas` variable instead.
+
For more details on how to use environment variables, and instructions for adding your own custom variables, see the [Environment Variables](/features/env-variables) documentation.
+
:::caution Important notes
- When changing passwords, update both the database user password and the environment variable separately - they don't automatically synchronize.
- While both `postgresql://` and `postgres://` URI formats are valid, Zerops uses the `postgresql://` format. If your software requires `postgres://`, create a custom environment variable with this format.
- Do not use SSL/TLS protocols for internal connections. Security is assured by the project's private network.
:::
+
## Connect Remotely
+
Zerops offers two methods for connecting to your PostgreSQL database from outside the Zerops environment:
+
### Method 1: Connect via Zerops VPN
+
You can securely connect to PostgreSQL from your local workstation via Zerops VPN:
+
1. [Install & set up zCLI](/references/cli)
2. [Start the Zerops VPN](/references/networking/vpn#start-vpn)
3. Use the connection details from Access Details in the PostgreSQL service detail in Zerops GUI
4. When finished, [stop the Zerops VPN](/references/networking/vpn#stop-vpn)
+
:::warning Important notes
* Do not use SSL/TLS protocols when connecting over VPN. Security is provided by the VPN tunnel.
* If your connection over VPN doesn't work, try adding `.zerops` suffix to the service hostname (e.g., `database1.zerops`). For additional help, check the [VPN troubleshooting page](/references/networking/vpn#troubleshooting).
:::
+
### Method 2: Connect via Direct IP Access
+
Direct IP Access uses [pgBouncer](https://www.pgbouncer.org/) for connection pooling and TLS termination.
+
Internally, port `5432` is available without SSL (and port `5433` for reads in HA mode). Externally, connections are secured with TLS through pgBouncer (port `6432`) before being routed to your PostgreSQL service. The read replica port is not available for external connections.
+
#### Enable external access
+
1. Navigate to your PostgreSQL service in the Zerops GUI and choose the **Public Access through IP Addresses** section
2. Choose either IPv6 (available by default) or IPv4 (requires the [unique IPv4](/references/networking/public-access#ipv4-configuration) add-on)
3. Open one or more ports and point them to your PostgreSQL service (the system will direct them through pgBouncer)
@@ -18418,6 +26353,7 @@ Internally, port `5432` is available without SSL (and port `5433` for reads in H
- Port configurations can be set independently for IPv4 and IPv6
4. Optionally enable firewall protection for additional security
5. Click the **Publish X IP access change(s)** button to apply your settings
+
For database management tools and how to manage users and databases, see [Manage PostgreSQL Users and Databases](/postgresql/how-to/manage).
----------------------------------------
@@ -18430,43 +26366,70 @@ For database management tools and how to manage users and databases, see [Manage
# Postgresql > How To > Create
+
## Create PostgreSQL using Zerops GUI
+
First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new PostgreSQL service:
+
+[Video: /vids/services/postgres.webm](/vids/services/postgres.webm)
+
### Choose PostgreSQL version
+
Following PostgreSQL versions are currently supported:
+
### Set a hostname
+
Enter a unique service identifier like `postgresql`, `sql`, `db` etc.
+
#### Limitations:
+
- Duplicate services with the same name within the same project are not allowed
- Maximum 25 characters
- Must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created and cannot be changed later.
:::
+
### Configure auto scaling
+
Zerops automatically scales PostgreSQL services based on actual database usage. Configure the scaling parameters to match your database needs and control costs.
+
**CPU Mode**: Choose between shared (cost-effective) or dedicated (consistent performance).
+
**Resource Limits**: Set minimum and maximum resources for CPU, RAM, and disk to control costs and ensure performance.
+
**Deployment Mode**: Choose the reliability configuration for your PostgreSQL service:
+
- **Highly Available**: Multiple containers with redundancy across different physical machines. Recommended for production environments.
- **Single Container**: One container suitable for development and non-critical environments.
+
:::warning
Deployment mode cannot be changed after service creation.
:::
+
:::tip Learn More
For detailed scaling configuration, deployment mode details, and troubleshooting, see:
- [How Zerops scales PostgreSQL](/postgresql/how-to/scale) - Database-specific scaling guide
- [Automatic Scaling and High Availability](/features/scaling) - Complete technical details
:::
+
## Create PostgreSQL using zCLI
+
zCLI is the Zerops command-line tool. To create a new PostgreSQL service via the command line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](#create-a-project-description-file)
3. Create a project and a PostgreSQL service
+
### Create a project description file
+
Zerops uses a YAML format file to describe the project infrastructure.
+
#### Basic example
+
Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content:
+
```yaml
# Basic project data
project:
@@ -18481,9 +26444,13 @@ services:
# mode of operation "HA"/"NON_HA"
mode: NON_HA
```
+
The YAML file describes your future project infrastructure. The project will contain one PostgreSQL service in the single container mode with default [auto scaling](/postgresql/how-to/scale) configuration. The hostname will be set to `postgresql1`.
+
#### Full example
+
Create a directory `my-project`. Create a `description.yaml` file inside the directory with the following content:
+
```yaml
# Basic project data
project:
@@ -18522,124 +26489,194 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The YAML file describes your future project infrastructure. The project will contain two PostgreSQL services.
+
The hostname of the first service will be set to `postgresql1`. The [high availability](/features/scaling#highly-available-ha-mode) mode will be chosen and the custom [auto scaling configuration](/postgresql/how-to/scale) will be set.
+
The hostname of the second service will be set to `postgresql2`. The [single container](/features/scaling#single-container-mode) mode will be chosen and the default [auto scaling configuration](/postgresql/how-to/scale) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
-
- Parameter
- Description
- Limitations
-
- name
- The name of the new project. Duplicates are allowed.
-
- description
- Optional. Description of the new project.
- Maximum 255 characters.
-
- tags
- Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
-
+
+
+
+
+
Parameter
+
Description
+
Limitations
+
+
+
+
+
name
+
The name of the new project. Duplicates are allowed.
+
+
+
+
description
+
Optional. Description of the new project.
+
Maximum 255 characters.
+
+
+
tags
+
Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
+
+
+
+
+
At least one service in the `services:` section is required. You can create a project with multiple services. The example above contains only PostgreSQL services but you can create a `description.yaml` with [different types] of services.
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
+ hostname
+
+
The unique service identifier.
-
- The hostname of the new database will be set to the `hostname` value.
-
- Limitations:
-
+
+ The hostname of the new database will be set to the `hostname` value.
+
+ Limitations:
+
- duplicate services with the same name in the same project are
forbidden
-
+
- maximum 25 characters
-
+
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+
+
+
+ type
+
+
Specifies the service type and version.
-
+
See what [PostgreSQL service types](/references/import-yaml/type-list#database-services) are currently supported.
-
- mode
-
+
+
+
+
+ mode
+
+
Defines the operation mode of the PostgreSQL service.
-
- HA
-
+
+ HA
+
Creates a PostgreSQL cluster with 3 database containers and 2 free
database proxies. This mode is suited for production.
-
+
Zerops always keeps the 3 database containers on different physical
machines. All your data is stored redundantly in 3 identical copies. In
case of a failure of a container or the underlying physical machine,
Zerops automatically disconnects the failed container from the cluster,
creates a new container and syncs all data from the remaining 2 copies.
Finally, the broken container is automatically deleted.
-
- In HA mode, a dedicated read replica port (5433) is available, allowing you to route read queries to replicas for better performance. See Connection Parameters for details.
-
- NON_HA
-
+
+ In HA mode, a dedicated read replica port (5433) is available, allowing you to route read queries to replicas for better performance. See [Connection Parameters](/postgresql/how-to/connect#connection-parameters) for details.
+
+ NON_HA
+
Zerops will create a PostgreSQL database installed in a single
container. Useful for non-essential data or dev environments.
-
+
Your data is stored only in a single container. If the container or the
the underlying physical machine fails, your data since the last backup are
lost. Zerops doesn't provide any automatic repairs of a single node
PostgreSQL services.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto-scaling parameters.
+
+
+
+
+ verticalAutoscaling
+
+
+ Optional. Defines [custom vertical auto-scaling parameters](/postgresql/how-to/scale#configure-scaling).
+
All verticalAutoscaling attributes are optional. Not specified
attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
+
+
+
+
+ - cpuMode
+
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
+ - minCpu/maxCpu
+
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
+ - minRam/maxRam
+
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
+ - minDisk/maxDisk
+
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
+
:::caution
The PostgreSQL service **hostname** and **mode** are fixed after the service is created. They can't be changed later.
:::
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project will be created.
--working-dir string Sets a custom working directory. The default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
The maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add PostgreSQL service to an existing project
+
#### Example
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```bash
# array of project services
services:
@@ -18651,97 +26688,145 @@ services:
# mode of operation "HA"/"NON_HA"
mode: NON_HA
```
+
The YAML file describes the list of one or more services that you want to add to your existing project. In the example above, one PostgreSQL service in the [single container](/features/scaling#single-container-mode) with default [auto scaling](/postgresql/how-to/scale) configuration will be added to your project. The hostname of the new service will be set to `postgresql1`.
+
The content of the `services:` section of `import.yaml` is identical to the [project description file](#create-a-project-description-file). The `import.yaml` never contains the `project:` section because the project already exists.
+
When your `import.yaml` is ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command will be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
The maximum size of the `import.yaml` file is 100 kB.
----------------------------------------
# Postgresql > How To > Export Import Data
+
## Use Adminer or phpMyAdmin to export or import data
* [Adminer ↗](https://www.adminer.org) - an open source full-featured database management tool written in PHP
* [phpMyAdmin ↗](https://www.phpmyadmin.net) - a free software tool written in PHP, intended to handle the administration of PostgreSQL over the Web
+
1. [Install the tools to Zerops](/postgresql/how-to/manage#installing-management-tools)
2. Use their standard export or import functions
+
## Use a database management tool on your workstation to export or import data
+
Do you already use a database management tool that supports PostgreSQL on your workstation? Connect it securely to PostgreSQL from your local workspace via Zerops VPN.
+
Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to PostgreSQL remotely](/postgresql/how-to/connect#connect-remotely).
:::caution
Do not use SSL/TLS protocols when connecting to PostgreSQL over VPN. Zerops PostgreSQL is not configured to support these protocols. The security is assured by the VPN.
:::
+
Once the connection to PostgreSQL is established, use the standard export or import functions of your favourite management tool.
+
## Use psql CLI to export or import data
+
If you are using the [psql ↗](https://www.postgresql.org/docs/current/app-psql.html) command-line client to manage your PostgreSQL on your local workspace, you can connect it securely to PostgreSQL via Zerops VPN.
+
Zerops VPN client is included into zCLI, the Zerops command-line tool. To start the VPN connection, read [how to connect to PostgreSQL remotely](/postgresql/how-to/connect#connect-remotely).
+
Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no [environment variables](/postgresql/how-to/connect#method-2-environment-variables-recommended) are available when connected through VPN. To connect to PostgreSQL in Zerops you have to copy the [access details](/postgresql/how-to/connect#connection-details) manually from Zerops GUI.
+
Use [psql ↗](https://www.postgresql.org/docs/current/app-psql.html) command to connect to PostgreSQL in Zerops:
+
```sh
psql -h [hostname] -U [user] -p [password] -d [database_name]
```
+
:::caution
Do not use SSL/TLS protocols when connecting to PostgreSQL over VPN. Zerops PostgreSQL is not configured to support these protocols. The security is assured by the VPN.
:::
+
To export your database data and structure, use the [pg_dump ↗](https://www.postgresql.org/docs/current/backup-dump.html) command.
+
```sh
pg_dump [database_name] > dumpfilename.sql
```
+
To import your database data and structure, use the `mysql` command.
+
```sh
mysql [database_name] < dumpfilename.sql
```
+
----------------------------------------
# Postgresql > How To > Manage
+
This guide covers how to manage your PostgreSQL databases in Zerops, including default setup, database management tools, plugins, and best practices.
+
## Default Database and User
+
Zerops creates a default database and user automatically when a new PostgreSQL service is [created](/postgresql/how-to/create).
+
### Database
+
- **Name**: Identical to the service hostname
- **Encoding**: `utf8mb4`
+
### DB User
+
- **Username**: Identical to the service hostname
- **Password**: Generated randomly
+
:::info
For connection methods and environment variables, see the [Connect to PostgreSQL in Zerops](/postgresql/how-to/connect) page.
:::
+
:::caution Important notes
- When changing passwords, update both the database user password and the environment variable separately - they don't automatically synchronize.
- While both `postgresql://` and `postgres://` URI formats are valid, Zerops uses the `postgresql://` format. If your software requires `postgres://`, create a custom environment variable with this format.
- Do not use SSL/TLS protocols for internal connections. Security is assured by the project's private network.
:::
+
## Database Management Tools
+
You can use any PostgreSQL management tool of your choice to administer your databases in Zerops. For convenience, Zerops provides ready-to-use recipes for two popular web-based database management tools:
+
* [Adminer](https://www.adminer.org) - a lightweight database management tool by Jakub Vrána
* [phpMyAdmin](https://www.phpmyadmin.net) - a popular free database administration tool that works with both MySQL and PostgreSQL databases
+
### Installing Management Tools
+
You can install these tools with a simple one-click import in Zerops:
+
1. In Zerops GUI, open your project and select **Import services** from the left menu
2. Copy and paste one of the following YAML configurations:
+
### Accessing Management Tools
+
After installation, you can access these tools via VPN:
+
1. [Start the Zerops VPN](/references/networking/vpn)
2. Type `http://adminer` or `http://phpmyadmin` in your browser
+
:::tip
Try `http://adminer.zerops` or `http://phpmyadmin.zerops` if you encounter any connection issues.
:::
+
:::caution
Do not use https when connecting to management tools via VPN.
:::
+
## Database Tools on Your Workstation
+
You can use various database management tools from your local workstation to connect to your PostgreSQL database in Zerops:
+
1. **Establish a secure tunnel** using the [Zerops VPN](/references/networking/vpn) to create an encrypted connection to your Zerops project
2. **Obtain the [connection details](/postgresql/how-to/connect#connection-details)** from Zerops GUI
- Environment variables are not available through VPN connections
@@ -18752,31 +26837,45 @@ You can use various database management tools from your local workstation to con
```sh
psql -h [hostname] -U [user] -d [database_name]
```
+
:::tip
Try `{hostname}.zerops` instead of just `{hostname}` if you encounter any connection issues.
:::
+
## How to install and manage PostgreSQL plugins
+
### Viewing available plugins
You can list all available PostgreSQL plugins by running the following query *(superuser privileges not required)*:
+
```sql
SELECT * FROM pg_available_extensions ORDER BY name;
```
+
### Installing plugins (requires superuser)
+
1. **Connect with superuser credentials**:
- Use the `superUser` (user `postgres`) and `superUserPassword` environment variables from your PostgreSQL service
+
2. **Switch to your service database**:
When logging in as the superuser, you're initially in the `postgres` database, not your service database.
+
3. **Install required extensions**:
```sql
CREATE EXTENSION pg_stat_statements;
CREATE EXTENSION vector;
CREATE EXTENSION postgis;
```
+
:::warning
Currently, it is not possible to add new plugins that are not already listed in `pg_available_extensions`.
:::
+
When working with text search functionality, you'll need to reference the correct `stop`, `dict`, and `affix` files when creating dictionaries in your database. These files are essential for proper text search configuration.
+
Zerops PostgreSQL includes the following dictionary files:
+
+#### Available dictionary files
+
**Stop word files** - used to remove common words that don't add significant meaning:
```
czech.stop
@@ -18813,101 +26912,165 @@ sk_SK.dict
```
unaccent.rules
```
+
For more information on text search dictionaries, refer to the [PostgreSQL documentation](https://www.postgresql.org/docs/16/textsearch-dictionaries.html).
----------------------------------------
# Postgresql > How To > Scale
+
Zerops automatically scales your PostgreSQL service based on actual database usage. When your database needs more power, resources increase. When demand drops, resources scale down to reduce costs.
+
:::tip Read More
For complete scaling details across all services, see [Automatic Scaling and High Availability](/features/scaling).
:::
+
## How PostgreSQL scaling works
+
PostgreSQL services use **vertical scaling** to adjust CPU, RAM, and disk resources within containers based on usage patterns. Unlike runtime services, PostgreSQL does not use horizontal scaling (adding/removing containers). Instead, PostgreSQL services use deployment modes for high availability.
+
## Configure scaling
+
You can configure scaling settings:
+
- **During service creation** - Set initial scaling parameters when [creating](/postgresql/how-to/create) your PostgreSQL service
- **During import** - Define scaling configuration in your YAML import file using `verticalAutoscaling` parameters
- **After service creation** - Navigate to your PostgreSQL service and select **Automatic scaling configuration** to modify settings
+
### Basic settings
-
+
**CPU Mode**: Choose between shared (cost-effective, variable performance) or dedicated (consistent performance, higher cost). You can change CPU mode once per hour. See [pricing](https://zerops.io/#pricing) for costs.
+
**Resource limits**: Configure minimum and maximum resources for your PostgreSQL service:
+
- **Lower the maximum** to control costs and prevent over-scaling
- **Raise the minimum** when you need guaranteed baseline performance
- **Set minimum = maximum** to disable automatic scaling for that specific resource
+
**Deployment mode**: Choose the reliability configuration for your PostgreSQL service:
+
- **Single Container**: One container with vertical scaling only. Suitable for development environments.
- **Highly Available**: Multiple containers with built-in redundancy. Recommended for production environments.
+
:::warning
Deployment mode cannot be changed after service creation.
:::
+
:::tip HA Mode
In HA mode, a dedicated read replica port (`5433`) is available for routing read queries to replicas. This improves performance by distributing load across all database containers. See [Connection Parameters](/postgresql/how-to/connect#connection-parameters) for details.
:::
+
When a container fails in HA mode, Zerops automatically replaces it with a new container on a different physical machine and synchronizes data from healthy copies.
+
### Advanced settings
+
**Start CPU cores**: Determines how many CPU cores are allocated during database startup. Increase this value if your PostgreSQL service starts slowly or requires more processing power during initialization.
+
**RAM thresholds**: Help prevent out-of-memory crashes by maintaining buffer space:
+
- **Absolute (GB)**: Maintains this amount of free RAM at all times
- **Percentage**: Keeps this percentage of total RAM free
+
Consider increasing these values if your database experiences memory-related issues.
-
+
:::info Read More
For detailed technical parameters and scaling behavior, see [Automatic Scaling and High Availability](/features/scaling#resource-scaling-behavior).
:::
+
## Monitor usage
+
Navigate to your PostgreSQL service and select **Service containers & Overview** to view:
- CPU, RAM, and disk usage over time
- Historical scaling events
- Container health status
+
## Technical details
+
Zerops monitors database usage and automatically adjusts resources based on predefined thresholds and timing parameters. The scaling behavior follows the same principles as other services in the platform.
+
For complete technical specifications including:
- Resource monitoring intervals and thresholds
- Scale-up and scale-down timing parameters
- Scaling increments and steps
- Detailed scaling behavior patterns
+
See [Resource Scaling Behavior](/features/scaling#resource-scaling-behavior) in the general scaling documentation.
+
## Common issues
+
**Out of memory errors**
- Increase minimum free RAM settings in your scaling configuration
- Consider raising the minimum RAM allocation
- Check for memory-intensive queries or operations
+
**Higher than expected costs**
- Consider lowering your maximum resource limits
- Review scaling patterns in the monitoring dashboard
+
**Slow database startup**
- Increase the "Start CPU cores" setting
- Consider switching to dedicated CPU mode for consistent performance
+
**Not utilizing HA mode effectively**
- Use port `5432` for write operations (INSERT, UPDATE, DELETE)
- Use port `5433` for read operations (SELECT) to distribute load across replicas
- See [Connection Parameters](/postgresql/how-to/connect#connection-parameters) for details
+
*Need help? Join our [Discord community](https://discord.gg/zerops) for assistance!*
+
----------------------------------------
# Postgresql > Overview
+
[PostgreSQL ↗](https://www.postgresql.org/) is a powerful, open source object-relational database system with over 35 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance.
+
## Feature Highlights
+
+- [Create PostgreSQL service](/postgresql/how-to/create) — Start with creating a PostgreSQL service using GUI or zCLI.
+- [Import config file](/postgresql/how-to/create#full-example) — Use an example config file to import your own app.
+
### Connect to PostgreSQL service
+
+- [Manage users and databases](/postgresql/how-to/manage)
+- [Connect from the same project](/postgresql/how-to/connect#connect-from-services-in-the-same-project)
+- [Connect remotely](/postgresql/how-to/connect#connect-remotely)
+
### Others
+
+- [Scale postgresql service](/postgresql/how-to/scale)
+- [Export and import data](/postgresql/how-to/export-import-data)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+
+- [FAQ](/postgresql/faq) — Most common questions in one place.
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Python > How To > Build Pipeline
+
Zerops provides a customizable build and runtime environment for your Python application.
+
## Add zerops.yaml to your repository
+
Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application:
+
```yaml
zerops:
# define hostname of your service
@@ -18916,47 +27079,61 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: python@latest
+
# OPTIONAL. Set the operating system for the build environment.
# os: ubuntu
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
# prepareCommands:
# - sudo apt-get something
# - curl something else
+
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- app.py
+
# OPTIONAL. Copy files from build container to runtime container.
addToRunPrepare:
- requirements.txt
+
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
# cache: file.txt
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: python@latest
+
# OPTIONAL. Sets the internal port(s) your app listens on:
ports:
# port number
- port: 8000
+
# OPTIONAL. Customize the runtime Python environment by installing additional
# dependencies to the base Python runtime environment.
# prepareCommands:
# - python3 -m pip install --ignore-installed -r requirements.txt
+
# OPTIONAL. Run one or more commands each time a new runtime container
# is started or restarted. These commands are triggered before
# your Python application is started.
# initCommands:
# - rm -rf ./cache
+
# REQUIRED. Your Python application start command
start: python3 app.py
```
+
The top-level element is always `zerops`.
+
### Setup
+
The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops.
Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`:
+
```yaml
zerops:
# definition for app service
@@ -18967,6 +27144,7 @@ zerops:
deploy: ...
# required
run: ...
+
# definition for api service
- setup: api
# optional
@@ -18976,11 +27154,21 @@ zerops:
# required
run: ...
```
+
Each service configuration contains at least the `run` section. Optional `build` and `deploy` sections can be added to further customize your process.
+
## Build pipeline configuration
+
### base
+
_REQUIRED._ Sets the base technology for the build environment.
+
Following options are available for Python builds:
+
+- `python@3.14 (Ubuntu only)`, `python@latest`
+- `python@3.12`
+- `python@3.11`
+
```yaml
zerops:
# hostname of your service
@@ -18991,12 +27179,18 @@ zerops:
base: python@latest
...
```
+
+
The base build environment contains {data.alpine.default}, the selected
- major version of Python, Zerops command line tool, `pip` and `git`.
+ major version of Python, [Zerops command line tool](/references/cli), `pip` and `git`.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the build environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -19010,34 +27204,52 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services).
+
To customize your build environment use the [prepareCommands](#preparecommands) attribute.
+
:::note
Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation.
:::
+
### os
+
_OPTIONAL._ Sets the operating system for the build environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customized.
:::
+
:::note
Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior.
:::
+
### prepareCommands
+
_OPTIONAL._ Customizes the build environment by installing additional dependencies or tools to the base build environment.
+
The base build environment contains:
-- {data.alpine.default}
+
+- {data.alpine.default}
- selected version of Python defined in the [base](#base) attribute
- [Zerops command line tool](/references/cli)
- `pip` and `git`
+
To install additional packages or tools add one or more prepare commands:
+
```yaml
zerops:
# hostname of your service
@@ -19046,94 +27258,136 @@ zerops:
build:
# REQUIRED. Set the base technology for the build environment:
base: python@latest
+
# OPTIONAL. Customize the build environment by installing additional packages
# or tools to the base build environment.
prepareCommands:
- sudo apt install python3-pip # already installed for Python services
...
```
+
When the first build is triggered, Zerops will
+
1. create a build container
2. download your application code from your repository
3. run the prepare commands in the defined order
+
The application code is available in `/build/source` before the prepare commands are triggered, so you can use any file from your repository in your prepare commands (e.g. a configuration file). The commands themselves run in the `/home/zerops` directory.
+
:::note
These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](/python/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase.
+
#### Run prepare commands as a single shell instance
+
Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it.
+
```yaml
prepareCommands:
- |
sudo apt update
sudo apt install python3-pip # already installed for Python services
```
+
#### Run prepare commands as a separate shell instances
+
When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command.
+
```yaml
prepareCommands:
- sudo apt update
- sudo apt install python3-pip # already installed for Python services
```
+
### deployFiles
-_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use `.deployignore` file.
+
+_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use [`.deployignore`](#deployignore) file.
+
```yaml
# REQUIRED. Select which files / folders to deploy after
# the build has successfully finished
deployFiles:
- app.py
```
+
Determines files or folders produced by your build, which should be deployed to your runtime service containers.
+
The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space.
+
The files/folders will be placed into `/var/www` folder in runtime, e.g. `./src/assets/fonts` would result in `/var/www/src/assets/fonts`.
+
#### Examples
+
Deploys a folder, and a file from the project root directory:
+
```yaml
deployFiles:
- app.py
```
+
Deploys the whole content of the build container:
+
```yaml
deployFiles: .
```
+
Deploys a folder, and a file in a defined path:
+
```yaml
deployFiles:
- ./path/to/file.txt
- ./path/to/dir/
```
+
#### How to use a wildcard in the path
+
Zerops supports the `~` character as a wildcard for one or more folders in the path.
+
Deploys all `file.txt` files that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/file.txt
```
+
Deploys all folders that are located in any path that begins with `/path/to/`
+
```yaml
deployFiles: ./path/to/~/
```
+
Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/`
+
```yaml
deployFiles: ./path/~/to/
```
+
:::note Example
By default, `./src/assets/fonts` deploys to `/var/www/src/assets/fonts`, keeping the full path. Adding `~`, like `./src/assets/~fonts`, shortens it to `/var/www/fonts`
:::
+
#### .deployignore
-Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as `.gitignore`.
+
+Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as [`.gitignore`](https://git-scm.com/docs/gitignore#_pattern_format).
+
To ignore a specific file or directory path, start the pattern with a forward slash (`/`). Without the leading slash, the pattern will match files with that name in any directory.
+
:::tip
For consistency, it's recommended to configure both your `.gitignore` and `.deployignore` files with the same patterns.
:::
+
Examples:
+
```yaml title="zerops.yaml"
zerops:
- setup: app
build:
deployFiles: ./
```
+
```text title=".deployignore"
/src/file.txt
```
@@ -19145,22 +27399,33 @@ This example above ignores `file.txt` in ANY directory named `src`, such as:
- `/src/file.txt`
- `/folder2/folder3/src/file.txt`
- `/src/src/file.txt`
+
:::note
-`.deployignore` file also works with `zcli service deploy` command.
+`.deployignore` file also works with [`zcli service deploy`](/references/zcli/commands#deploy) command.
:::
+
### cache
+
_OPTIONAL._ Defines which files or folders will be cached for the next build.
+
```yaml
# OPTIONAL. Which files / folders you want to cache for the next build.
# Next builds will be faster when the cache is used.
cache: file.txt
```
+
The cache attribute helps optimize build times by preserving specified files between builds.
+
The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path).
+
Learn more about the [build cache system](/features/build-cache) in Zerops.
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the build environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -19169,6 +27434,7 @@ zerops:
build:
base: python@latest
…
+
# OPTIONAL. Defines the env variables for the build environment:
envVariables:
PYTHON_ENV: production
@@ -19177,12 +27443,22 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/python/how-to/env-variables) in Zerops.
+
## Runtime configuration
+
### base
+
_OPTIONAL._ Sets the base technology for the runtime environment.
If you don't specify the `run.base` attribute, Zerops keeps the current Python version for your runtime.
+
Following options are available for Python builds:
+
+- `python@3.14 (Ubuntu only)`, `python@latest`
+- `python@3.12`
+- `python@3.11`
+
```yaml
zerops:
# hostname of your service
@@ -19192,18 +27468,25 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: python@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
base: python@latest
...
```
+
+
The base runtime environment contains {data.alpine.default}, the
- selected major version of Python, Zerops command line tool, `pip` and `git`.
+ selected major version of Python, [Zerops command line tool](/references/cli), `pip` and `git`.
+
+
:::info
You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository.
:::
+
If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example:
+
```yaml
zerops:
# hostname of your service
@@ -19213,6 +27496,7 @@ zerops:
# REQUIRED. Sets the base technology for the build environment:
base: python@latest
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Sets the base technology for the runtime environment:
@@ -19222,43 +27506,74 @@ zerops:
- zsc add go@latest
...
```
+
See the full list of supported [run base environments](/zerops-yaml/base-list).
+
To customize your build environment use the `prepareCommands` attribute.
+
### os
+
_OPTIONAL._ Sets the operating system for the runtime environment.
+
Following options are available:
+
- `alpine`
- `ubuntu`
+
Default value is `alpine`.
+
We are currently using following os version:
-- {data.alpine.default}
-- {data.ubuntu.default}
+
+- {data.alpine.default}
+- {data.ubuntu.default}
+
:::caution
The os version is fixed and cannot be customised.
:::
+
### ports
+
_OPTIONAL._ Specifies one or more internal ports on which your application will listen.
+
Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port.
+
For example, to connect to a Python service with hostname = "app" and port = 8000 from another service of the same project, simply use `app:8000`. Read more about [how to access a Python service](/references/networking/internal-access#basic-service-communication).
+
Each port has following attributes:
-
- Parameter
- Description
-
- port
- Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
-
- protocol
- Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
-
- httpSupport
- Optional. httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of public access. httpSupport = true is available only in combination with the TCP protocol.
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port number. You can set any port number between 10 and 65435. Ports outside this interval are reserved for internal Zerops systems.
+
+
+
protocol
+
Optional. Defines the protocol. Allowed values are TCP or UDP. Default value is TCP.
+
+
+
httpSupport
+
Optional.httpSupport = true is the default setting for TCP protocol. Set httpSupport = false if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). httpSupport = true is available only in combination with the TCP protocol.
+
+
+
+
### prepareCommands
+
_OPTIONAL._ Customises the Python runtime environment by installing additional dependencies or tools to the runtime base environment.
+
+
The base Python environment contains {data.alpine.default}, the selected
- major version of Python, Zerops command line tool, `pip` and `git`. To install additional packages or tools add one or more
+ major version of Python, [Zerops command line tool](/references/cli), `pip` and `git`. To install additional packages or tools add one or more
prepare commands:
+
+
```yaml
zerops:
# hostname of your service
@@ -19266,6 +27581,7 @@ zerops:
# ==== how to build your application ====
build:
...
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -19274,27 +27590,45 @@ zerops:
- python3 -m pip install --ignore-installed -r requirements.txt
...
```
+
When the first deploy with a defined prepare attribute is triggered, Zerops will
+
1. create a prepare runtime container
2. optionally: [copy selected folders or files from your build container](#copy-folders-or-files-from-your-build-container)
3. run the `prepareCommands` commands in the defined order
+
:::note
`run.prepareCommands` run in the `/home/zerops` directory.
:::
+
#### Command exit code
+
If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](/python/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase.
+
#### Cache of your custom runtime environment
+
Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met:
+
1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy
2. The custom runtime cache wasn't invalidated in the Zerops GUI.
+
To invalidate the Zerops runtime cache go to your service detail in Zerops GUI, choose **Service dashboard & runtime containers** from the left menu and click on the **Open pipeline detail** button. Then click on the **Clear runtime prepare cache** button.
+
When the prepare cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly.
+
#### Single or separated shell instances
+
You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build:prepareCommands](#preparecommands).
+
### Copy folders or files from your build container
+
+
The prepare runtime container contains {data.alpine.default} the
- selected major version of Python, Zerops command line tool, `pip` and `git`.
+ selected major version of Python, [Zerops command line tool](/references/cli), `pip` and `git`.
+
+
The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration).
+
```yaml
zerops:
# hostname of your service
@@ -19304,6 +27638,7 @@ zerops:
...
addToRunPrepare:
- requirements.txt
+
# ==== how to run your application ====
run:
# OPTIONAL. Customise the runtime environment by installing additional packages
@@ -19312,15 +27647,20 @@ zerops:
- python3 -m pip install --ignore-installed -r requirements.txt
...
```
+
In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `/home/zerops` folder in the new prepare runtime container before the prepare commands are triggered.
+
### initCommands
+
_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# OPTIONAL. Run one or more commands each time a new runtime container
@@ -19329,22 +27669,35 @@ zerops:
initCommands:
- rm -rf ./cache
```
+
These commands are triggered in the runtime container before your Python application is started via the [start command](#start).
+
:::note
`run.initCommands` run in the `/var/www` directory.
:::
+
Use init commands to clean or initialise your application cache or similar operations.
+
:::caution
The init commands will delay the start of your application each time a new runtime container is started (including the horizontal [scaling](/python/how-to/scaling) or when a runtime container is restarted).
+
Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](#preparecommands-1) attribute instead.
:::
+
#### Command exit code
+
If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](/python/how-to/logs#runtime-log) to troubleshoot the error.
+
#### Single or separated shell instances
+
You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build:prepareCommands](#preparecommands).
+
### envVariables
+
_OPTIONAL._ Defines the environment variables for the runtime environment.
+
Enter one or more env variables in following format:
+
```yaml
zerops:
# define hostname of your service
@@ -19359,56 +27712,82 @@ zerops:
DB_USER: db
DB_PASS: ${db_password}
```
+
Read more about [environment variables](/python/how-to/env-variables) in Zerops.
+
### start
+
_REQUIRED._ Defines the start command for your Python application.
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Python application start command
start: app.py
```
+
### health check
+
_OPTIONAL._ Defines a health check.
+
`healthCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the health check to request a local URL using a HTTP GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Python application start command
start: app.py
+
# OPTIONAL. Define a health check with a HTTP GET request option.
# Configures the check on http://127.0.0.1:80/status
healthCheck:
@@ -19416,30 +27795,47 @@ zerops:
port: 80
path: /status
```
+
#### exec
+
Configures the health check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
Defines a local command to be run.
- The command has access to the same environment variables as your Python application.
+
+ The command has access to the same [environment variables](/python/how-to/create#set-secret-environment-variables) as your Python application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to run your application ====
run:
# REQUIRED. Your Python application start command
start: app.py
+
# OPTIONAL. Define a health check with a shell command.
healthCheck:
exec:
@@ -19448,13 +27844,18 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
### crontab
+
_OPTIONAL._ Defines cron jobs.
+
Setup cron jobs in the following format:
+
```yaml
zerops:
# define hostname of your service
- setup: app
+
# ==== how to run your application ====
run:
crontab:
@@ -19463,40 +27864,62 @@ zerops:
# REQUIRED. Sets the interval time to execute:
timing: "0 * * * *"
```
+
Read more about setting up [cron](/zerops-yaml/cron) in Zerops.
+
## Deploy configuration
+
### readiness check
+
_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](/python/how-to/deploy-process#readiness-checks) in Zerops.
+
`readinessCheck` requires either one `httpGet` object or one `exec` object.
+
#### httpGet
+
Configures the readiness check to request a local URL using a http GET method.
+
Following attributes are available:
-
- Parameter
- Description
-
- port
- Defines the port of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- path
- Defines the URL path of the HTTP GET request.
-The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
-
- host
- Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
-
- scheme
- Optional. The readiness check is triggered from inside of your runtime container so no https is required.
-If your application requires a https request, set scheme: https
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
port
+
Defines the port of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
path
+
Defines the URL path of the HTTP GET request.
+The readiness check will trigger a GET request on {'http://127.0.0.1:{port}/{path}'}
+
+
+
host
+
Optional. The readiness check is triggered from inside of your runtime container so it always uses the localhost 127.0.0.1. If you need to add a host to the request header, specify it in the host attribute.
+
+
+
scheme
+
Optional. The readiness check is triggered from inside of your runtime container so no https is required.
+If your application requires a https request, set scheme: https
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -19505,30 +27928,48 @@ zerops:
httpGet:
port: 80
path: /status
+
# ==== how to run your application ====
run: ...
```
+
Read more about how the [readiness check works](/python/how-to/deploy-process#readiness-checks) in Zerops.
+
#### exec
+
Configures the readiness check to run a local command.
Following attributes are available:
-
- Parameter
- Description
-
- command
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
command
+
Defines a local command to be run.
- The command has access to the same environment variables as your Python application.
+
+ The command has access to the same [environment variables](/python/how-to/create#set-secret-environment-variables) as your Python application.
+
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below.
-
+
+
+
+
+
**Example:**
+
```yaml
zerops:
# hostname of your service
- setup: app
# ==== how to build your application ====
build: ...
+
# ==== how to deploy your application ====
deploy:
# OPTIONAL. Define a readiness check with a HTTP GET request option.
@@ -19540,8 +27981,10 @@ zerops:
rm -rf life
mv /outside/user /home/user
```
+
Read more about how the [readiness check works](/python/how-to/deploy-process#readiness-checks) in Zerops.
+
----------------------------------------
# Python > How To > Build Process
@@ -19558,35 +28001,60 @@ Read more about how the [readiness check works](/python/how-to/deploy-process#re
# Python > How To > Create
+
Zerops provides a Python runtime service with extensive build support. Python runtime is highly scalable and customisable to suit both development and production.
+
## Create Python service using Zerops GUI
+
First, set up a project in Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu in the **Services** block. Then add a new Python service:
+
+[Video: /vids/services/python.webm](/vids/services/python.webm)
+
### Choose Python version
+
Following Python versions are currently supported:
+
:::info
You can [change](/python/how-to/upgrade) the major version at any time later.
:::
+
### Set a hostname
+
Enter a unique service identifier like "app","cache", "gui" etc. Duplicate services with the same name in the same project are forbidden.
+
#### Limitations:
+
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
:::caution
The hostname is fixed after the service is created. It can't be changed later.
:::
+
### Set secret environment variables
+
Add environment variables with sensitive data, such as password, tokens, salts, certificates etc. These will be securely saved inside Zerops and added to your runtime service upon start.
+
Setting the secret environment variables is optional. You can set them later in Zerops GUI.
+
Read more about [different types of env variables](/python/how-to/env-variables#service-env-variables) in Zerops.
+
## Create Python service using zCLI
+
zCLI is the Zerops command-line tool. To create a new Python service via the command-line, follow these steps:
+
1. [Install & setup zCLI](/references/cli)
2. [Create a project description file](/python/how-to/create#create-a-project-description-file)
3. [Create a project with a Python and PostgreSQL service](#full-example)
+
### Create a project description file
+
Zerops uses a yaml format to describe the project infrastructure.
+
#### Basic example:
+
Create a directory `my-project`. Create an `description.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -19607,13 +28075,18 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes your future project infrastructure. The project will contain one Python version 3.12 service with default [auto scaling](/python/how-to/scaling) configuration. Hostname will be set to "app", the internal port(s) the service listens on will be defined later in the [zerops.yaml](/python/how-to/build-pipeline#ports). Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
#### Full example:
+
Create a directory my-project. Create an description.yaml file inside the my-project directory with following content:
+
```yaml
# basic project data
project:
@@ -19658,114 +28131,172 @@ services:
# mode of operation "HA"/"non_HA"
mode: NON_HA
```
+
The yaml file describes your future project infrastructure. The project will contain a Python service and a [PostgreSQL](/postgresql/overview) service.
+
Python service with "app" hostname, the internal port(s) the service listens on will be defined later in the zerops.yaml. Python service will run on version 3.12 with a custom vertical and horizontal scaling. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The hostname of the PostgreSQL service will be set to "db". The [single container](/features/scaling#single-container-mode)(/features/scaling#deployment-modes-databases-and-shared-storage) mode will be chosen and the default auto [scaling configuration](/postgresql/how-to/scale#configure-scaling) will be set.
+
#### Description of description.yaml parameters
+
The `project:` section is required. Only one project can be defined.
-
- Parameter
- Description
- Limitations
-
- name
- The name of the new project. Duplicates are allowed.
-
- description
- Optional. Description of the new project.
- Maximum 255 characters.
-
- tags
- Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
-
+
+
+
+
+
Parameter
+
Description
+
Limitations
+
+
+
+
+
name
+
The name of the new project. Duplicates are allowed.
+
+
+
+
description
+
Optional. Description of the new project.
+
Maximum 255 characters.
+
+
+
tags
+
Optional. One or more string tags. Tags do not have a functional meaning, they only provide better orientation in projects.
+
+
+
+
+
At least one service in `services:` section is required. You can create a project with multiple services. The example above contains Python and PostgreSQL services but you can create a `description.yaml` with your own combination of [services](/features/infrastructure).
-
- Parameter
- Description
-
- hostname
-
+
+
+
+
+
Parameter
+
Description
+
+
+
+
+
hostname
+
The unique service identifier.
-
+
The hostname of the new service will be set to the `hostname` value.
-
- Limitations:
-
- duplicate services with the same name in the same project are forbidden
- maximum 25 characters
- must contain only lowercase ASCII letters (a-z) or numbers (0-9)
-
- type
-
+
+ Limitations:
+
+
duplicate services with the same name in the same project are forbidden
+
maximum 25 characters
+
must contain only lowercase ASCII letters (a-z) or numbers (0-9)
+
+
+
+
+
type
+
Specifies the service type and version.
-
+
See what [Python service types](/references/import-yaml/type-list#runtime-services) are currently supported.
-
- verticalAutoscaling
-
- Optional. Defines custom vertical auto scaling parameters.
-
+
+
+
+
verticalAutoscaling
+
+ Optional. Defines [custom vertical auto scaling parameters](/python/how-to/create#set-auto-scaling-configuration).
+
All verticalAutoscaling attributes are optional. Not specified attributes will be set to their default values.
-
- - cpuMode
-
- Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
-
- - minCpu/maxCpu
-
- Optional. Set the minCpu or maxCpu in CPU cores (integer).
-
- - minRam/maxRam
-
- Optional. Set the minRam or maxRam in GB (float).
-
- - minDisk/maxDisk
-
- Optional. Set the minDisk or maxDisk in GB (float).
-
- minContainers
-
- Optional. Default = 1. Defines the minimum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
- cpuMode
+
+ Optional. Accepts `SHARED`, `DEDICATED` values. Default is `SHARED`
+
+
+
+
- minCpu/maxCpu
+
+ Optional. Set the minCpu or maxCpu in CPU cores (integer).
+
+
+
+
- minRam/maxRam
+
+ Optional. Set the minRam or maxRam in GB (float).
+
+
+
+
- minDisk/maxDisk
+
+ Optional. Set the minDisk or maxDisk in GB (float).
+
+
+
+
minContainers
+
+ Optional. Default = 1. Defines the minimum number of containers for [horizontal autoscaling](/python/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- maxContainers
-
- Defines the maximum number of containers for horizontal autoscaling.
-
- Limitations:
-
+
+
+
+
maxContainers
+
+ Defines the maximum number of containers for [horizontal autoscaling](/python/how-to/create#horizontal-auto-scaling).
+
+ Limitations:
+
Current maximum value = 10.
-
- envSecrets
-
- Optional. Defines one or more secret env variables as a key value map. See env variable restrictions.
-
+
+
+
+
envSecrets
+
+ Optional. Defines one or more secret env variables as a key value map. See env variable [restrictions](/python/how-to/env-variables#env-variable-restrictions).
+
+
+
+
+
### Create a project based on the description.yaml
+
When you have your `description.yaml` ready, use the `zcli project project-import` command to create a new project and the service infrastructure.
+
```sh
Usage:
zcli project project-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project import command.
--org-id string If you have access to more than one organization, you must specify the org ID for which the
project is to be created.
--working-dir string Sets a custom working directory. Default working directory is the current directory. (default "./")
```
+
Zerops will create a project and one or more services based on the `description.yaml` content.
+
Maximum size of the `description.yaml` file is 100 kB.
+
You don't specify the project name in the `zcli project project-import` command, because the project name is defined in the `description.yaml`.
+
If you have access to more than one client, you must specify the client ID for which the project is to be created. The `clientID` is located in the Zerops GUI under the client name on the project dashboard page.
-
+
### Add Python service to an existing project
+
#### Example:
+
Create a directory `my-project` if it doesn't exist. Create an `import.yaml` file inside the `my-project` directory with following content:
+
```yaml
# basic project data
project:
@@ -19786,33 +28317,38 @@ services:
S3_ACCESS_KEY_ID: 'P8cX1vVVb'
S3_ACCESS_SECRET: 'ogFthuiLYki8XoL73opSCQ'
```
+
The yaml file describes the list of one or more services that you want to add to your existing project. In the example above, one Python service version 3.12 with default [auto scaling](/python/how-to/scaling) configuration will be added to your project. Hostname of the new service will be set to `app`. Following secret env variables will be configured:
+
```env
S3_ACCESS_KEY_ID="P8cX1vVVb"
S3_ACCESS_SECRET="ogFthuiLYki8XoL73opSCQ"
```
+
The content of the `services:` section of `import.yaml` is identical to the project description file. The `import.yaml` never contains the `project:` section because the project already exists.
+
When you have your `import.yaml` ready, use the `zcli project service-import` command to add one or more services to your existing Zerops project.
+
```sh
Usage:
zcli project service-import importYamlPath [flags]
+
Flags:
-h, --help Help for the project service import command.
-P, --project-id string If you have access to more than one project, you must specify the project ID for which the
command is to be executed.
```
+
zCLI commands are interactive, when you press enter after `zcli project service-import importYamlPath`, you will be given a list of your projects to choose from.
+
Maximum size of the import.yaml file is 100 kB.
+
----------------------------------------
# Python > How To > Customize Runtime
-System packages for processing: When your app processes images, videos, or files (requiring packages like sudo apk add --no-cache imagemagick)',
- 'Python build tools: When you need setuptools, or other tools not included by default',
- 'Scientific libraries: When you need NumPy, SciPy, or other packages requiring system dependencies',
- 'Different base OS: When you need Ubuntu instead of Alpine for specific compatibility requirements'
-]} />
+
----------------------------------------
@@ -19866,13 +28402,21 @@ System packages for processing: When your app processes images, videos, or files
# Python > Overview
+
[Python ↗](https://www.python.org/) is a programming language that lets you work quickly and integrate systems more effectively..
+
As said, there is no need for coding yet, we have created a [Github repository ↗](https://github.com/zeropsio/recipe-python-hello-world), a **_recipe_**, containing the most simple Python web application. The repo will be used as a source from which the app will be built.
- This is the most bare-bones example of Python running in Zerops — as few libraries as possible,
+
+### 🚀 Feel free to deploy the recipe yourself
+
+This is the most bare-bones example of Python running in Zerops — as few libraries as possible,
just a simple endpoint with connect, read and write to a Zerops PostgreSQL database.
-
+
+ [Deploy "python" recipe on Zerops](https://app.zerops.io/recipe/?lf=python)
+
1. Log in/sign up to [Zerops GUI ↗](https://app.zerops.io)
2. In the **Projects** box click on **Import a project** and paste in the following YAML config ([source ↗](https://github.com/zeropsio/recipe-python-hello-world/blob/main/import-project/description.yaml)):
+
```yaml
project:
name: my-first-project
@@ -19884,37 +28428,76 @@ services:
buildFromGit: https://github.com/zeropsio/recipe-python-hello-world@main
enableSubdomainAccess: true
```
+
3. Click on **Import project** and wait until all pipelines have finished.
+
**That's it, your application is now up and running! :star: Let's check it works:**
+
1. A _subdomain_ should have been enabled and visible in the project's **IP addressed & Public Routing Overview** box. Its format should look similar to this `https://helloworld-24-8080.prg1.zerops.app`.
2. Click or the `subdomain` URL to open it in a browser and you should see
+
```
Hello, World!
```
+
:::tip
Do you have any questions? Check the step-by-step tutorial, browse the documentation and join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members.
:::
+
## How to start
+
+- [Care for details?](/python/how-to/create) — Dive in all Zerops has to offer for your Python application.
+
## Feature Highlights
+
+- [Create Python service](/python/how-to/create) — Start with creating a Python service using GUI or zCLI.
+- [zerops.yaml](/python/how-to/build-pipeline#add-zeropsyaml-to-your-repository) — See a full example of zerops.yaml file to create your own app.
+- [Scaling configuration](/python/how-to/scaling) — Set up scaling of your Python application so that it runs smoothly while using only necessary resources.
+
{" "}
+
+- [Customize build environment](/python/how-to/build-process#customize-build-environment)
+- [Customize runtime environment](/python/how-to/customize-runtime)
+
## When in doubt, reach out
+
Don't know how to start or got stuck during the process? You might not be the first one, visit the FAQ section to find out.
+
In case you haven't found an answer (and also if you have), we and our community are looking forward to hearing from you on Discord.
+
Have you build something that others might find useful? Don't hesitate to share your knowledge!
+
+- [FAQ](/python/faq) — Most common questions in one place.
+- [Discord](https://discord.com/invite/WDvCZ54) — Join our core team and Zerops community on Discord. Ask questions and share your tips with other members.
+
## Popular Guides
+- [zCLI](/references/cli) — Get even more out of Zerops with the zCLI command line tool.
+- [Zerops VPN](/references/networking/vpn) — Connect to your services easily with Zerops VPN.
+
+
----------------------------------------
# Qdrant > Overview
+
[Qdrant](https://qdrant.tech/) in Zerops provides a fully managed vector database solution designed for AI applications. Focus on building vector search features while we handle infrastructure maintenance, high availability, and data protection.
+
## Supported Versions
+
Currently supported Qdrant versions:
+
Import configuration version:
+
+- `qdrant@1.12`
+- `qdrant@1.10`
+
## Deployment Modes
+
#### Non-HA Mode
- Single node setup ideal for development and non-production projects
- Simple deployment and management
+
#### HA Cluster
- Automatically configured with 3 nodes
- Recommended for production environments
@@ -19922,31 +28505,47 @@ Import configuration version:
- By default (`automaticClusterReplication=true`), automatically creates replicas of all shards across all three nodes
- Can be disabled by setting `automaticClusterReplication` to `false`
- Automatic cluster recovery and node replacement in case of failures
+
## Data Backup
+
Qdrant backups are created using native snapshotting:
+
- **Format**: `.snapshot` (compressed)
- **Tooling**: Native snapshotting
- **Source**: Taken from the primary node (leader in HA clusters)
+
For backup configuration, scheduling, retention policies, and management options, see the [Zerops Backups](/features/backup) documentation.
+
### Restoring Backups
+
To restore a Qdrant backup:
+
1. **Download** the backup file (`.snapshot`) from the Zerops UI
2. **Prepare** your target environment (clean existing collections or use a new instance)
3. **Restore** using the Qdrant API. Use the snapshot restore endpoint to import the snapshot file. Follow the [official Qdrant documentation](https://qdrant.tech/documentation/database-tutorials/create-snapshot/#restore-from-snapshot) for detailed snapshot restore procedures.
+
For assistance with the restoration process, contact Zerops support.
+
## Network Architecture & Access
+
Qdrant can be accessed only from services within the same project, public access is not available.
+
### API Keys
API key authentication is required for both HTTP and gRPC API calls. Include the key in your request headers. The keys are automatically generated when the Qdrant service is created and can be found in the service's environment variables:
+
- **`apiKey`:** Full access API key for administrative operations (creating collections, indexing)
- **`readOnlyApiKey`:** Restricted API key for search operations
+
#### HTTP API
- **Port:** `6333`
- **Connection String:** Available as `connectionString` environment variable or construct using `http://${hostname}:${port}`
+
#### gRPC API
- **Port:** `6334`
- **gRPC Connection String:** Available as `grpcConnectionString` environment variable or construct using `tcp://${hostname}:${grpcPort}`
+
## Support
+
For advanced configurations or custom requirements:
- Join our [Discord community](https://discord.gg/zeropsio)
- Contact support via [email](mailto:support@zerops.io)
@@ -19955,295 +28554,436 @@ For advanced configurations or custom requirements:
# References > Api
+
The Zerops REST API allows you to programmatically interact with Zerops platform by providing access to resources like projects, services, users, billing, and configurations.
+
## Base URL
+
All API requests should be made to:
```
https://api.app-prg1.zerops.io/api/rest/public
```
+
## Authentication
+
The API uses Bearer token authentication. You can obtain your Personal access token from the **Access Token management** section in the Zerops GUI.
+
Include the token in the Authorization header:
```
-Authorization: Bearer
+Authorization: Bearer
```
+
## API Resources
+
:::note
Some resource groups have non-obvious naming:
- `/service-stack` endpoints handle services management
- `/user-data` endpoints handle environment variables management
:::
+
View the [full Swagger documentation](https://api.app-prg1.zerops.io/api/rest/public/swagger) or jump to a specific resource group:
-
- Group
- Description
-
- /app-version
- Manage application versions, builds, and deployments
-
- /auth
- Authentication and token management
-
- /billing
- Billing operations and payment management
-
- /client
- Client account management
-
- /client-user
- User management within client accounts
-
- /github
- GitHub repository connections and authorization
-
- /gitlab
- GitLab repository connections and authorization
-
- /project
- Project management operations
-
- /project-env
- Project environment variables management
-
- /public-http-routing
- HTTP routing configuration
-
- /public-port-routing
- Port routing and firewall rules configuration
-
- /service-stack
- Service stack operations and configuration
-
- /settings
- System settings and configurations
-
- /user
- User account management
-
- /user-data
- Environment variables management
-
- /user-notification
- User notifications management
-
- /user-token
- Personal access tokens management
-
+
+
----------------------------------------
# References > Cli
+
zCLI is the command-line tool for Zerops that allows users to manage services, simplify interactions, and configure infrastructure directly from the terminal.
+
For detailed information, see the [Configuration](/references/zcli/configuration) and [Commands Reference](/references/zcli/commands) pages.
+
## Platforms
+
zCLI currently supports:
+
- Linux (x86 & x64)
- macOS (x86-64 & ARM64)
- Windows (x64)
+
## Get started
+
### Manual Installation
+
To download the zCLI directly, get the [latest release](https://github.com/zeropsio/zcli/releases) from GitHub.
+
### Linux/MacOS
+
```sh
curl -L https://zerops.io/zcli/install.sh | sh
```
+
zCLI will be installed inside `/usr/bin` or `/usr/local/bin`.
+
### Windows
+
Execute following command in PowerShell:
+
```powershell
irm https://zerops.io/zcli/install.ps1 | iex
```
+
zCLI will be installed inside `C:\Program Files\` or `C:\Program Files (x86)\`
+
### Using Package Managers
+
You can also install zCLI using package managers:
+
```sh
npm i -g @zerops/zcli
```
+
```sh
yarn global add @zerops/zcli
```
+
### NixOS
+
:::note
Make sure `nix-command` and flakes are enabled, if not. You can also use `--extra-experimental-features 'nix-command flakes'` with `nix`.
:::
+
Clone the [zCLI repository](https://github.com/zeropsio/zcli) and build the binary.
+
```
git clone https://github.com/zeropsio/zcli
```
+
```
cd zcli
```
+
```
nix develop
```
+
```
nix build
```
+
You can find zCLI binary inside `result/bin`.
+
## Personal access tokens
+
Personal tokens allow you to securely access Zerops directly. You can create one or more personal tokens and manage them in [Zerops GUI](https://app.zerops.io).
+
### Managing your access tokens
+
To create a new personal access token, go to [Access Tokens management](https://app.zerops.io/settings/token-management) and click "Generate a new access token".
-
+
You may delete an access token anytime.
+
### Using access tokens
+
You may use an access token to access Zerops using this command:
+
```sh
-zcli login
+zcli login
```
----------------------------------------
# References > Github Integration
+
Discover how to seamlessly integrate your GitHub repository with Zerops for automated builds and deployments.
+
You can choose between two powerful integration approaches: direct integration through the Zerops GUI for straightforward setup, or GitHub Actions for more customized deployment workflows.
+
This guide walks you through both integration methods, helping you choose and implement the approach that best fits your team's needs.
+
---
+
## Prerequisites
+
Before starting the integration process, ensure your repository contains a valid `zerops.yaml` configuration file located in the root directory. This file is essential for defining the build, deploy, and run processes.
For detailed information on how to create or modify this file, refer to the [Zerops YAML configuration](/zerops-yaml/specification) guide.
+
---
+
## Integration via Zerops GUI
+
Follow these steps to connect your GitHub repository directly with Zerops:
+
1. **Access Service Settings**
+
- Log into the [**Zerops GUI**](https://app.zerops.io/)
- Select the relevant service from your dashboard.
- In the left-hand menu, navigate to **Build, Deploy, Run Pipeline Settings**.
+
2. **Connect to GitHub**
+
- Click **Connect with a GitHub repository**
- You'll be prompted to authorize Zerops to access your GitHub account.
- Grant the necessary permissions for Zerops to manage webhooks and fetch your code.
+
:::note
Zerops requires full access to your repository in order to configure webhooks and pull the latest code changes. However, Zerops does not store your source code unless explicitly specified by you.
:::
+
3. **Select Repository and Trigger**
+
- Choose the GitHub repository you'd like to integrate with Zerops.
- Configure the trigger that will initiate a build:
- **New tag**: Builds are triggered whenever a new tag is created. This is the recommended option for production deployments.
- You can optionally add a regular expression (regex) to filter specific tags.
- **Push to branch**: Builds are triggered on every push to a specified branch, such as `main` or `develop`.
+
4. **Finalize Setup**
+
- Review and confirm your settings to complete the integration process.
- Your GitHub repository is now connected, and builds will be triggered based on the configured triggers.
-
+
---
+
### Skip the automatic pipeline once
+
To ensure that a pipeline is not triggered by a specific commit, add `[ci skip]` or `[skip ci]` to the commit message. It is case insensitive.
+
:::note
You will still see a successful delivery of a webhook in your GitHub repository as a webhook is actually triggered, but with no action.
:::
+
---
+
### Disconnecting Your Repository
+
To disconnect your GitHub repository from Zerops:
+
1. Navigate to the **Service Details** page for the relevant service
1. Select **Build, Deploy, Run Pipeline Settings** from the menu.
1. Click **Stop automatic build trigger**
+
**This action will remove the GitHub webhook and delete the associated integration configuration, effectively halting automated builds from this repository.**
-
+
### Authorizing Access to Organizations
+
If you want to authorize Zerops to access a specific organization, you can do so by clicking on the **Grant** from [GitHub Applications Settings](https://github.com/settings/connections/applications/4408deded6c1fed7193c).
+
---
+
## GitHub Workflow Integration
+
As an alternative to direct integration, you can use GitHub Actions to manage your deployments. This approach gives you more control over your deployment workflow and allows integration with other CI/CD processes.
+
### GitHub Workflow using Zerops Actions
+
1. **Create Workflow Configuration**
+
Create a new file at `.github/workflows/deploy.yaml` in your repository:
+
```yaml
name: Deploy to Zerops
-
+
on:
push:
branches:
- main
-
+
jobs:
deploy:
runs-on: ubuntu-latest
-
+
steps:
- name: Checkout code
uses: actions/checkout@v3
-
+
- name: Deploy with Zerops
uses: zeropsio/actions@main
with:
access-token: ${{ secrets.ZEROPS_TOKEN }}
service-id: your-service-id
```
+
2. **Generate Access Token**
+
- Navigate to [**Settings > Access Token Management**](https://app.zerops.io/settings/token-management) in your Zerops dashboard
- Generate a new access token with appropriate permissions
- Copy this token for use in GitHub secrets
+
3. **Locate Service ID**
+
- Go to your service dashboard and click the three dots menu → **Copy Service ID**
- - Alternatively, find it in your service URL: `https://app.zerops.io/service-stack//dashboard`
+ - Alternatively, find it in your service URL: `https://app.zerops.io/service-stack//dashboard`
+
4. **Configure GitHub Secrets**
+
- Go to your GitHub repository settings
- Navigate to **Settings** > **Secrets and variables** > **Actions** > **Repository secrets**
- Add a new secret named `ZEROPS_TOKEN` with your access token value
+
:::note
Keep your access token secure and never commit it directly to your repository. The token provides administrative access to your Zerops resources.
:::
+
For more information about GitHub Actions, refer to the [official GitHub Actions documentation](https://docs.github.com/en/actions).
+
----------------------------------------
# References > Gitlab Integration
+
Discover how to seamlessly integrate your GitLab repository with Zerops for automated builds and deployments.
+
This guide walks you through the step-by-step process to link your repository, configure triggers, and manage your integrations efficiently.
+
---
+
## Prerequisites
+
Before starting the integration process, ensure your repository contains a valid `zerops.yaml` configuration file located in the root directory. This file is essential for defining the build, deploy, and run processes.
For detailed information on how to create or modify this file, refer to the [Zerops YAML configuration](/zerops-yaml/specification) guide.
+
---
+
## Integration Steps
+
Follow these steps to connect your Gitlab repository with Zerops:
+
1. **Access Service Settings**
+
- Log into the [**Zerops GUI**](https://app.zerops.io/)
- Select the relevant service from your dashboard.
- In the left-hand menu, navigate to **Build, Deploy, Run Pipeline Settings**.
+
2. **Connect to GitLab**
+
- Click **Connect with a GitLab repository**
- You'll be prompted to authorize Zerops to access your GitLab account.
- Grant the necessary permissions for Zerops to manage webhooks and fetch your code.
+
:::note
Zerops requires full access to configure webhooks and download your code. Your source code is not stored after the build process.
:::
+
3. **Select Repository and Trigger**
+
- Choose the repository to integrate
- Select a trigger method:
- **New tag**: Builds trigger on new tags
- Optionally add a regex to filter tags
- **Push to branch**: Builds trigger on pushes to a specific branch
+
4. **Finalize Setup**
- Confirm your settings to complete the integration
+
-->
+
---
+
### Skip the automatic pipeline once
+
To ensure that a pipeline is not triggered by a specific commit, add `[ci skip]` or `[skip ci]` to the commit message. It is case insensitive.
+
:::note
You will still see a successful delivery of a webhook in your GitLab repository as a webhook is actually triggered, but with no action.
:::
+
---
+
## Disconnecting Your Repository
+
To disconnect your GitLab repository from Zerops:
+
1. Navigate to the **Service Details** page for the relevant service
1. Select **Build, Deploy, Run Pipeline Settings** from the menu.
1. Click **Stop automatic build trigger**
+
**This action will remove the GitLab webhook and delete the associated integration configuration, effectively halting automated builds from this repository.**
-
+
----------------------------------------
# References > Import Yaml > Pre Processor
+
The `yamlPreprocessor` option in your project & service import YAML allows you to generate random secret values, passwords, and public/private key pairs for your secret environment variables.
+
---
+
## How does it work?
+
The `yamlPreprocessor=on` is required as the first line in your import YAML to enable the preprocessor.
+
```yaml
#yamlPreprocessor=on
project:
@@ -20255,103 +28995,145 @@ services:
enableSubdomainAccess: true
envSecrets:
# yamlPreprocessor feat: generates a random 64 char and stores it
- SECRET_KEY: )>
-
+ SECRET_KEY: <@generateRandomString(<64>)>
+
- hostname: db
type: postgresql@16
mode: HA
```
+
After you've added the `yamlPreprocessor=on` line, the preprocessor will be enabled and you can now utilize the functions.
+
---
+
### How Preprocessing Works
+
The YAML script processing happens in two sequential steps. During the first turn (preprocessing), the system scans for Zerops import functions and modifiers, evaluates them, and replaces function calls with their results. All this data is stored in memory.
+
The second turn handles standard processing, where the system creates the imported project, instantiates all required services, and handles environment variables, including setting up any new ones as needed.
+
### Syntax Reference
-
- Sequence
- Description
-
- `
- The identifier of the beginning of a function expression syntax.
-
- `(`
- The identifier of the beginning of the function parameters.
-
- `)`
- The identifier of the end of the function parameters.
-
- `,`
- A function parameters delimiter.
-
- `
- Identifier of the beginning of a string expression (without @).
-
- `>`
- The identifier of the end of a string expression or a function expression syntax.
-
- `|`
- The separator between a string or a function expression content and a modifier name.
-
- `\`
- Escaping character.
-
- `\<>|`
- Characters that need to be escaped to print them out.
-
+
+
+
+
+
Sequence
+
Description
+
+
+
+
+
`<@`
+
The identifier of the beginning of a function expression syntax.
+
+
+
`(`
+
The identifier of the beginning of the function parameters.
+
+
+
`)`
+
The identifier of the end of the function parameters.
+
+
+
`,`
+
A function parameters delimiter.
+
+
+
`<`
+
Identifier of the beginning of a string expression (without @).
+
+
+
`>`
+
The identifier of the end of a string expression or a function expression syntax.
+
+
+
`|`
+
The separator between a string or a function expression content and a modifier name.
+
+
+
`\`
+
Escaping character.
+
+
+
`\<>|`
+
Characters that need to be escaped to print them out.
+
+
+
+
:::note
All functions in the preprocessor return values as strings, regardless of the operation performed. This includes numeric operations, random generation, and variable manipulation.
:::
+
---
+
## Parameter Data Types
+
Functions generally support 2 types of parameters.
+
### String expressions
-- Value is enclosed in `` characters.
-- Spaces between `` are NOT trimmed.
+
+- Value is enclosed in `<` and `>` characters.
+- Spaces between `<` and `>` are NOT trimmed.
- When the value is passed as a function parameter, it's always a string.
+
```yaml
-# String expression:
-SECRET_KEY: )>
-# String expressions: and
-RANDOM_RANGE: , )>
-# String expressions: , ,
-PICK_VALUE: , , )>
+# String expression: <16>
+SECRET_KEY: <@generateRandomString(<16>)>
+# String expressions: <1> and <100>
+RANDOM_RANGE: <@generateRandomInt(<1>, <100>)>
+# String expressions: , ,
+PICK_VALUE: <@pickRandom(, , )>
```
+
### Variable reference names
+
Variables are used to store and reuse values across your configuration. They can be created using functions like `setVar` and retrieved using `getVar`.
-- Variable references are NOT enclosed in `` when used with `getVar`
+
+- Variable references are NOT enclosed in `<` and `>` when used with `getVar`
- Variable names are case-sensitive
- Spaces before and after the reference name are trimmed
- Returns an error if the variable doesn't exist
+
```yaml
# Stores a value in myPassword variable
-PASSWORD: , )>)>
+PASSWORD: <@setVar(, <@generateRandomString(<30>)>)>
+
# Retrieves the stored value (myPassword)
-HASHED_PASSWORD:
+HASHED_PASSWORD: <@getVar(myPassword)|sha256>
# Reuses the stored value (myPassword)
-SAME_PASSWORD_AGAIN:
+SAME_PASSWORD_AGAIN: <@getVar(myPassword)>
```
+
:::tip Internal processing of function parameters
All parameters are handled as strings internally. For functions that expect numbers (like `generateRandomString`), the string values are automatically converted to numbers during processing.
:::
+
---
+
## Nested Expressions
+
The preprocessor supports nested function and string expressions, allowing you to:
- Combine multiple functions
- Use function outputs as inputs for other functions
- Nest string expressions within other strings
- Create complex, multi-level expressions
+
### Examples of Nesting with Environment Variables
+
```yaml
#yamlPreprocessor=on
services:
- hostname: app
type: nodejs@20
envSecrets:
- NESTED_STRINGS: content>
- NESTED_FUNCTIONS: , )>)>
- EVEN_MORE_NESTING: , , )>)>)>
+ NESTED_STRINGS: content>
+ NESTED_FUNCTIONS: <@generateRandomString(<@generateRandomInt(<20>, <50>)>)>
+ EVEN_MORE_NESTING: <@setVar(, <@generateRandomString(<@generateRandomInt(<20>, <30>)>)>)>
```
+
### Outputs of Nesting with Environment Variables
+
```yaml
#yamlPreprocessor=on
services:
@@ -20362,291 +29144,450 @@ services:
NESTED_FUNCTIONS: "58580f0ad377a8e4c0dccc1622e2d3812b90"
EVEN_MORE_NESTING: "73bcd2b647293dd04674cdecc"
```
+
### Escaping to Print Reserved Characters
+
Reserved characters `\<>|` have to be escaped using the `\` backslash to print them out. It's mandatory to escape the `\` character itself.
+
:::caution
The YAML processing happens in two sequential phases:
1. **Preprocessing Phase**: Evaluates functions, modifiers, and replaces them with results
2. **YAML Processing Phase**: Creates project, services, and handles environment variables
+
Each phase processes escape characters, so backslashes need to be escaped twice:
+
- If you want to output a single backslash `\`, you need to use four backslashes `\\\\`
- Example:
+
Input: `FILE_PATH: value\\\\with\\\\backslashes`
+
Output: `FILE_PATH: value\with\backslashes`
-It means that if `DIR: ` is used, the final value stored in the environment variable will be just `\`. The same is true for any value with backslashes, like `SERVER: True\\\\False`, where the stored result will be `True\False`.
+
+It means that if `DIR: <\\\\>` is used, the final value stored in the environment variable will be just `\`. The same is true for any value with backslashes, like `SERVER: True\\\\False`, where the stored result will be `True\False`.
:::
+
### Examples of Correct Function Expressions
+
```yaml
# Function will receive one parameter as the string constant value of: 30
-)>
+<@generateRandomString(<30>)>
# Function will receive two parameters as the string constant values of: 200 and 1000
-, )>
+<@generateRandomInt(<200>, <1000>)>
# It's possible to nest functions one into the other.
-, )>)>
+<@generateRandomString(<@generateRandomInt(<200>, <1000>)>)>
# Using commas inside a string constant passed as the parameter is possible.
# The passed value is stored as internal variable under the name: commentValue
-, )>
+<@setVar(, )>
# Function will receive one parameter as the internal variable reference: commentValue
# Its value is returned as a string if such an internal variable exists. If not, an error returns.
+<@getVar(commentValue)>
# Examples of function expressions with escaped characters:
-\ # Output:
-\)\> # Output: )>
-\, \)\> # Output: , )>
-\\, \)\> # Output: , )>
-\, )\> # Output:
+\<@generateRandomString(30)\> # Output: <@generateRandomString(30)>
+\<@generateRandomString(\<30\>)\> # Output: <@generateRandomString(<30>)>
+\<@generateRandomInt(\<30\>, \<80\>)\> # Output: <@generateRandomInt(<30>, <80>)>
+\<@generateRandomInt(\<30\>\, \<80\>)\> # Output: <@generateRandomInt(<30>, <80>)>
+\<@generateRandomInt(<30>, <80>)\> # Output: <@generateRandomInt(30, 80)>
```
+
---
+
:::tip What happens with environment variable references
Environment variable reference might need to be used as a part of string expressions. From the parsing point of view on the pre-processing level, they have not been recognized as something special but just a regular string, and they will be transparently passed without any modification. The second standard parsing turn only evaluates them.
:::
+
```yaml
+
# The part ` {ITEM_VALUE` is taken as a regular text when storing a string value as an internal variable.
-, )>
+<@setVar(, )>
# The returned value will be exactly the same when retrieving the previously stored value.
-)>
+<@getVar()>
# The returned value will be: By the way, this {ITEM_VALUE} is text passed over as a value.
+
```
+
---
+
## List of import functions
+
:::caution Important reminder
If you don't use the `yamlPreprocessor=on` line at the beginning of your import YAML script, the preprocessor will not be enabled and the functions will not work.
+
The `type: nodejs@latest` is just an example. The functions are available for all runtime types.
:::
+
---
+
### generateRandomString (length)
+
This function generates a random string of specified length using alphanumeric characters and some special characters (`_`, `-`, `.`). It's useful for creating random passwords, API keys, or any other secret values that needs to be unique and unpredictable.
-
- Field
- Details
-
- Syntax:
- `)>`
-
- Limitation:
- Length of the string should be an *integer* between `1` and `1024` characters. eg. ``, ``, ``.
-
- Output:
- hR5hS79H4p
-
+
+
+
+
+
Field
+
Details
+
+
+
+
+
Syntax:
+
`<@generateRandomString(<10>)>`
+
+
+
Limitation:
+
Length of the string should be an *integer* between `1` and `1024` characters. eg. `<10>`, `<512>`, `<1024>`.
+
+
+
Output:
+
hR5hS79H4p
+
+
+
+
#### Usage in import YAML
+
```yaml
#yamlPreprocessor=on
services:
- hostname: app
type: nodejs@20
envSecrets:
- RANDOM_STRING: )>
+ RANDOM_STRING: <@generateRandomString(<10>)>
```
+
#### Output of import YAML
+
```yaml
RANDOM_STRING: 58580f0ad377a8e4c0dccc1622e2d3812b90
```
+
---
+
### generateRandomBytes (length)
+
This function generates requested amount of cryptographically random bytes. It is useful for creating random passwords, API keys, or any other secret values that needs to be unique and unpredictable.
-
- Field
- Details
-
- Syntax:
- `)>`
-
- Limitation:
- Length of the string should be an *integer* between `1` and `1024` characters. eg. ``, ``, ``.
-
- Output:
- hR5hS79H4p
-
+
+
+
+
+
Field
+
Details
+
+
+
+
+
Syntax:
+
`<@generateRandomBytes(<10>)>`
+
+
+
Limitation:
+
Length of the string should be an *integer* between `1` and `1024` characters. eg. `<10>`, `<512>`, `<1024>`.
+
+
+
Output:
+
hR5hS79H4p
+
+
+
+
#### Usage in import YAML
+
```yaml
#yamlPreprocessor=on
services:
- hostname: app
type: nodejs@20
envSecrets:
- RANDOM_STRING: )>
+ RANDOM_STRING: <@generateRandomString(<10>)>
```
+
#### Output of import YAML
+
```yaml
RANDOM_STRING: 58580f0ad377a8e4c0dccc1622e2d3812b90
```
+
---
+
### generateRandomInt (min, max)
+
This function generates a random integer within a specified range (inclusive). It's particularly useful when you need random numeric values, like ports, timeouts, or any other configuration that requires random numbers within specific bounds.
-
- Field
- Details
-
- Syntax:
- `, )>`
-
- Minimum:
- Required minimum (inclusive) as a signed integer (from -4,611,686,018,427,387,903 to 4,611,686,018,427,387,903).
-
- Maximum:
- Required maximum (inclusive) as a signed integer (from -4,611,686,018,427,387,903 to 4,611,686,018,427,387,903).
-
- Output:
- 823
-
+
+
+
+
+
Field
+
Details
+
+
+
+
+
Syntax:
+
`<@generateRandomInt(<200>, <1000>)>`
+
+
+
Minimum:
+
Required minimum (inclusive) as a signed integer (from -4,611,686,018,427,387,903 to 4,611,686,018,427,387,903).
+
+
+
Maximum:
+
Required maximum (inclusive) as a signed integer (from -4,611,686,018,427,387,903 to 4,611,686,018,427,387,903).
+
+
+
Output:
+
823
+
+
+
+
#### Usage in import YAML
+
```yaml
#yamlPreprocessor=on
services:
- hostname: app
type: nodejs@20
envSecrets:
- RANDOM_INT: , )>
+ RANDOM_INT: <@generateRandomInt(<200>, <1000>)>
```
+
#### Output of import YAML
+
```yaml
RANDOM_INT: 823
```
+
---
+
### pickRandom (...param)
-
- Field
- Details
-
- Syntax:
- `, , , , , )>`
-
- Parameters:
- The required parameters from which the selection will be made. eg. ``, ``, ``, etc.
-
- Output:
- 1024
-
+
+
The required parameters from which the selection will be made. eg. `<1101>`, `<800>`, `<1920>`, etc.
+
+
+
Output:
+
1024
+
+
+
+
This function randomly selects one value from a list of provided options. It's helpful when you want to randomly assign values from a predefined set, such as screen resolutions, configuration options, or any other scenario where you need random selection from specific choices.
+
#### Usage in import YAML
+
```yaml
#yamlPreprocessor=on
services:
- hostname: app
type: nodejs@20
envSecrets:
- PICK_RANDOM: , , , , , )>
+ PICK_RANDOM: <@pickRandom(<640>, <800>, <1024>, <1280>, <1440>, <1920>)>
```
+
#### Output of import YAML
+
```yaml
PICK_RANDOM: 1024
```
+
---
+
### setVar (name, content)
+
This function stores a value in memory for later use and returns the stored value. It's particularly useful when you need to reuse the same generated value multiple times in your configuration, ensuring consistency across different environment variables.
-
- Field
- Details
-
- Syntax:
- `, )>)>`
-
- Variable:
- The required parameter of the internal variable name under which the provided content can be retrieved later using getVar function. The chosen name is case-sensitive. eg. ``, ``, etc
-
- Content:
- Any text you want to be stored, including composition using functions. Already existing variable with the same name is overwritten.
-
- Output:
- N4KdtM41WskS74wx
-
+
+
+
+
+
Field
+
Details
+
+
+
+
+
Syntax:
+
`<@setVar(, <@generateRandomString(<16>)>)>`
+
+
+
Variable:
+
The required parameter of the internal variable name under which the provided content can be retrieved later using [getVar](#getvar) function. The chosen name is case-sensitive. eg. ``, ``, etc
+
+
+
Content:
+
Any text you want to be stored, including composition using functions. Already existing variable with the same name is overwritten.
+
+
+
Output:
+
N4KdtM41WskS74wx
+
+
+
+
#### Usage in import YAML
+
```yaml
#yamlPreprocessor=on
services:
- hostname: app
type: nodejs@20
envSecrets:
- SET_VAR: , )>)>
+ SET_VAR: <@setVar(, <@generateRandomString(<16>)>)>
```
+
#### Output of import YAML
+
```yaml
SET_VAR: N4KdtM41WskS74wx
```
+
---
+
### getVar (name)
+
This function retrieves a previously stored value from memory. It works in conjunction with setVar and other storage functions to access values that were generated or stored earlier in the configuration process. eg. `plainPassword`
-
- Field
- Details
-
- Syntax:
- ``
-
- Variable:
- The required parameter of the internal variable name that is case-sensitive. The parameter is used as a reference, so it MUST NOT be enclosed in < and >. eg. `(plainPassword)`, `(varName)`, etc
-
- Output:
- N4KdtM41WskS74wx
-
+
+
+
+
+
Field
+
Details
+
+
+
+
+
Syntax:
+
`<@getVar(plainPassword)>`
+
+
+
Variable:
+
The required parameter of the internal variable name that is case-sensitive. The parameter is used as a reference, so it MUST NOT be enclosed in < and >. eg. `(plainPassword)`, `(varName)`, etc
+
+
+
Output:
+
N4KdtM41WskS74wx
+
+
+
+
#### Usage in import YAML
+
```yaml
#yamlPreprocessor=on
services:
- hostname: app
type: nodejs@20
envSecrets:
- GET_VAR:
+ GET_VAR: <@getVar(plainPassword)>
```
+
#### Output of import YAML
+
```yaml
GET_VAR: N4KdtM41WskS74wx
```
+
---
+
### generateRandomStringVar (name, length)
+
This function combines the functionality of `generateRandomString` and `setVar`. It generates a random string and automatically stores it under a specified variable name for later use.
+
The output contains only a random combination of alphanumeric characters (`a-zA-Z0-9`) and select special characters (`_`, `-`, `.`).
-
- Field
- Details
-
- Syntax:
- `, )>`
-
- Variable:
- The required parameter of the internal variable name under which the provided content can be retrieved later using getVar function. The chosen name is case-sensitive. eg. ``, ``, etc
-
- Limitation:
- Required length of the string to be generated in characters (maximum allowed value is 1024).
-
- Output:
- hR5hS79H4p
-
+
+
+
+
+
Field
+
Details
+
+
+
+
+
Syntax:
+
`<@generateRandomStringVar(, <10>)>`
+
+
+
Variable:
+
The required parameter of the internal variable name under which the provided content can be retrieved later using [getVar](#getvar) function. The chosen name is case-sensitive. eg. ``, ``, etc
+
+
+
Limitation:
+
Required length of the string to be generated in characters (maximum allowed value is 1024).
+
+
+
Output:
+
hR5hS79H4p
+
+
+
+
#### Usage in import YAML
+
```yaml
#yamlPreprocessor=on
services:
- hostname: app
type: nodejs@20
envSecrets:
- GENERATE_RANDOM_STRING_VAR: , )>
+ GENERATE_RANDOM_STRING_VAR: <@generateRandomStringVar(, <10>)>
```
+
#### Output of import YAML
+
```yaml
GENERATE_RANDOM_STRING_VAR: hR5hS79H4p
```
+
---
+
### generateJWT (tokenSecret, jsonPayload)
+
This function generates a JWT (JSON Web Token) signed by HS256 algorithm using provided secret and payload. The payload MUST be a valid JSON value. Default values for `iss` and `iat` are set to `zerops` and current timestamp respectively.
-
- Field
- Details
-
- Syntax:
- `, )>`
-
- Token Secret:
- The required secret (`string`) used to sign your JWT.
-
- JSON Payload:
- The required payload part of the JWT (`string`) in JSON format.
-
- Output:
- eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJpYXQiOjE3Mjkw
+
+
+
+
+
Field
+
Details
+
+
+
+
+
Syntax:
+
`<@generateJWT(, )>`
+
+
+
Token Secret:
+
The required secret (`string`) used to sign your JWT.
+
+
+
JSON Payload:
+
The required payload part of the JWT (`string`) in JSON format.
+
#### Usage in import YAML
+
```yaml
#yamlPreprocessor=on
services:
@@ -20654,79 +29595,114 @@ services:
type: nodejs@20
envSecrets:
# Using a fixed secret string
- JWT_FIXED: , )>
-
+ JWT_FIXED: <@generateJWT(, <{"role":"admin","exp":1798761600}>)>
+
# Using an empty payload
- JWT_EMPTY: , )>
-
+ JWT_EMPTY: <@generateJWT(, <{}>)>
+
# Generate and store a random secret, then use it
- JWT_RANDOM: , )>, )>
-
+ JWT_RANDOM: <@generateJWT(<@generateRandomStringVar(, <32>)>, <{"role":"admin","exp":1798761600}>)>
+
# Use a previously stored secret
- JWT_STORED: , )>
+ JWT_STORED: <@generateJWT(<@getVar(jwtSecretKeyVar)>, <{"role":"admin","exp":1798761600}>)>
```
+
#### Output of import YAML
+
```yaml
JWT_FIXED: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJleHAiOjE3OTg3NjE2MDAsImlhdCI6MTcyOTA2OTYzMiwiaXNzIjoiemVyb3BzIn0.xPrqHDtGhK5c7WMJliguwBeKI29qzAoD7KXrtACbjio
+
JWT_EMPTY: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MjkwNjk4NTcsImlzcyI6Inplcm9wcyJ9.xPrqHDtGhK5c7WMJliguwBeKI29qzAoD7KXrtACbjio
+
JWT_RANDOM: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJleHAiOjE3OTg3NjE2MDAsImlhdCI6MTcyOTA2OTYzMiwiaXNzIjoiemVyb3BzIn0.ksbck_HQv44YXbqJk6lDrGFYTq3nmLydFIe0Xlejk5Q
+
JWT_STORED: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYWRtaW4iLCJleHAiOjE3OTg3NjE2MDAsImlhdCI6MTcyOTA2OTYzMiwiaXNzIjoiemVyb3BzIn0.O0RaXzGFwj2t8P2kc4nU4PfuI43-dAuAl2d0T1uUlEE
```
+
---
+
### getDateTime (format, [timezone])
+
This function returns the current date and time formatted according to your specifications. It's useful for timestamps, logging, and any scenario where you need the current time in a specific format and timezone.
-Returns the current date and time in a specified mask pattern and a chosen timezone.
-
- Field
- Details
-
- Syntax:
- `, )>`
-
- Mask:
- The required parameter of the chosen timezone.
- eg. ``
-
- Timezone:
-
+
+Returns the current date and time in a [specified mask pattern](#masking) and a chosen timezone.
+
+
+
+
+
Field
+
Details
+
+
+
+
+
Syntax:
+
`<@getDatetime(, )>`
+
+
+
Mask:
+
The required parameter of the chosen timezone.
+ eg. ``
+
+
+
Timezone:
+
The optional parameter of the chosen timezone. It's possible to select from three different formats: Abbreviation, Location, and POSIX. If not specified, the GMT timezone is set by default.
- You can see the complete listing of all possible values. POSIX format uses the opposite sign. Times to the west are positive, to the east negative.
+
+ You can see the complete listing of [all possible values](https://nodatime.org/TimeZones). POSIX format uses the opposite sign. Times to the west are positive, to the east negative.
+
For Central European Time, you can use `CET`, `Europe/Prague`, `Etc/GMT-2` (summer), `Etc/GMT-1` (winter). Abbreviated and location formats return values with the currently valid DST.
- eg. ``, ``, ``
-
- Output:
- 11.12.2022 18:06:13
-
+
+ eg. ``, ``, ``
+
+
+
+
Output:
+
11.12.2022 18:06:13
+
+
+
+
#### Usage in import YAML
+
```yaml
#yamlPreprocessor=on
services:
- hostname: app
type: nodejs@20
envSecrets:
- GET_DATETIME: , )>
+ GET_DATETIME: <@getDatetime(, )>
```
+
#### Output of import YAML
+
```yaml
GET_DATETIME: 11.12.2022 18:06:13
```
+
#### Masking
-
- When using the `getDateTime` function, you can customize the output format using various masks. Here's a comprehensive list of available format patterns:
+
+#### Date and Time Format
+
+When using the `getDateTime` function, you can customize the output format using various masks. Here's a comprehensive list of available format patterns:
+
#### Year
- `YYYY` - Full year (e.g., 2024)
- `YY` - Two-digit year (e.g., 24)
+
#### Month
- `MMMM` - Full month name (e.g., January)
- `MMM` - Short month name (e.g., Jan)
- `MM` - Two-digit month (e.g., 01)
- `M` - Single-digit month (e.g., 1)
+
#### Day
- `DDDD` - Day of year with leading zeros (e.g., 001, 002, ..., 365)
- `DD` - Day of month with leading zeros (e.g., 01, 02, ..., 31)
- `D` - Day of month without leading zeros (e.g., 1, 2, ..., 31)
- `dddd` - Full weekday name (e.g., Monday)
- `ddd` - Short weekday name (e.g., Mon)
+
#### Time
- `HH` - 24-hour format with leading zeros (e.g., 00, 01, ..., 23)
- `hh` - 12-hour format with leading zeros (e.g., 01, 02, ..., 12)
@@ -20736,75 +29712,108 @@ GET_DATETIME: 11.12.2022 18:06:13
- `ss` - Seconds with leading zeros (e.g., 00, 01, ..., 59)
- `s` - Seconds without leading zeros (e.g., 0, 1, ..., 59)
- `S` - Microseconds (e.g., 000000...999999)
+
#### Period
- `A` - Uppercase meridiem (AM, PM)
- `a` - Lowercase meridiem (am, pm)
+
#### Timezone
- `ZZZ` - Timezone abbreviation (e.g., UTC, CET)
- `zz` - Timezone offset with colon (e.g., +00:00, +01:00)
- `Z` - Timezone offset without colon (e.g., +0000, +0100)
+
#### Usage of different masks
+
```yaml
#yamlPreprocessor=on
services:
- hostname: app
type: nodejs@20
envSecrets:
- TIMESTAMP: , )>
- FRIENDLY_DATE: , )>
+ TIMESTAMP: <@getDateTime(, )>
+ FRIENDLY_DATE: <@getDateTime(, )>
```
-
+
---
+
:::tip Example Usage for Environment Variables
- For Multiline Generation use:
```yaml
APP_PUBLIC_KEY: |
-
+ <@getVar(KeyPublic)>
```
+
- For Single Value Generation use:
```yaml
-APP_PUBLIC_KEY_SSH:
+APP_PUBLIC_KEY_SSH: <@getVar(KeyPublicSsh)>
```
:::
+
---
+
### generateED25519Key (name)
-Generates public and private ED25519 key pairs (including SSH) and stores them for later use as internal variables with names using the base name and variants.
-
- Field
- Details
-
- Syntax:
- `)>`
-
- Variants:
- The base name parameter stores all generated key versions as internal variables, combined with the Available Variants.
-
-#### Available Variants
-
- Variant
- Description
- Retrieving the value
-
- Public
- Public key version. This value is also returned by the called function.
- ``
-
- PublicSsh
- SSH formatted public key version. For use as the authorized key file.
- ``
-
- Private
- Private key version in the standard format. Not usable for OpenSSH.
- ``
-
- PrivateSsh
- Private key version in the OpenSSH format.
- ``
-
-#### Usage in import YAML
-:::caution
- These Generated keys are formatted as multiline strings. That means using the `|` syntax is necessary in import YAML.
-:::
+
+Generates public and private [ED25519](https://en.wikipedia.org/wiki/EdDSA) key pairs (including SSH) and stores them for later use as internal variables with names using the base name and variants.
+
+
+
+
+
Field
+
Details
+
+
+
+
+
Syntax:
+
`<@generateED25519Key()>`
+
+
+
Variants:
+
The base name parameter stores all generated key versions as internal variables, combined with the [Available Variants](#available-variants).
+
+
+
+
+#### Available Variants
+
+
+
+
+
Variant
+
Description
+
Retrieving the value
+
+
+
+
+
Public
+
Public key version. This value is also returned by the called function.
+
`<@getVar(KeyPublic)>`
+
+
+
PublicSsh
+
SSH formatted public key version. For use as the authorized key file.
+
`<@getVar(KeyPublicSsh)>`
+
+
+
Private
+
Private key version in the standard format. Not usable for OpenSSH.
+
`<@getVar(KeyPrivate)>`
+
+
+
PrivateSsh
+
Private key version in the OpenSSH format.
+
`<@getVar(KeyPrivateSsh)>`
+
+
+
+
+#### Usage in import YAML
+
+:::caution
+ These Generated keys are formatted as multiline strings. That means using the `|` syntax is necessary in import YAML.
+:::
+
```yaml
#yamlPreprocessor=on
services:
@@ -20812,52 +29821,69 @@ services:
type: nodejs@20
envSecrets:
GENERATED_PUBLIC_KEY: |
- )>
+ <@generateED25519Key()>
APP_PUBLIC_KEY: |
-
- APP_PUBLIC_KEY_SSH:
+ <@getVar(KeyPublic)>
+ APP_PUBLIC_KEY_SSH: <@getVar(KeyPublicSsh)>
APP_PRIVATE_KEY: |
-
+ <@getVar(KeyPrivate)>
APP_PRIVATE_KEY_SSH: |
-
+ <@getVar(KeyPrivateSsh)>
```
+
#### Output of import YAML
+
:::info
You can clearly see the multiline strings and the `|` syntax in Output.
:::
-
- - Generated as a multiline value
+
+#### GENERATED_PUBLIC_KEY
+
+- Generated as a multiline value
- The same value as in APP_PUBLIC_KEY.
+
```yaml
GENERATED_PUBLIC_KEY: |
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAu0/gEIpNUbVdqA20lVl+ZD+5/zzfVK4exrgGLxgQQRU=
-----END PUBLIC KEY-----
```
-
- - Generated as a multiline value.
+
+#### APP_PUBLIC_KEY
+
+- Generated as a multiline value.
- The same value as in GENERATED_PUBLIC_KEY.
+
```yaml
APP_PUBLIC_KEY: |
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAu0/gEIpNUbVdqA20lVl+ZD+5/zzfVK4exrgGLxgQQRU=
-----END PUBLIC KEY-----
```
-
- - Generated as a single value
+
+#### APP_PUBLIC_KEY_SSH
+
+- Generated as a single value
+
```yaml
APP_PUBLIC_KEY_SSH: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILtP4BCKTVG1XagNtJVZfmQ/uf8831SuHsa4Bi8YEEEV
```
-
- - Generated as a multiline value
+
+#### APP_PRIVATE_KEY
+
+- Generated as a multiline value
+
```yaml
APP_PRIVATE_KEY: |
-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEIFzW6uPLlMnse2Hqg4hlyTwtlWaPKHjyoaaBi/FfVxBQ
-----END PRIVATE KEY-----
```
-
- - Generated as a multiline value
+
+#### APP_PRIVATE_KEY_SSH
+
+- Generated as a multiline value
+
```yaml
APP_PRIVATE_KEY_SSH: |
-----BEGIN OPENSSH PRIVATE KEY-----
@@ -20868,42 +29894,67 @@ services:
ULtP4BCKTVG1XagNtJVZfmQ/uf8831SuHsa4Bi8YEEEVAAAAAAECAwQF
-----END OPENSSH PRIVATE KEY-----
```
-
+
---
+
### generateRSA2048Key (name)
-This Generates public and private RSA 2048bit key pairs (including SSH) and stores them for later use as internal variables with names using the base name and variants.
-
- Field
- Details
-
- Syntax:
- `)>`
-
- Variants:
- The base name parameter stores all generated key versions as internal variables, combined with the Available Variants.
-
+
+This Generates public and private [RSA 2048bit](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) key pairs (including SSH) and stores them for later use as internal variables with names using the base name and variants.
+
+
+
+
+
Field
+
Details
+
+
+
+
+
Syntax:
+
`<@generateRSA2048Key()>`
+
+
+
Variants:
+
The base name parameter stores all generated key versions as internal variables, combined with the [Available Variants](#available-variants).
+
+
+
+
#### Available Variants
-
- Variant
- Description
- How to use with: `)>`
-
- Public
- Public key version. This value is also returned by the called function.
- ``
-
- PublicSsh
- SSH formatted public key version. For use as the authorized key file.
- ``
-
- Private
- Private key version in the standard format.
- ``
-
+
+
+
+
+
Variant
+
Description
+
How to use with: `<@generateRSA2048Key()>`
+
+
+
+
+
Public
+
Public key version. This value is also returned by the called function.
+
`<@getVar(KeyPublic)>`
+
+
+
PublicSsh
+
SSH formatted public key version. For use as the authorized key file.
+
`<@getVar(KeyPublicSsh)>`
+
+
+
Private
+
Private key version in the standard format.
+
`<@getVar(KeyPrivate)>`
+
+
+
+
#### Usage in import YAML
+
:::caution
These Generated keys are formatted as multiline strings. That means using the `|` syntax is necessary in import YAML.
:::
+
```yaml
#yamlPreprocessor=on
services:
@@ -20912,20 +29963,25 @@ services:
minContainers: 1
envSecrets:
GENERATED_PUBLIC_KEY: |
- )>
+ <@generateRSA2048Key()>
APP_PUBLIC_KEY: |
-
- APP_PUBLIC_KEY_SSH:
+ <@getVar(KeyPublic)>
+ APP_PUBLIC_KEY_SSH: <@getVar(KeyPublicSsh)>
APP_PRIVATE_KEY: |
-
+ <@getVar(KeyPrivate)>
```
+
#### Output of import YAML
+
:::info
You can clearly see the multiline strings and the `|` syntax in Output.
:::
-
- - Generated as a multiline value
+
+#### GENERATED_PUBLIC_KEY
+
+- Generated as a multiline value
- The same value as in APP_PUBLIC_KEY.
+
```yaml
GENERATED_PUBLIC_KEY: |
-----BEGIN PUBLIC KEY-----
@@ -20938,9 +29994,12 @@ services:
UwIDAQAB
-----END PUBLIC KEY-----
```
-
- - Generated as a multiline value.
+
+#### APP_PUBLIC_KEY
+
+- Generated as a multiline value.
- The same value as in GENERATED_PUBLIC_KEY.
+
```yaml
APP_PUBLIC_KEY: |
-----BEGIN PUBLIC KEY-----
@@ -20953,13 +30012,19 @@ services:
UwIDAQAB
-----END PUBLIC KEY-----
```
-
- - Generated as a single value
+
+#### APP_PUBLIC_KEY_SSH
+
+- Generated as a single value
+
```yaml
APP_PUBLIC_KEY_SSH: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDJYwrH690Rv9bDX22tX0OiDvHp3gwIvi7nvp9V0OMEWFeNdisrRjSai+9g17vaq2mCBbwWcCIpsU1YwuvuZXXa7QkR0/NqpI5f9cpEpararvDJmMZTS5UsndF3ZjjIXKODrNu8DQeHkdGBufvGhExRtPea3WUE/4N4ciL17FO+2I1+k7RnVuJ2Ysu/MudqSDV6LxhacQAUmLzf8y5EyEhY4DfaHXhZVu+DhIDv75JMcXe4cv6Qcns/8p6oAIME9uBxz1LPtaxJMA7o92vLeysoI/rQAxpPY97AHnUC268VHyc/TlayQyB3zzsoddmOT02ENTkTTq/Pid/tre36K3RT
```
-
- - Generated as a multiline value
+
+#### APP_PRIVATE_KEY
+
+- Generated as a multiline value
+
```yaml
APP_PRIVATE_KEY: |
-----BEGIN PRIVATE KEY-----
@@ -21015,42 +30080,67 @@ services:
A0bX/JM8kHjLlJNrtioxcT+dX4lL6/zT
-----END PRIVATE KEY-----
```
-
+
---
+
### generateRSA4096Key (name)
-This Function Generates public and private RSA 4096bit key pairs (including SSH) and stores them for later use as internal variables with names using the base name and variants.
-
- Field
- Details
-
- Syntax:
- `)>`
-
- Variants:
- The base name parameter stores all generated key versions as internal variables, combined with the Available Variants.
-
+
+This Function Generates public and private [RSA 4096bit](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) key pairs (including SSH) and stores them for later use as internal variables with names using the base name and variants.
+
+
+
+
+
Field
+
Details
+
+
+
+
+
Syntax:
+
`<@generateRSA4096Key()>`
+
+
+
Variants:
+
The base name parameter stores all generated key versions as internal variables, combined with the [Available Variants](#available-variants).
+
+
+
+
#### Available Variants
-
- Variant
- Description
- How to use with: `)>`
-
- Public
- Public key version. This value is also returned by the called function.
- ``
-
- PublicSsh
- SSH formatted public key version. For use as the authorized key file.
- ``
-
- Private
- Private key version in the standard format.
- ``
-
+
+
+
+
+
Variant
+
Description
+
How to use with: `<@generateRSA4096Key()>`
+
+
+
+
+
Public
+
Public key version. This value is also returned by the called function.
+
`<@getVar(KeyPublic)>`
+
+
+
PublicSsh
+
SSH formatted public key version. For use as the authorized key file.
+
`<@getVar(KeyPublicSsh)>`
+
+
+
Private
+
Private key version in the standard format.
+
`<@getVar(KeyPrivate)>`
+
+
+
+
#### Usage in import YAML
+
:::caution
These Generated keys are formatted as multiline strings. That means using the `|` syntax is necessary in import YAML.
:::
+
```yaml
#yamlPreprocessor=on
services:
@@ -21058,20 +30148,25 @@ services:
type: nodejs@16
envSecrets:
GENERATED_PUBLIC_KEY: |
- )>
+ <@generateRSA4096Key()>
APP_PUBLIC_KEY: |
-
- APP_PUBLIC_KEY_SSH:
+ <@getVar(KeyPublic)>
+ APP_PUBLIC_KEY_SSH: <@getVar(KeyPublicSsh)>
APP_PRIVATE_KEY: |
-
+ <@getVar(KeyPrivate)>
```
+
#### Output of import YAML
+
:::info
You can clearly see the multiline strings and the `|` syntax in Output.
:::
-
- - Generated as a multiline value
+
+#### GENERATED_PUBLIC_KEY
+
+- Generated as a multiline value
- The same value as in APP_PUBLIC_KEY.
+
```yaml
GENERATED_PUBLIC_KEY: |
-----BEGIN PUBLIC KEY-----
@@ -21089,9 +30184,12 @@ services:
LdzErIs9vEaox5Qe6l4lhAUCAwEAAQ==
-----END PUBLIC KEY-----
```
-
- - Generated as a multiline value.
+
+#### APP_PUBLIC_KEY
+
+- Generated as a multiline value.
- The same value as in GENERATED_PUBLIC_KEY.
+
```yaml
APP_PUBLIC_KEY: |
-----BEGIN PUBLIC KEY-----
@@ -21109,13 +30207,19 @@ services:
LdzErIs9vEaox5Qe6l4lhAUCAwEAAQ==
-----END PUBLIC KEY-----
```
-
- - Generated as a single value
+
+#### APP_PUBLIC_KEY_SSH
+
+- Generated as a single value
+
```yaml
APP_PUBLIC_KEY_SSH: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDWRgQntuMGJfMEwj9wLrBqNyUd13k1nRuzHZ3x5VJodRrPjX19M9gFXuY95zTJti6VOG+pZftzuTkf+MlW9NwFEe/g0OomY6UwfKfPj4/ib3MPiASg2o4Ixqu0mv3IrLOsGmU25J38gAVQI3oohW4+B7Vp+2+RnLQCx1FsweWpa8wR0ffQwl0LsWSEWyutfSxi+5pbYwWORBOKyESmGFqGBhMfl0KutBqNAGLt9IYS61bYIqnvfzHqE1uIH3/+ViNzMAr56xt8Lr5a+Y84Mmer1h1wnh6OHnOE6y2sw+876RO8OjMTnHq6v1HDnKHQyCNHxDvpqihy7hlyRtCpC9fuCJC94lB0Gf65xgJC55Jx7gGRSbdLUhN2XZdQeAGPtdidz5KqC8S02fhiDKe0C78hpUGD8MZU4GqvqlyiHoouBhKugkba7F0NeSOLVC9GPLdKNjt5AyCi72pQz8vXaBk8TIb7F+WeQ3NtLw8sgZj0XjXRtx/S6SSoTIOkIKB6hKsPV0k+Z7VaVJ+FpXPsr2CbwcH0iyCJC6A6hLQWnDnts26PLcFck7hE6UjE4BsBhXQhcyMTe5Yai3y4V5NWoHinkLO9NX2N2hBcpQWSSCbr0wSg33xAHROzcG1w5/n1fq46723CbWW3GcsfnaL/hPIt3MSsiz28RqjHlB7qXiWEBQ==
```
-
- - Generated as a multiline value
+
+#### APP_PRIVATE_KEY
+
+- Generated as a multiline value
+
```yaml
APP_PRIVATE_KEY: |
-----BEGIN PRIVATE KEY-----
@@ -21171,230 +30275,490 @@ services:
A0bX/JM8kHjLlJNrtioxcT+dX4lL6/zT
-----END PRIVATE KEY-----
```
-
+
## Import modifiers
-Modifiers provide a simpler way to transform values compared to using functions alone. You can chain multiple modifiers together using the `|` symbol, making it easy to apply several transformations in sequence. They work with both string and function expressions - just add them between the `` markers, right before the closing `>`.
+
+Modifiers provide a simpler way to transform values compared to using functions alone. You can chain multiple modifiers together using the `|` symbol, making it easy to apply several transformations in sequence. They work with both string and function expressions - just add them between the `<` and `>` markers, right before the closing `>`.
+
---
+
### List of import modifiers
-
- Name
- Description
-
- sha256
- Generate a hash of the incoming string using sha256 algorithm.
-
- sha512
- Generate a hash of the incoming string using sha512 algorithm.
-
- bcrypt
-
- Generate a hash of the incoming string using bcrypt algorithm.
+
+
+
+
+
Name
+
Description
+
+
+
+
+
sha256
+
Generate a hash of the incoming string using [sha256](https://en.wikipedia.org/wiki/SHA-2) algorithm.
+
+
+
sha512
+
Generate a hash of the incoming string using [sha512](https://en.wikipedia.org/wiki/SHA-2) algorithm.
+
+
+
bcrypt
+
+ Generate a hash of the incoming string using [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) algorithm.
+
Fixed configuration: Number of cycles = 11
-
- argon2id
-
- Generate a hash of the incoming string using argon2id algorithm.
+
+
+
+
argon2id
+
+ Generate a hash of the incoming string using [argon2id](https://en.wikipedia.org/wiki/Argon2) algorithm.
+
Fixed configuration: Memory = 64MiB, Iterations = 4, Parallelism = 4, SaltLen = 16B, KeyLength = 32B
-
- toHex
- Encodes provided string/bytes into hexadecimal
-
- toString
- Encodes provided string/bytes into string comprised of [a-zA-Z0-9_-.]
-
- upper
- Maps all unicode letters to their upper case
-
- lower
- Maps all unicode letters to their lower case
-
- title
- Maps all words to title case (first letter upper case, rest lower case)
-
- noop
- Does nothing - used in tests
-
+
+
+
+
toHex
+
Encodes provided string/bytes into hexadecimal
+
+
+
toString
+
Encodes provided string/bytes into string comprised of [a-zA-Z0-9_-.]
+
+
+
upper
+
Maps all unicode letters to their upper case
+
+
+
lower
+
Maps all unicode letters to their lower case
+
+
+
title
+
Maps all words to title case (first letter upper case, rest lower case)
+
+
+
noop
+
Does nothing - used in tests
+
+
+
+
---
+
### Examples of correctly using import modifiers
-
- - `, )>` will output a random string of 30 characters:
+
+#### Generating a plain password and related hashes
+
+- `<@generateRandomStringVar(, <30>)>` will output a random string of 30 characters:
```yaml
7a14c8e74bc98a0d74253b1d1a4ef6
```
- - `)| sha256>` will output the sha256 hash of the `` variable:
+
+ - `<@getVar()| sha256>` will output the sha256 hash of the `` variable:
```yaml
081b91d6dff5036229a92e2442fb65d7c8124571d4e70a2ac4729aeb86957407
```
- - `)| sha512>` will output the sha512 hash of the `` variable:
+
+ - `<@getVar()| sha512>` will output the sha512 hash of the `` variable:
```yaml
89c05547de0aa4926512a958f95ab8bf4096ceec63ad5aad4266890bfa059e0cc98917c54276ba4cd61f1dde4c8efda948fc967885c9dd50558ed939722ca10c
```
- - `)| bcrypt>` will output the bcrypt hash of the `` variable:
+
+ - `<@getVar()| bcrypt>` will output the bcrypt hash of the `` variable:
```yaml
$2a$10$CxKZX0yIxdc7ts6eI5aBu.g.heAsFcePdMDEpnlViTlo3vGc//PXe
```
- - `)| argon2id>` will output the argon2id hash of the `` variable:
+
+ - `<@getVar()| argon2id>` will output the argon2id hash of the `` variable:
```yaml
$argon2id$v=19$m=98304,t=1,p=3$uWBpmoUT3sfckXHyRF9hlg$8bGtNffuHxaRIgN99zCmJeGEYJF5BY2J9TwzqmezP28
```
-
- - Using upper case modifier:
+
+#### String Case Modification Examples
+
+- Using upper case modifier:
```yaml
- Input:
+ Input:
Output: STATIC STRING WITH A MODIFIER
```
+
- Using lower case modifier:
```yaml
- Input:
+ Input:
Output: static string with a modifier
```
+
- Using title case modifier:
```yaml
- Input:
+ Input:
Output: Static String With A Modifier
```
+
- Chaining multiple modifiers:
```yaml
- Input:
+ Input:
Output: static string with a modifier
```
+
- Using modifiers with functions:
```yaml
- Input: ) | upper>
+ Input: <@generateRandomString(<30>) | upper>
Output: 7A14C8E74BC98A0D74253B1D1A4EF6
-
- Input: , ) | lower>)>
+
+ Input: <@setVar(, <@generateRandomString(<10>) | lower>)>
Output: h73ep149sd
```
+
:::tip Using a space before the pipe separator
As you can see above, unlike the case of the string expression, using a space before the `|` separator in a function expression doesn't add an additional space character to the result.
:::
+
----------------------------------------
# References > Import Yaml > Type List
+
This is a list of all supported service types that can be used in import yaml configuration file.
+
:::note
Versions listed on the same line are aliases of the same underlying version.
:::
+
## Available service types
+
### Static Services
-
- Service Type
- Versions
-
- Nginx
-
- Static
-
+
+
-# References > Import
+### Runtime services
-The Zerops YAML configuration provides powerful capabilities for both importing and exporting projects and services. This documentation covers how to define your infrastructure as code and move configurations between environments.
-## YAML Configuration Basics
-The Zerops YAML configuration can be used to create or replicate services in Zerops. You can import configurations in two ways:
-- **Using the GUI**:
- - **For projects**: In the Zerops dashboard, click on **Import a project** in the Projects section
- - **For services**: Navigate to a project's details page and click **Import services** in the services section
-- **Using the [CLI](/references/cli)**: Run `zcli project project-import` for projects or `zcli project service-import` for individual services
-Both methods provide straightforward ways to migrate or replicate infrastructure as needed.
-This section provides a comprehensive example of an import YAML configuration file, allowing you to define and import a project and its services with environment variables.
-```yaml
-# ==== Define a project to import ====
-project:
- # REQUIRED. Name of your project
- name: project0
- # Project description
- description: "This project is an example only"
- # Project core package - LIGHT/SERIOUS
- corePackage: SERIOUS
- # List of project tags for filtering
- tags:
+
+
+
+----------------------------------------
+
+# References > Import
+
+
+The Zerops YAML configuration provides powerful capabilities for both importing and exporting projects and services. This documentation covers how to define your infrastructure as code and move configurations between environments.
+
+## YAML Configuration Basics
+
+The Zerops YAML configuration can be used to create or replicate services in Zerops. You can import configurations in two ways:
+
+- **Using the GUI**:
+ - **For projects**: In the Zerops dashboard, click on **Import a project** in the Projects section
+ - **For services**: Navigate to a project's details page and click **Import services** in the services section
+- **Using the [CLI](/references/cli)**: Run `zcli project project-import` for projects or `zcli project service-import` for individual services
+
+Both methods provide straightforward ways to migrate or replicate infrastructure as needed.
+
+#### Comprehensive example of an import YAML configuration
+
+This section provides a comprehensive example of an import YAML configuration file, allowing you to define and import a project and its services with environment variables.
+
+```yaml
+# ==== Define a project to import ====
+project:
+ # REQUIRED. Name of your project
+ name: project0
+ # Project description
+ description: "This project is an example only"
+ # Project core package - LIGHT/SERIOUS
+ corePackage: SERIOUS
+ # List of project tags for filtering
+ tags:
- test
- dev
# Project-level environment variables
@@ -21411,10 +30775,10 @@ services:
mode: HA
# Map of secret environment variables
envSecrets:
- SECRET_KEY: )>
+ SECRET_KEY: <@generateRandomString(<32>)>
# Environment variables defined in .env format (automatically creates secret envs)
dotEnvSecrets: |
- APP_KEY=)>
+ APP_KEY=<@generateRandomString(<32>)>
DB_PASSWORD=secure123
# Object storage size in GB
objectStorageSize: 2
@@ -21455,11 +30819,14 @@ services:
server {
listen 80 default_server;
listen [::]:80 default_server;
+
server_name _;
root /var/www;
+
location / {
try_files $uri $uri/ /index.html;
}
+
access_log syslog:server=unix:/dev/log,facility=local1 default_short;
error_log syslog:server=unix:/dev/log,facility=local1;
}
@@ -21486,49 +30853,70 @@ services:
type: shared-storage
...
```
+
:::note
The example above is a general guideline; not all keys are valid for every service type. For technology-specific details, refer to the **Create service** page in the **How To** section of the Zerops documentation.
+
- `REQUIRED.` If a parent object is defined, the key-value pair is required to be filled. All other key-value pairs are optional.
:::
+
## Project Configuration
+
The project configuration is used to define the project you want to import.
+
### Usage
-
- Field
- Type
- Description
-
- project
- object
- _REQUIRED, if a whole project is imported_
-Only one project can be defined.
-
- name
- string, REQUIRED
- The name of the new project. Duplicates are allowed.
-
- description
- string
- Description of the new project.
-
- corePackage
- string
- [Core package](/features/infrastructure#project-core-options) of the new project.
-Values: LIGHT/SERIOUS (default LIGHT)
-
- tags
- list of strings
- One or more string tags.
-Tags provide better orientation in projects.
-
- envVariables
- map[string]string
- [Project-level environment variables](/features/env-variables#project-variables) that are available to all services in the project.
-
+
+
+
+
+
Field
+
Type
+
Description
+
+
+
+
+
project
+
object
+
_REQUIRED, if a whole project is imported_
+Only one project can be defined.
+
+
+
name
+
string, REQUIRED
+
The name of the new project. Duplicates are allowed.
+
+
+
description
+
string
+
Description of the new project.
+
+
+
corePackage
+
string
+
[Core package](/features/infrastructure#project-core-options) of the new project.
+Values: LIGHT/SERIOUS (default LIGHT)
+
+
+
tags
+
list of strings
+
One or more string tags.
+Tags provide better orientation in projects.
+
+
+
envVariables
+
map[string]string
+
[Project-level environment variables](/features/env-variables#project-variables) that are available to all services in the project.
+
+
+
+
:::important
The `corePackage` value can be upgraded later from Lightweight to Serious Core, but cannot be downgraded. Upgrades involve a brief service disruption and are partially destructive (logs/statistics are lost). Make sure to choose a suitable core package for your project. Learn more about [core upgrade process](/features/infrastructure#project-core-upgrade).
:::
+
This example will create a project named `project0` with [serious core](/features/infrastructure#serious-core) package and the description `This project is an example only`. The project will have two tags: `test` and `dev`, and two environment variables: `LOG_LEVEL` and `API_VERSION`:
+
```yaml
# ==== Define a project to import ====
project:
@@ -21547,8 +30935,11 @@ project:
LOG_LEVEL: info
API_VERSION: v1
```
+
## Service Configuration
+
The service configuration defines one or more services to import into your project. Services are specified as an array under the `services` key, allowing you to configure multiple services in a single YAML file. You need at least one service and either an existing project to import into or a project defined in the YAML file.
+
The Service Configuration section is divided into multiple subsections for better organization:
- [**Service Basic Configuration**](#service-basic-configuration) - Core parameters like hostname, type, mode, and environment variables
- [**Service Vertical Autoscaling**](#service-vertical-autoscaling) - CPU, RAM, and disk scaling settings
@@ -21556,17 +30947,22 @@ The Service Configuration section is divided into multiple subsections for bette
- [**Service Mount Shared Storage**](#service-mount-shared-storage) - Connecting to shared storage services
- [**Service Nginx Configuration**](#service-nginx-configuration) - Custom web server settings
- [**Service zerops.yaml Configuration**](#service-zeropsyaml-configuration) - Build and run configurations
+
+#### Complete Service Configuration Example
+
```yaml
#yamlPreprocessor=on
services:
- hostname: app # REQUIRED: Unique service identifier
type: nodejs@22 # REQUIRED: Service type and version
mode: HA # HA or NON_HA mode (default: NON_HA)
+
# Environment variables
envSecrets: # Secret environment variables (blurred in GUI)
- SECRET_KEY: )> # Generated random string
+ SECRET_KEY: <@generateRandomString(<32>)> # Generated random string
dotEnvSecrets: | # Environment vars in .env format
- APP_KEY=)>
+ APP_KEY=<@generateRandomString(<32>)>
+
# Storage configuration
objectStorageSize: 2 # Object storage size in GB
objectStoragePolicy: public-read-write # Predefined S3 bucket policy
@@ -21583,11 +30979,13 @@ services:
}
]
}
+
# Build and deployment
buildFromGit: https://github.com/myorg/myapp # Git repo for one-time build
enableSubdomainAccess: true # Enable public access via Zerops subdomain
priority: 1 # Higher priority services are created sooner
override: true # When true, triggers redeploy of existing service
+
# Vertical autoscaling
verticalAutoscaling:
minCpu: 1 # Minimum number of virtual CPUs
@@ -21602,12 +31000,15 @@ services:
minFreeCpuPercent: 20 # Min free CPU percentage before scaling
minFreeRamGB: 0.5 # Min free RAM in GB before scaling
minFreeRamPercent: 20 # Min free RAM percentage before scaling
+
# Horizontal autoscaling
minContainers: 2 # Minimum number of containers (default: 1, max: 10)
maxContainers: 6 # Maximum number of containers (max: 10)
+
# Shared storage
mount: # List of shared storage services to mount
- teststorage1
+
# Nginx configuration
nginxConfig: |- # Custom nginx configuration
server {
@@ -21615,12 +31016,15 @@ services:
listen [::]:80 default_server;
server_name _;
root /var/www/public;
+
location / {
try_files $uri $uri/ /index.html;
}
+
access_log syslog:server=unix:/dev/log,facility=local1 default_short;
error_log syslog:server=unix:/dev/log,facility=local1;
}
+
# Zerops.yaml configuration
zeropsSetup: backendapi # Service setup name from zeropsYaml or repo
zeropsYaml: # Full zerops.yaml configuration
@@ -21637,85 +31041,121 @@ services:
initCommands:
- npm run db:migrate
start: npm start
+
# A second, simpler service example
- hostname: teststorage1
type: shared-storage
```
+
This example includes all possible configuration options for Zerops services. Not all options are required or applicable to every service type. The example shows two services in the same YAML file: a fully configured Node.js API service and a simpler static frontend service.
+
### Service Basic Configuration
-
- Field
- Type
- Description
-
- services
- list of objects, REQUIRED
- At least one service is required.
-
- hostname
- string, REQUIRED
-
+
+
+
+
+
Field
+
Type
+
Description
+
+
+
+
+
services
+
list of objects, REQUIRED
+
At least one service is required.
+
+
+
hostname
+
string, REQUIRED
+
The unique service identifier.
Limitations:
- duplicates in the same project forbidden
- maximum 25 characters, lowercase ASCII letters (a-z) or numbers (0-9) only
-
- type
- enum, REQUIRED
- Specifies the service type and version. See [supported types](/references/import-yaml/type-list).
-
- mode
- enum
- Values: HA / NON_HA (default NON_HA)
-Defines the operation mode of the service.
-
- envSecrets
- map[string]string
- Environment variables that are blurred by default in Zerops GUI. Can be edited or deleted in Zerops GUI.
-
- dotEnvSecrets
- string (multiline)
- Environment variables in .env file format that are automatically created as secret envs.
-
- objectStorageSize
- integer
- Object storage size in GB.
-
- objectStoragePolicy
- enum
-
+
+
+
+
type
+
enum, REQUIRED
+
Specifies the service type and version. See [supported types](/references/import-yaml/type-list).
+
+
+
mode
+
enum
+
Values: HA / NON_HA (default NON_HA)
+Defines the operation mode of the service.
+
+
+
envSecrets
+
map[string]string
+
Environment variables that are blurred by default in Zerops GUI. Can be edited or deleted in Zerops GUI.
+
+
+
dotEnvSecrets
+
string (multiline)
+
Environment variables in .env file format that are automatically created as secret envs.
Define your own AWS S3 bucket access policy. See [AWS docs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html) for details.
Use `{{ .BucketName }}` placeholder if you need to use bucket name in your custom policy rules.
-
- buildFromGit
- string (URL)
-
+
+
+
+
buildFromGit
+
string (URL)
+
A URL of a Github or Gitlab repository used for a one-time build of your service.
-
- enableSubdomainAccess
- boolean
-
+
+
+
+
enableSubdomainAccess
+
boolean
+
Default: `false`
+
Set `true`, if you want to enable a public access to your service via a Zerops subdomain. Not suitable for production.
-
- priority
- integer
-
+
+
+
+
priority
+
integer
+
Services are sorted before creation by priority in descending order, i.e. the higher the priority the sooner the service is created.
-
- override
- boolean
-
+
+
+
+
override
+
boolean
+
Default: `false`
+
This only works for **runtime** services.
+
The parameter allows you to replace an existing runtime service with the same hostname byt triggering a redeploy if the service already exists.
-
+
+
+
+
+
+#### Service Basic Configuration Example
+
```yaml
#yamlPreprocessor=on
services:
@@ -21727,10 +31167,10 @@ services:
mode: HA
# Map of secret environment variables
envSecrets:
- SECRET_KEY: )>
+ SECRET_KEY: <@generateRandomString(<32>)>
# Environment variables in .env format
dotEnvSecrets: |
- APP_KEY=)>
+ APP_KEY=<@generateRandomString(<32>)>
# Object storage size in GB
objectStorageSize: 2
# Choose object storage policy from a predefined list
@@ -21746,6 +31186,7 @@ services:
# When set to true, triggers a redeploy of an existing runtime service with the same hostname
override: false
```
+
This yaml will create a `nodejs@latest` service named `app` in `HA` (High-Availability) mode with the following configurations:
- Environment variables:
- From `envSecrets`: `SECRET_KEY` (requires yamlPreprocessor)
@@ -21755,77 +31196,112 @@ This yaml will create a `nodejs@latest` service named `app` in `HA` (High-Availa
- Public access enabled via Zerops subdomain
- Priority: 1
- Override existing service: `false`
+
The `services` object allows you to define one or more services in the same yaml file.
+
:::caution
The `yamlPreprocessor` option in your project & service import YAML is required to generate random secret values, passwords, and public/private key pairs. For more information, see the [yamlPreprocessor](/references/import-yaml/pre-processor) page.
:::
+
### Service Vertical Autoscaling
+
The vertical autoscaling configuration defines how the service can scale its resources vertically.
-
- Field
- Type
- Description
-
- minCpu
- integer
- Minimum number of virtual CPUs
-
- maxCpu
- integer
- Maximum number of virtual CPUs
-
- cpuMode
- enum
- Values: **SHARED / DEDICATED**
-
- minRam
- float
-
+
+
+
+
+
Field
+
Type
+
Description
+
+
+
+
+
minCpu
+
integer
+
Minimum number of virtual CPUs
+
+
+
maxCpu
+
integer
+
Maximum number of virtual CPUs
+
+
+
cpuMode
+
enum
+
Values: **SHARED / DEDICATED**
+
+
+
minRam
+
float
+
Minimum RAM in GB that each container of the service can scale down to.
-
- maxRam
- float
-
+
+
+
+
maxRam
+
float
+
Maximum RAM in GB that each container of the service can scale up to.
-
- minDisk
- float
-
+
+
+
+
minDisk
+
float
+
Minimum disk space in GB that each container of the service can scale down to.
-
- maxDisk
- float
-
+
+
+
+
maxDisk
+
float
+
Maximum disk space in GB that each container of the service can scale up to.
-
- startCpuCoreCount
- integer
-
+
+
+
+
startCpuCoreCount
+
integer
+
Number of CPU cores with which each container starts.
-
- minFreeCpuCores
- float
-
+
+
+
+
minFreeCpuCores
+
float
+
Minimum number of unused CPU cores before a container starts scaling.
-
- minFreeCpuPercent
- float
-
+
+
+
+
minFreeCpuPercent
+
float
+
Minimum percentage of unused CPU cores before a container starts scaling.
-
- minFreeRamGB
- float
-
+
+
+
+
minFreeRamGB
+
float
+
Minimum unused memory in GB before a container starts scaling.
-
- minFreeRamPercent
- float
-
+
+
+
+
minFreeRamPercent
+
float
+
Minimum percentage of unused memory before a container starts scaling.
-
-```yaml
-services:
- - hostname: app
+
+
+
+
+
+#### Vertical Autoscaling Configuration Example
+
+```yaml
+services:
+ - hostname: app
type: nodejs@22
buildFromGit: https://github.com/myorg/myapp
enableSubdomainAccess: true
@@ -21843,25 +31319,41 @@ services:
minFreeRamGB: 0.5 # Min free RAM in GB before scaling
minFreeRamPercent: 20 # Min free RAM percentage before scaling
```
+
This yaml will create a service with the hostname `app` with `php-nginx@8.4` runtime with `HA` High-Availability mode for vertical autoscaling:
+
- CPU: `1-3` virtual CPUs in `DEDICATED` mode
- RAM: `1-4 GB`
- Disk Space: `1-10 GB`
+
### Service Horizontal Autoscaling
+
The horizontal autoscaling configuration is used to define the horizontal autoscaling settings for the service.
-
- Field
- Type
- Description
-
- minContainers
- integer
- Minimum number of containers of the service.
-Default: 1, maximum value: 10
- maxContainers
- integer
- Maximum number of containers of the service.
-Maximum value: 10
+
+
+
+
+
Field
+
Type
+
Description
+
+
+
+
+
minContainers
+
integer
+
Minimum number of containers of the service.
+Default: 1, maximum value: 10
+
+
+
maxContainers
+
integer
+
Maximum number of containers of the service.
+Maximum value: 10
+
+
+
+
```yaml
services:
- hostname: app
@@ -21873,18 +31365,30 @@ services:
# Maximum number of containers
maxContainers: 6
```
+
The `minContainers` and `maxContainers` parameters allow you to define the minimum and maximum number of containers for the service. The service will automatically scale between these values as needed.
+
### Service Mount Shared Storage
+
The mount shared storage configuration defines which shared storage services should be mounted to the service.
-
- Field
- Type
- Description
-
- mount
- list of strings
- Mount shared storage to the service. `buildFromGit` must be filled.
-
+
+
+
+
+
Field
+
Type
+
Description
+
+
+
+
+
mount
+
list of strings
+
Mount shared storage to the service. `buildFromGit` must be filled.
+
+
+
+
```yaml
services:
- hostname: app
@@ -21894,18 +31398,30 @@ services:
mount:
- teststorage1
```
+
The `mount:` parameter allows you to mount a shared storage (which should be created inside the project) to the service.
+
### Service Nginx Configuration
+
The nginx configuration defines the nginx settings for the service.
-
- Field
- Type
- Description
-
- nginxConfig
- string (multiline)
- Insert full nginx config.
-
+
+
+
+
+
Field
+
Type
+
Description
+
+
+
+
+
nginxConfig
+
string (multiline)
+
Insert full nginx config.
+
+
+
+
```yaml
#yamlPreprocessor=on
services:
@@ -21916,31 +31432,47 @@ services:
server {
listen 80 default_server;
listen [::]:80 default_server;
+
server_name _;
root /var/www;
+
location / {
try_files $uri $uri/ /index.html;
}
+
access_log syslog:server=unix:/dev/log,facility=local1 default_short;
error_log syslog:server=unix:/dev/log,facility=local1;
}
```
+
The `nginxConfig: |-` parameter allows you to specify a custom nginx configuration for the service.
+
### Service zerops.yaml Configuration
+
The `zeropsSetup` and `zeropsYaml` parameters provide flexibility in how you define and use your service configurations. Both parameters are optional and work together in the following ways:
-
- Field
- Type
- Description
-
- zeropsSetup
- string
- Specifies which service setup to use. This should match a setup name found in either the `zeropsYaml` parameter (if provided) or the `zerops.yaml` file in the repository root. If not specified, defaults to the service hostname.
-
- zeropsYaml
- object
- Contains the full [zerops.yaml configuration](/zerops-yaml/specification). If provided, this will be used instead of looking for a `zerops.yaml` file in the repository.
-
+
+
+
+
+
Field
+
Type
+
Description
+
+
+
+
+
zeropsSetup
+
string
+
Specifies which service setup to use. This should match a setup name found in either the `zeropsYaml` parameter (if provided) or the `zerops.yaml` file in the repository root. If not specified, defaults to the service hostname.
+
+
+
zeropsYaml
+
object
+
Contains the full [zerops.yaml configuration](/zerops-yaml/specification). If provided, this will be used instead of looking for a `zerops.yaml` file in the repository.
+
+
+
+
```yaml
services:
- hostname: app
@@ -21964,7 +31496,9 @@ services:
- npm run db:migrate
start: npm start
```
+
#### How They Work Together
+
- **Neither parameter specified**:
- The system looks for a `zerops.yaml` file in the repository root
- It searches for a setup with a name that matches the service hostname
@@ -21976,59 +31510,86 @@ services:
- **Both parameters specified**:
- The system uses the provided `zeropsYaml` configuration
- It specifically looks for the setup named in `zeropsSetup` within that YAML
+
If the specified `zeropsSetup` does not exist in the available YAML configuration (either provided in `zeropsYaml` or found in the repository), the import will fail.
+
## Export
+
Zerops provides the ability to export your existing projects and services as YAML configurations through the GUI. This feature is particularly useful for:
- Creating backups of your project configurations
- Replicating project or service setups across different environments
- Sharing project templates with team members
- Creating version-controlled infrastructure configurations
+
The exported YAML follows the same structure as the import YAML configuration detailed above. It will contain all the configuration parameters you've set for your project and services.
+
### How to Export
+
#### Exporting a Single Service
Navigate to your service dashboard in the Zerops GUI, click the three-dot menu (⋮) in the top-right corner of the service card, and choose **Export service as yaml**.
+
#### Exporting an Entire Project
In the Zerops GUI, go to the project dashboard, click the three-dot menu (⋮) in the top-right corner of the project card, and select **Export project as yaml**.
+
### Using Exported Configurations
+
The exported YAML files are compatible with:
- The Zerops GUI import functionality
- The `zcli project project-import` command
- The `zcli project service-import` command (for single service exports)
+
This allows you to easily move configurations between environments or create new instances of your infrastructure.
----------------------------------------
# References > Log Forwarding
+
For more advanced [log](/references/logging) analysis and centralized logging, you can forward all your Zerops logs to external logging services. The Zerops logger service uses **syslog-ng** to enable this functionality.
+
## Ready-Made Configurations
+
Zerops provides pre-configured setups for popular logging services:
+
- **[Better Stack](https://betterstack.com/)**
- **[Papertrail](https://www.papertrail.com/)**
- **Self-hosted [ELK Stack](https://www.elastic.co/elastic-stack) (Logstash)**
+
To set up one of these integrations, go to your project detail, select **Advanced Observability**, choose your preferred service, and follow the guided steps in the interface.
+
## Self-Hosted Logstash
+
To collect logs in a self-hosted ELK stack, a Logstash instance (deployed as the `logstash` service) is required. Logstash listens for incoming UDP syslog packets and indexes them to Elasticsearch.
+
The one-click GUI integration setup is all you need to get started. After setup completes, logs will appear in Kibana's "Logs > Explorer" section. You can find access information in the **Advanced Observability** section of your project in the GUI.
+
:::warning
Setting up log forwarding to ELK will override any previously configured log forwarding.
:::
+
### What Happens Behind the Scenes
+
1. The `elkstorage`, `kibana`, and `logstash` services are deployed and configured in the target project (if not already present)
2. If logging is required across different projects, the `logstash` service is made publicly accessible through port routing with firewall whitelisting for source project IPs
3. Log forwarding is configured on source projects to forward logs to the target Logstash instance
+
:::tip
For the complete ELK stack setup including tracing capabilities, see the [Self-Hosted Observability](/references/metrics) guide.
:::
+
## Custom Log Forwarding Configuration
+
You can set up forwarding to any syslog-ng compatible software. To do this, navigate to your project detail's **Advanced Observability** section, and choose the "Setup forwarding to any syslog-ng compatible software" option.
+
When configuring your custom syslog-ng setup, note the following important details:
+
### Certificate Configuration
- Certificates are located in `/etc/ssl/certs`
- If your configuration references `/etc/syslog-ng/ca.d` or `/etc/syslog-ng/cert.d`, change these paths to `/etc/ssl/certs`
- For custom certificates, you can use: `ca-file("/etc/syslog-ng/user.crt")`
- You can combine custom certificates with standard certificates using: `ca-dir("/etc/ssl/certs")`
(This will verify both your custom certificate and standard certificates like those from LetsEncrypt)
+
### Source Configuration
- Zerops uses `s_src` as the source configuration name
- This differs from Papertrail, which might instruct you to "replace 's_sys' with the name you found" - in Zerops, always use `s_src` instead
@@ -22037,60 +31598,91 @@ When configuring your custom syslog-ng setup, note the following important detai
# References > Logging
+
Zerops automatically collects logs from all services in your project through a built-in logger service. These logs include runtime operations, database activities, build processes, and more.
+
## Project-Wide Logs
+
To view all project logs, navigate to your project detail and select the **Logs overview** section, where you'll find a consolidated view of all logging activity from all services with multiple filtering options.
+
Additionally, in the **Advanced Observability** section, you can set up [log forwarding](/references/log-forwarding) to external logging services for more advanced analysis and long-term storage.
+
## Service-Specific Logs
+
Zerops provides different log types depending on the service:
+
### Build Logs
Shows the output from your build process:
- **GUI**: Service detail → **Pipelines & CI/CD settings** section → Pipeline detail → Build log
-- **CLI**: zcli service log --showBuildLogs
+- **CLI**: [`zcli service log --showBuildLogs`](/references/zcli/commands#service-log)
+
:::note
The build log button is available only when the [build pipeline](/features/pipeline#build-phase) was triggered for the selected deploy.
:::
+
### Prepare Runtime Logs
Documents the creation of a custom runtime image:
- **GUI**: Service detail → **Pipelines & CI/CD settings** section → Pipeline detail → Prepare runtime log
- **CLI**: *Not currently supported*
+
:::note
The prepare runtime log button is available only when the [prepare runtime phase](/features/pipeline#runtime-prepare-phase-optional) was triggered for the selected deploy.
:::
+
### Runtime/Database Logs
Contains the operational output from your service.
+
- **GUI**:
- Runtime services: Service detail → **Runtime logs**
- Database services: Service detail → **Database logs**
-- **CLI**: zcli service log
+- **CLI**: [`zcli service log`](/references/zcli/commands#service-log)
+
:::note
Each container has its own log. For services with multiple containers, select the specific container in the header. You can filter logs by severity level or time period.
+
To view logs from all containers of a service combined, you can either use the Project logs view or click the **Go to full service log** button in the service detail page.
:::
+
:::important
For severity levels to work properly in Zerops, your application must log to syslog.
:::
+
----------------------------------------
# References > Metrics
+
Zerops Advanced Observability provides one-click, self-hosted, pre-configured deployments of the **[ELK stack](#elk-stack)** or **[Prometheus with Grafana](#prometheus-with-grafana)**. This enables comprehensive observability for your deployments while maintaining full control over your data and infrastructure.
+
## Deployment Modes
+
Both ELK and Prometheus can be deployed in two ways:
+
- **Local deployment**: Services are deployed within your target project
- **Global deployment**: A dedicated project is created specifically for observability
+
## ELK Stack
+
The ELK observability setup deploys and configures two base services:
+
- **Elasticsearch** (as `elkstorage`)
- **Kibana** (as `kibana`) - the observability access point
+
### Logging
+
For log collection with ELK, see the [Log Forwarding](/references/log-forwarding#self-hosted-logstash) guide which covers the Logstash setup and configuration.
+
### Tracing
+
To collect traces in the ELK stack, an APM Server instance (deployed as the `apmserver` service) is required. APM Server listens for incoming traces securely over HTTPS and indexes them to Elasticsearch.
+
First, follow the one-click GUI integration setup to deploy the required infrastructure. Then configure your application to send traces to APM Server.
+
#### Setting Up APM Agents
+
1. Update your code according to the [APM documentation](https://www.elastic.co/guide/en/apm/agent/index.html) for your application's language. See this [simple Go application](https://github.com/zerops-recipe-apps/go-hello-world-app/tree/with-apm-and-metrics) using APM libraries for reference.
+
2. Add the following environment variables to your application service (these are specific to the official Go APM Agent library and may differ for other agents):
```
ELASTIC_APM_ACTIVE=true
@@ -22098,63 +31690,96 @@ ELASTIC_APM_SERVICE_NAME=recipe-go
ELASTIC_APM_SERVER_URL=https://apmserver.url.copy.from.gui
ELASTIC_APM_SECRET_TOKEN=secret_token_copy_from_gui
```
+
:::note
The `ELASTIC_APM_ACTIVE` variable is set to `false` by default on Zerops, so you must explicitly set it to `true` to enable APM for the official Go APM agent.
:::
+
3. Restart or reload your application service.
+
You should start seeing traces appear in Kibana's "Applications > Traces" section.
+
#### What Happens Behind the Scenes
+
1. The `elkstorage`, `kibana`, and `apmserver` services are deployed and configured in the target project (if not already present)
2. The `apmserver` is made publicly accessible over HTTPS via a Zerops subdomain and configured with a secret token for secure access
+
Access information for both Kibana and APM Server can be found in the **Advanced Observability** section of your project in the GUI.
+
### Next Steps
+
- **Security**: Set up custom domains for Kibana and APM Server
- **Optimization**: Connect to APM Server locally via HTTP for improved performance
- **Customization**: Fork the [ELK recipe](https://github.com/zeropsio/recipe-elk), customize the Logstash configuration, and redeploy the `logstash` service via `zcli`
+
## Prometheus with Grafana
+
The full Prometheus setup consists of:
+
- **Prometheus** (as `prometheus`)
- **Grafana** (as `grafana`) - the observability access point
- **PostgreSQL database** (as `grafanadb`) - for Grafana data storage
- **S3 bucket** (as `prometheusbackups`) - for storing Prometheus backups
+
Metrics can be forwarded to the target project via a Prometheus exporter (single `prometheuslight` service configured [with remote write](https://grafana.com/docs/agent/latest/flow/reference/components/prometheus.remote_write/#prometheusremote_write)). When present in a source project, it collects metrics and forwards them to Prometheus in the target project.
+
Since Prometheus supports only filesystem storage and non-HA (single instance) setup, the `prometheus` service is configured to run a backup cron job that stores metric data snapshots in object storage.
+
### Metrics
+
After deploying the full or forwarder Prometheus setup, metrics are automatically scraped by Prometheus. After setup completes, log in to Grafana using the credentials found in the **Advanced Observability** section of your project in the GUI, then navigate to `/dashboards` to start exploring your metrics.
+
Zerops provides several metrics out of the box:
+
- Service scaling and resource metrics
- PostgreSQL database service metrics (with HAProxy balancer metrics in HA setups)
- MariaDB database service metrics
- Valkey database metrics
+
:::note
Some PostgreSQL database metrics are available only after enabling the `pg_stat_statements` extension. Run `CREATE EXTENSION IF NOT EXISTS pg_stat_statements;` as a superuser and restart the database service.
:::
+
You can also expose custom metrics from your applications.
+
#### Exposing Custom Metrics
+
1. Configure your application to expose an HTTP `/metrics` endpoint on an arbitrary port. See this [simple Go application using `promauto`](https://github.com/zerops-recipe-apps/go-hello-world-app/tree/with-apm-and-metrics) for reference.
+
:::note
Only the `/metrics` path is scraped and cannot currently be configured otherwise.
:::
+
2. Add and commit the `ZEROPS_PROMETHEUS_PORT` environment variable to your application service with the port where you exposed the `/metrics` endpoint:
```
Single port:
9090
+
Multiple ports can be defined using commas:
9090,9091
```
+
For example: `ZEROPS_PROMETHEUS_PORT=9090`. After setting the environment variable, your service's ports will be automatically added to metrics discovery and scraped by Prometheus.
+
#### What Happens Behind the Scenes
+
**Full setup:**
+
1. The `prometheus`, `grafana`, `grafanadb`, and `prometheusbackups` services are deployed and configured (if not already present)
2. `grafana` is made publicly accessible over HTTPS, securely accessible via a generated password
+
After that, metrics are scraped and available for visualization in Grafana.
+
**Forwarder setup:**
+
1. The `prometheuslight` forwarder service is deployed in the source project
2. The `prometheus`, `grafana`, `grafanadb`, and `prometheusbackups` services are deployed and configured in the target project (if not already present)
3. `grafana` is made publicly accessible over HTTPS, securely accessible via a generated password
4. `prometheus` is made publicly accessible over HTTPS via a Zerops zone domain and secured with basic access authentication (username and password)
5. `prometheuslight` is configured to forward metrics to the target `prometheus` using the generated credentials over secure HTTPS
+
### Next Steps
+
- **Security**: Set up custom domains for Grafana and Prometheus
- **Customization**: Fork the [Prometheus recipe](https://github.com/zeropsio/recipe-prometheus), customize dashboards and alerting rules, and redeploy via `zcli`
- **Advanced monitoring**: Explore Grafana's alerting capabilities and create custom dashboards for your specific use cases
@@ -22163,155 +31788,211 @@ After that, metrics are scraped and available for visualization in Grafana.
# References > Networking > Cloudflare
+
This guide provides step-by-step instructions for configuring Cloudflare to work with your Zerops applications, covering DNS records, proxy settings, SSL/TLS configuration, and common troubleshooting scenarios.
+
## Prerequisites
+
Before starting, ensure you have:
- A Cloudflare account
- A registered domain name
- Access to your Zerops project with [domain access configured](/references/networking/public-access#custom-domain-access)
- Your Zerops IP addresses (IPv4 and/or IPv6) from the Zerops GUI
+
## DNS Record Configuration
+
Configure your DNS records in Cloudflare using one of these approaches based on your needs:
+
### Using CNAME Records
+
CNAME can be used for non-apex domains (subdomains) or with DNS providers that support CNAME flattening at the apex (like Cloudflare). When you set up a CNAME in Zerops, it internally creates A and AAAA records pointing to your project.
+
To find your CNAME target value, go to your service in the Zerops GUI, navigate to **Public access & internal ports**, and select the **CNAME** option when adding a domain.
```bash
Type Name Content Proxy status TTL
-CNAME Proxied/DNS Only Auto
+CNAME Proxied/DNS Only Auto
```
+
:::warning Cloudflare Proxy with Shared IPv4
When using Cloudflare's proxy with CNAME records, you **must exclude the shared IPv4**. Toggle off "Shared IPv4 included in the CNAME" in the Zerops GUI.
+
Zerops does a reverse lookup of the AAAA record of the domain for requests to our shared IPv4 address. If you use a shared IPv4 and also enable a proxy for the AAAA record, Zerops will not be able to correctly route the request.
+
This setting affects all domains in your project.
:::
+
### With Cloudflare Proxy
+
#### IPv6 only
```bash
Type Name Content Proxy status TTL
-AAAA Proxied Auto
+AAAA Proxied Auto
```
+
Cloudflare handles IPv4 to IPv6 translation, making your service accessible to both IPv4 and IPv6 users. Uses Zerops' free dedicated IPv6 address.
+
:::note
Do not add a proxied A record with shared IPv4 when using this setup, as it would prevent proper IPv4 traffic routing.
:::
+
#### Dedicated IPv4
```bash
Type Name Content Proxy status TTL
-A Proxied Auto
+A Proxied Auto
# Optional
-AAAA Proxied Auto
+AAAA Proxied Auto
```
+
Uses your dedicated IPv4 address with Cloudflare's proxy features.
+
:::tip
Adding the AAAA record allows visitors with IPv6 support to connect directly via IPv6.
:::
+
#### Shared IPv4 *(not recommended)*
```bash
Type Name Content Proxy status TTL
AAAA DNS only Auto
A Proxied Auto
```
+
:::tip Why Not?
Zerops does a reverse lookup of the AAAA record of the domain for requests to our shared IPv4 address. If you use a shared IPv4 and also enable a proxy for the AAAA record, Zerops will not be able to correctly route the request.
+
Consider using IPv6 only or dedicated IPv4 configurations instead.
:::
+
### DNS-Only Configuration (Without Cloudflare Proxy)
+
If you prefer direct connections without Cloudflare's proxy features:
+
#### Shared IPv4
```bash
Type Name Content Proxy status TTL
-A DNS only Auto
-AAAA DNS only Auto
+A DNS only Auto
+AAAA DNS only Auto
```
+
Uses Zerops' free shared IPv4.
+
:::note Both A + AAAA Required
Adding AAAA record is essential for shared IPv4 configuration as it serves as a [security measure](/references/networking/dns#understand-shared-ipv4) to prevent unauthorized domain claims.
:::
+
#### Dedicated IPv4
```bash
Type Name Content Proxy status TTL
-A DNS only Auto
+A DNS only Auto
# Optional
-AAAA DNS only Auto
+AAAA DNS only Auto
```
+
Uses your dedicated IPv4 address.
:::tip
Adding the AAAA record allows visitors with IPv6 support to connect directly via IPv6.
:::
+
#### IPv6 only
```bash
Type Name Content Proxy status TTL
-AAAA DNS only Auto
+AAAA DNS only Auto
```
+
Uses only Zerops' free dedicated IPv6.
:::note
This configuration will only work for users with IPv6 connectivity.
:::
+
## Wildcard Domain Configuration
-Zerops supports wildcard domains (`*.`) that allow routing all subdomains to your project.
+
+Zerops supports wildcard domains (`*.`) that allow routing all subdomains to your project.
+
### DNS Records for Wildcards
+
Configure wildcard domains using either method:
+
#### Method A: Direct Wildcard Records
```bash
Type Name Content Proxy status TTL
-A *. DNS only/Proxied Auto
-AAAA *. DNS only/Proxied Auto
+A *. DNS only/Proxied Auto
+AAAA *. DNS only/Proxied Auto
```
+
#### Method B: CNAME to Main Domain
First ensure your main domain has proper A/AAAA records, then add:
```bash
Type Name Content Proxy status TTL
-CNAME *. DNS only/Proxied Auto
+CNAME *. DNS only/Proxied Auto
```
+
### Certificate Validation for Wildcards
+
To enable automatic SSL certificate issuance for wildcard domains:
+
```bash
Type Name Content Proxy status TTL
-CNAME _acme-challenge. .zerops.zone DNS only Auto
+CNAME _acme-challenge..zerops.zone DNS only Auto
```
+
This CNAME record allows Zerops to handle the DNS-01 challenge required for wildcard SSL certificates.
+
### Higher-Level Wildcard Subdomains
-You can also set up higher-level wildcard subdomains like `*..`:
+
+You can also set up higher-level wildcard subdomains like `*..`:
+
#### Method A: Direct Configuration
```bash
Type Name Content Proxy status TTL
-A *.. DNS only/Proxied Auto
-AAAA *.. DNS only/Proxied Auto
+A *.. DNS only/Proxied Auto
+AAAA *.. DNS only/Proxied Auto
```
+
#### Method B: Using a CNAME Record
```bash
Type Name Content Proxy status TTL
-CNAME *.. . DNS only/Proxied Auto
+CNAME *... DNS only/Proxied Auto
```
or
```bash
Type Name Content Proxy status TTL
-CNAME *.. DNS only/Proxied Auto
+CNAME *.. DNS only/Proxied Auto
```
+
For certificate validation with higher-level wildcards:
```bash
Type Name Content Proxy status TTL
-CNAME _acme-challenge.. ..zerops.zone DNS only Auto
+CNAME _acme-challenge....zerops.zone DNS only Auto
```
+
### Combining Main Domain and Wildcard Domain
-To use both `` and `*.`, specify both variants in your [Zerops configuration](/references/networking/public-access#http-routing-setup). Zerops automatically issues a single shared certificate for both the main domain and all its subdomains.
+
+To use both `` and `*.`, specify both variants in your [Zerops configuration](/references/networking/public-access#http-routing-setup). Zerops automatically issues a single shared certificate for both the main domain and all its subdomains.
+
## Cloudflare SSL/TLS Configuration
+
### Essential SSL/TLS Settings
+
1. **Set Encryption Mode**
- Navigate to **SSL/TLS** → **Overview** in your Cloudflare dashboard
- Select **Full (strict)** for production or **Full** for testing
- **Never use Flexible mode** - this will cause redirect loops
+
2. **Edge Certificates**
- Go to **SSL/TLS** → **Edge Certificates**
- Ensure **Always Use HTTPS** is enabled for production
- Keep **Automatic HTTPS Rewrites** enabled
+
### Certificate Validation Configuration
+
For proper certificate issuance, especially with Let's Encrypt:
+
#### Option A: Simple Setup (Testing/Development)
- Temporarily disable **Always Use HTTPS** during initial certificate setup
- Re-enable after certificates are issued
+
#### Option B: Production Setup
Keep **Always Use HTTPS** enabled and create a Configuration Rule:
+
1. Go to **Rules** → **Configuration Rules**
2. Create a new rule with these settings:
- **Rule name:** "Allow ACME Challenge"
@@ -22319,60 +32000,84 @@ Keep **Always Use HTTPS** enabled and create a Configuration Rule:
- **Operator:** starts with
- **Value:** `/.well-known/acme-challenge/`
- **Action:** Disable **Automatic HTTPS Rewrites**
+
This rule allows certificate validation to work while maintaining HTTPS enforcement for all other traffic.
+
## Validation and Testing
+
### DNS Resolution Testing
```bash
# Check IPv4 resolution
-dig A
+dig A
+
# Check IPv6 resolution
-dig AAAA
+dig AAAA
+
# Check from specific DNS server
-dig @1.1.1.1
+dig @1.1.1.1
```
+
### Connectivity Testing
```bash
# Basic HTTPS test
-curl -vI https://
+curl -vI https://
+
# Test with specific subdomain (for wildcards)
-curl -vI https://api.
+curl -vI https://api.
+
# Test IPv4 specifically
-curl -4 -v https://
+curl -4 -v https://
+
# Test IPv6 specifically
-curl -6 -v https://
+curl -6 -v https://
```
+
### Cloudflare-Specific Checks
+
1. **Verify proxy status** in Cloudflare DNS dashboard (orange cloud = proxied)
2. **Check SSL/TLS mode** in SSL/TLS → Overview
3. **Confirm certificate issuance** in SSL/TLS → Edge Certificates
4. **Test redirect behavior** by accessing `http://` version of your domain
+
## Troubleshooting Common Issues
+
### SSL Certificate Problems
+
#### Too Many Redirects or SSL Errors
+
**Possible causes:**
- Incorrect SSL/TLS mode in Cloudflare
- Invalid or missing certificates
- Misconfigured HTTPS settings
+
**Solutions:**
1. Verify SSL/TLS mode is set to **Full** or **Full (strict)**, not **Flexible**
2. Check that both Zerops and Cloudflare have valid certificates
3. Ensure **Always Use HTTPS** is properly configured
4. For new domains, refresh the Cloudflare SSL/TLS page as settings may display incorrectly initially
+
#### Certificate Validation Fails for Wildcard Domains
+
**Possible causes:**
- Missing or incorrect `_acme-challenge` CNAME record
- DNS propagation not complete
- Incorrect CNAME target
+
**Solutions:**
1. Verify the `_acme-challenge` CNAME record is correctly configured
2. Ensure DNS propagation is complete (check with `dig` command)
-3. Confirm the CNAME points to `.zerops.zone`
+3. Confirm the CNAME points to `.zerops.zone`
+
#### Domain Verification Failed (DNS Warning in Zerops)
+
**Possible causes:**
- Cloudflare's WAF or security features blocking the `/.well-known/acme-challenge/` path
- Let's Encrypt HTTP-01 validation being prevented
+
**Solutions:**
+
**Option 1: Create a WAF Skip Rule (Recommended)**
+
1. Navigate to **Security** → **WAF** → **Custom rules** in Cloudflare
2. Click **Create rule** and configure:
- **Rule name:** "Allow ACME Challenge"
@@ -22383,44 +32088,58 @@ curl -6 -v https://
- **Which rules to skip:** Select all WAF components
3. Move this rule to the **top** of your Custom rules list
4. Wait a few minutes and check if the warning disappears in Zerops
+
**Option 2: Modify Existing WAF Rules**
+
1. Edit your existing WAF rule
2. Add an additional condition:
- **Field:** URI Path
- **Operator:** does not start with
- **Value:** `/.well-known/acme-challenge/`
+
:::tip CNAME Flattening and DNS Verification
Cloudflare uses CNAME flattening, which converts CNAME records to A/AAAA records in DNS responses. This is normal behavior and doesn't affect Zerops' domain verification. However, if WAF or other security features block the ACME challenge endpoint, Zerops cannot complete the HTTP-01 validation required for certificate issuance.
:::
+
### DNS Resolution Issues
+
#### Domain Not Resolving
+
**Possible causes:**
- Incorrect DNS record configuration
- DNS propagation delay
- Typos in IP addresses
+
**Solutions:**
1. Confirm DNS records are correctly configured in Cloudflare
2. Verify proxy status matches your intended setup (orange cloud = proxied)
3. Check for typos in IP addresses or CNAME targets
4. Wait for DNS propagation (typically 5-10 minutes, up to 24 hours globally)
-5. Test resolution using: `dig @1.1.1.1 `
+5. Test resolution using: `dig @1.1.1.1 `
+
#### IPv4 Traffic Not Working with IPv6-Only Setup
+
**Possible causes:**
- Cloudflare proxy disabled
- Incorrect IPv6 address
- Conflicting DNS records
+
**Solutions:**
1. Ensure Cloudflare proxy is **enabled** (orange cloud icon)
2. Verify IPv6 address is correct in AAAA record
3. Confirm no conflicting A record with shared IPv4 exists
-4. Test with: `curl -4 -v https://`
+4. Test with: `curl -4 -v https://`
+
## Security Considerations
+
- Always use **Full (strict)** SSL mode for production
- Enable **HSTS (HTTP Strict Transport Security)** in Cloudflare
- Consider enabling **Bot Fight Mode** for additional protection
- Use Cloudflare's **Firewall Rules** to block malicious traffic
- Regularly monitor SSL certificate expiration dates
+
## Getting Help
+
If you encounter issues not covered in this guide:
- Check the [general DNS configuration guide](/references/networking/dns#technical-background) for additional context
- Review your Zerops service logs for error messages
@@ -22432,177 +32151,243 @@ If you encounter issues not covered in this guide:
# References > Networking > Dns
+
This guide will show you how to configure DNS records and proxy settings to work with your Zerops applications.
+
:::important Cloudflare
If you're using Cloudflare, check out our dedicated [Cloudflare DNS Configuration Guide](/references/networking/cloudflare) for step-by-step instructions specific to Cloudflare's interface and features.
:::
+
## DNS Configuration
+
DNS records for Zerops services can be configured in two main ways:
* **With Proxy**: Routes traffic through proxy services, providing additional security and performance features (recommended for DDoS protection)
* **Without Proxy (DNS Only)**: Direct connection to your Zerops service's IP address
+
DNS allows you to set two records based on IP address type:
* **A** record for **IPv4** - Zerops offers either a free **shared** IPv4 or a paid **dedicated** IPv4
* **AAAA** record for **IPv6** - Zerops provides a free **dedicated** IPv6
+
### Using CNAME Records
+
CNAME can be used for non-apex domains (subdomains) or with DNS providers that support CNAME flattening at the apex. When you set up a CNAME in Zerops, it internally creates A and AAAA records pointing to your project.
+
To find your CNAME target value, go to your service in the Zerops GUI, navigate to **Public access & internal ports**, and select the **CNAME** option when adding a domain.
+
```
Type Name Content Proxy status TTL
-CNAME DNS only/Proxied Auto
+CNAME DNS only/Proxied Auto
```
+
:::warning Using Proxy with Shared IPv4
When using any CDN or proxy service with CNAME records, you should **exclude the shared IPv4**. Toggle off "Shared IPv4 included in the CNAME" in the Zerops GUI.
+
Zerops does a reverse lookup of the AAAA record of the domain for requests to our shared IPv4 address. If you use a shared IPv4 and also enable a proxy for the AAAA record, Zerops will not be able to correctly route the request because it sees the proxy's IP instead of your project's IPv6.
+
This setting affects all domains in your project.
:::
+
### With Proxy
+
#### IPv6 only
```bash
Type Name Content Proxy status TTL
-AAAA Proxied Auto
+AAAA Proxied Auto
```
+
:::note
Make sure your proxy service supports IPv4 to IPv6 translation for this configuration to work for **both IPv4 and IPv6** users.
+
Do not add a proxied A record with shared IPv4 - doing so would prevent the proxy from properly routing IPv4 traffic to your service.
:::
+
#### Dedicated IPv4
```bash
Type Name Content Proxy status TTL
-A Proxied Auto
+A Proxied Auto
# Optional
-AAAA Proxied Auto
+AAAA Proxied Auto
```
+
:::tip
Adding also AAAA record can be beneficial as visitors with IPv6 support will connect directly via IPv6.
:::
+
#### Shared IPv4 *(not recommended)*
```bash
Type Name Content Proxy status TTL
-AAAA DNS only Auto
-A Proxied Auto
+AAAA DNS only Auto
+A Proxied Auto
```
+
:::tip Why Not?
Zerops does a reverse lookup of the AAAA record of the domain for requests to our shared IPv4 address. If you use a shared IPv4 and also enable a proxy for the AAAA record, Zerops will not be able to correctly route the request.
+
Use [IPv6 only](#ipv6-only) or dedicated IPv4 configurations instead.
:::
+
### Without Proxy
+
#### Shared IPv4
```bash
Type Name Content Proxy status TTL
-AAAA DNS only Auto
-A DNS only Auto
+AAAA DNS only Auto
+A DNS only Auto
```
+
:::note Both A + AAAA Required
Adding AAAA record is essential for shared IPv4 configuration as it serves as a [security measure](#understand-shared-ipv4) to prevent unauthorized domain claims.
:::
+
#### Dedicated IPv4
```bash
Type Name Content Proxy status TTL
-A DNS only Auto
+A DNS only Auto
# Optional
-AAAA DNS only Auto
+AAAA DNS only Auto
```
+
:::tip
Adding also AAAA record can be beneficial as visitors with IPv6 support will connect directly via IPv6.
:::
+
#### IPv6 only
```bash
Type Name Content Proxy status TTL
-AAAA DNS only Auto
+AAAA DNS only Auto
```
+
:::note
This configuration will only work for users with IPv6 connectivity, which may limit your service accessibility.
:::
+
## Wildcard Domain Configuration
-Zerops supports wildcard domains (`*.`) that allow routing all subdomains to your project.
+
+Zerops supports wildcard domains (`*.`) that allow routing all subdomains to your project.
+
### DNS Configuration
#### Method A: Direct configuration of A and AAAA records
-Configure wildcard DNS records following the same patterns described in the [DNS Configuration](#dns-configuration) section, using `*.` in the Name field:
+Configure wildcard DNS records following the same patterns described in the [DNS Configuration](#dns-configuration) section, using `*.` in the Name field:
+
```bash
Type Name Content Proxy status TTL
-A *. DNS only/Proxied Auto
-AAAA *. DNS only/Proxied Auto
+A *. DNS only/Proxied Auto
+AAAA *. DNS only/Proxied Auto
```
+
#### Method B: Using a CNAME record
-First configure A and AAAA records for your main domain (``), then set up a CNAME record:
+First configure A and AAAA records for your main domain (``), then set up a CNAME record:
+
```bash
Type Name Content Proxy status TTL
-CNAME *. DNS only/Proxied Auto
+CNAME *. DNS only/Proxied Auto
```
+
### Certificate Validation
+
For proper HTTPS certificate functionality with wildcard domains, configure:
```bash
Type Name Content Proxy status TTL
-CNAME _acme-challenge. .zerops.zone DNS only Auto
+CNAME _acme-challenge..zerops.zone DNS only Auto
```
+
This record enables Zerops to issue and verify a wildcard certificate for your domain.
+
### Higher-Level Wildcard Subdomains
-You can also set up higher-level wildcard subdomains like `*..`:
+
+You can also set up higher-level wildcard subdomains like `*..`:
+
#### Method A: Direct configuration
```bash
Type Name Content Proxy status TTL
-A *.. DNS only/Proxied Auto
-AAAA *.. DNS only/Proxied Auto
+A *.. DNS only/Proxied Auto
+AAAA *..
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+