Apps: projects, services and deployments
Concepts
| Concept | Meaning |
|---|---|
| Project | One product of yours: its services, databases and buckets. It runs in a Location chosen when it is created. |
| Environment | A copy of the project (production by default; add staging, or pr-<number> for previews). Each environment has its own network and variables, and its own databases or shared ones. |
| Service | A program running in an environment: web, worker, cron or private (TCP). |
| Deployment | One build-and-run of a service, numbered #1, #2… |
On the project's canvas, each card is a service, database or bucket. Click a card to open its details panel. Tidy up puts the cards back in their default positions.
Service types
Change the type on the Settings tab → Service type, then redeploy for it to take effect.
| Type | Use it for | Tabs |
|---|---|---|
| Web | Serves HTTP requests, has an HTTPS address and custom domains | Deployments, Logs, Metrics, Variables, Domains, Settings |
| Worker | Queue consumers, bots, background jobs; no port, no address | Deployments, Logs, Metrics, Variables, Settings |
| Cron job | Runs on a schedule and then stops: backups, sending reports… | Runs, Deployments, Variables, Settings |
| Private (TCP) | A database or server that only your own services reach, at <service>.internal:<port>; no public address |
Deployments, Logs, Metrics, Variables, Domains, Settings |
Cron jobs
- Schedule (cron): 5 fields
minute hour day month weekday, in Vietnam time. For example0 2 * * *is 2 a.m. every day and*/15 * * * *is every 15 minutes. ZoCloud enforces a minimum interval between two runs (the portal tells you if the schedule is too dense). - Timeout (minutes): the maximum duration of one run.
- Each run is a container that runs to completion, with the environment's variables and network. If the previous run has not finished, the next one is skipped.
- The Runs tab shows the exit code and the last lines of the log; the Run now button starts a run by hand.
Deploy sources
GitHub App
- Go to the organisation's GitHub section and click Connect GitHub.
- On GitHub, install ZoCloud on your personal account or organisation and choose all repositories or selected repositories.
- If you belong to several ZoCloud organisations, choose which one will use these repositories ("Link GitHub to which organisation?"). One GitHub installation is linked to exactly one ZoCloud organisation.
- Installed already: click Installed before? Link it. To add repositories later: Give ZoCloud more repositories or Choose repositories.
ZoCloud only reads source code (never writes), uses a short-lived token per repository when building, and reports the deployment status on the commit. With Deploy on push turned on (Settings tab), each push to the service's branch deploys exactly that commit; if you push while a build is running, ZoCloud waits and then deploys the newest version.
Unlinking a GitHub account means the services that use its repositories can no longer build.
If the portal says "GitHub is not turned on yet", you can still deploy from a Public Git URL or with the zo CLI.
Public Git URL
Paste https://github.com/you/app (or another Git host over https). There is no deploy on push: click Deploy or use the CLI.
Upload from your machine (zo CLI)
zo deploy packs the current folder and uploads it. It never sends .env* files (except .env.example), .git, node_modules, .venv…, and it honours .gitignore, .zocloudignore and .dockerignore. See zo CLI and MCP server.
Docker image
A public image (Docker Hub, GHCR, Quay…). ZoCloud pins the tag to its digest at deploy time, so a rollback runs exactly the same image again. Leave Port empty to take it from the image's EXPOSE.
Templates
New → From a template: choose an application (filter by category or Find a template) and click Deploy the template. The portal creates the project, databases, services, variables (secrets are generated at random) and storage in turn, then deploys.
Build and run
ZoCloud detects the framework and chooses the install, build and start commands. To see in advance what ZoCloud will do with a folder: zo detect.
Override them on the Settings tab → Build and run (empty means the detected value; changes apply from the next deployment):
| Field | Notes |
|---|---|
| Branch, Root folder | Leave the root folder empty if the app sits at the root of the repository (monorepo: apps/web) |
| Install command, Build command, Start command | |
| Port | The app must listen on the PORT variable; empty: from EXPOSE, or 8080 |
| Health check | A path that returns a status below 500 once the app is ready (for example /health); empty: only the port is checked |
| mCPU, RAM (MB) | Resources per replica, within the plan's limits |
| Watch paths | One pattern per line, relative to the repository root (api/**, *.go, !docs/**): deploy only when the push changes a matching file |
Configuration file zocloud.json (or railway.json)
Put it at the root of the repository (or the service's root folder). When the file exists, its values take precedence over the portal's fields on every build; the portal shows which file is in effect.
{
"build": {
"builder": "auto",
"dockerfile": "Dockerfile",
"install": "npm ci",
"build": "npm run build",
"runtime_version": "22",
"output_dir": "dist",
"watch_paths": ["api/**", "!**/*.md"]
},
"deploy": {
"start": "npm start",
"prestart": "npm run migrate",
"port": 3000,
"health_path": "/health",
"replicas": 2,
"cron_schedule": "0 2 * * *",
"sleep_after_minutes": 15
}
}
| Field | Valid values |
|---|---|
builder |
auto, dockerfile, generated |
dockerfile |
a path inside the repository |
prestart |
a command run before the app starts (for example migrations) |
port |
1–65535 |
health_path |
starts with / |
replicas |
0–20 |
cron_schedule |
a cron expression (cron services only) |
sleep_after_minutes |
0 (never sleep) or 5–1440 |
watch_paths |
up to 50 patterns |
zocloud.json rejects unknown fields (a misspelt name fails the deployment). Each command is a single line.
Moving from Railway: ZoCloud reads railway.json with the fields builder, buildCommand, dockerfilePath, watchPatterns, startCommand, preDeployCommand, healthcheckPath, numReplicas, cronSchedule and sleepApplication.
Environment variables
Variables tab: Add variable, or Edit as .env to paste several lines; Table switches back. Variables are encrypted at rest, available both at build time and at run time, and take effect from the next deployment.
Reference variables
A value can point at a database, bucket or another service in the same environment, and is updated automatically when the source changes:
| Reference | Meaning |
|---|---|
${{pg.DATABASE_URL}} |
the connection string of the database named pg |
${{cache.REDIS_URL}} |
the Valkey named cache |
${{files.S3_BUCKET}}, ${{files.S3_ACCESS_KEY_ID}}… |
the bucket named files |
${{api.PRIVATE_URL}} |
http://api.internal (private network) |
${{api.PUBLIC_URL}} |
the https://…zocloud.app address of the web service api |
${{api.VARIABLE_NAME}} |
a variable (not a reference) of the service api |
Variables set by ZoCloud
PORT, ZOCLOUD_SERVICE_NAME, ZOCLOUD_PUBLIC_DOMAIN, ZOCLOUD_DEPLOYMENT_ID, ZOCLOUD_GIT_COMMIT_SHA (when built from Git), ZOCLOUD_VOLUME_MOUNT_PATH (when a volume is attached). You cannot set these yourself.
Private networking
Services in the same environment talk to each other over a private network that never touches the Internet:
- Web services:
http://<service>.internal(HTTP and WebSocket). Use the${{<service>.PRIVATE_URL}}variable. - Private (TCP) services:
<service>.internal:<port>for any TCP protocol (variablesPRIVATE_DOMAIN,PRIVATE_PORT).
The private address is shown on the service's Domains tab. The calling service needs to be redeployed after you add the variable.
Volumes (persistent storage)
For uploaded files, SQLite… The data survives deployments. Each service can have at most one volume.
- Settings tab → Volume → Add a volume: enter the Path in the container (for example
/data) and the Size (MB). - Redeploy to attach the volume.
Notes:
- A service with a volume runs 1 replica and does not autoscale. On every deployment the old replica stops before the new one starts (a few seconds of downtime).
- Resize only grows a volume, never shrinks it; it happens online. When the volume is full, the app gets "No space left" errors.
- Used space is measured about every 10 minutes. The total volume size is one of the plan's limits.
- Delete the volume: the data is deleted after the next deployment and cannot be recovered.
Volume backups
- Automatic every night (encrypted, primary copy kept in Vietnam), plus frequent (every few minutes) backups and a Back up now button.
- Restore a backup: every file currently in the volume is replaced and the service restarts.
- Commands around backups (for databases running inside the container): Before the backup and After the backup (always run), run with
sh -cinside the container with the service's variables. If the "before" command fails, no backup is taken. - If the server holding the volume suffers a prolonged outage, ZoCloud restores the latest backup onto another server by itself and runs the service there. Writes made after the latest backup may be lost (usually at most about 15 minutes); contact Support if you need to get them back.
Scaling
Settings tab → Scaling:
- Replicas (0–20): applied immediately, no deployment needed. From 2 replicas up, the app stays up when one server fails; a single-replica app may be down for a few minutes when its server breaks. Use 2 replicas for production.
- Scale with CPU: set Minimum, Maximum and CPU target (%). ZoCloud adds replicas when the average CPU exceeds the target and removes them when the load drops, within the plan's limits. Not available for services with a volume, nor for cron jobs.
Metrics tab: requests, errors (5xx), p95 latency, CPU and RAM across all replicas, updated every minute.
Sleep when idle
Web services only. Settings tab → Sleep when idle:
- As the plan says: the default of the plan you are on.
- Never sleep.
- Sleep after 10 / 30 / 60 / 240 minutes.
While asleep, the app is stopped (it uses no resources); the next request wakes it up within a few seconds. Good for demos, internal tools and apps with few users. Not for apps that must answer instantly.
Environments
On the canvas, open the environment menu (next to production):
- New environment: enter a Name (for example
staging), choose which environment it is a Copy of, and a Git branch (leave it empty to keep each service's own branch). The new environment has the same services, variables and volumes; pushing to that branch deploys automatically. - Own (empty) databases: creates empty databases like the originals, without touching production data. If you do not tick it, the new environment has no databases of its own: add databases to that environment yourself (reference variables only point at databases in the same environment).
- Remove environment: its services and its own databases are deleted.
Pull request previews
Requires a repository connected through the GitHub App.
- Environment menu → Pull request previews → Turn previews on.
- Choose the Preview databases:
- Their own empty databases: each PR gets empty copies of the production databases (same names, no data), deleted when the PR is closed. They count towards the plan's limits.
- Share production's databases: fast, but the PR can touch real data.
- No databases.
Every PR against the branch the project deploys gets its own pr-<number> environment at <service>-pr<number>-<project>.zocloud.app, running 1 replica, updated on every push and deleted automatically when the PR is closed or merged. GitHub shows a "ZoCloud preview / " status on the PR; click it to open the preview. PRs from forks get no preview (because previews run with the project's environment variables). To delete one by hand: select the preview environment → Remove preview.
Deployments, logs and rollback
The Deployments tab
Lists the deployments with their trigger (Push, Deploy from the CLI, Configuration change, Rollback…), commit and status. Click Deploy at the top to deploy again.
The running deployment keeps serving when the new one fails; traffic only moves over once the new one is healthy.
Rollback
On the Deployments tab, pick an older deployment → Roll back. No rebuild is needed. CLI: zo rollback <number>.
The Logs tab
- The Search the logs (Enter) box: text search.
- Filters: All lines, App output,
stderr, HTTP requests (further filtered by 2xx/3xx/4xx/5xx; each line has the status, method, path, duration and IP), Firewall (WAF events). - Time range: 15m, 1h, 6h, 24h, 7d.
- Pause / Follow live.
Common deployment errors
| Symptom | Usual cause |
|---|---|
| The repository cannot be cloned | The repository is not public (use the GitHub App), wrong branch or wrong URL |
| The build fails | Read the build log on the Deployments tab; try zo detect on your machine |
| The app starts and then exits | The app does not listen on 0.0.0.0:$PORT, or a variable is missing |
| Out of resources / over the plan's limits | Lower the RAM or replicas, or upgrade the plan (Billing) |
Automatic diagnosis and one-click fixes
When a deployment fails, ZoCloud reads its error code, build log and app log to find the cause. The result is the Diagnosis card under the error on the Deployments tab:
- Each cause has a short explanation and the log line that shows it.
- When a setting fixes it, a button does it: Set port 3000 and deploy again, Add NPM_CONFIG_LEGACY_PEER_DEPS=true and deploy again, Set runtime_version to 20 and deploy again.
- Some certain failures (the app on another port, npm peer dependency conflicts, the wrong Node version) are fixed and deployed again by themselves, once a day per service at most. The card and Activity say so.
- A failure no rule knows is explained by ZoCloud AI, with a fix when it is sure of one.
Your AI agent (Claude, Cursor…) reads the diagnosis with the MCP tool diagnose and applies a fix with apply_fix; when a deployment fails, zo mcp tells the agent to call diagnose.
Custom domains
Web services only. The ….zocloud.app address is always there, with HTTPS.
-
Domains tab → enter the name (for example
www.example.vn) → Add. -
Prove the name is yours (if the portal asks): add a TXT record
Type Name Value TXT _zocloud.<domain>zocloud-verify=<your organisation's code>It can be set on the name itself or on the domain above it: proving
example.vncovers every name under it. This step is not needed for names bought at ZoCloud, names in ZoCloud DNS, or names in a connected Cloudflare zone. -
Point the name at ZoCloud:
- Subdomains (
www,app…):CNAME→<service>-<project>.zocloud.app(the portal shows the exact value). - The apex (
example.vn):Arecords to the IPs the portal shows (Domains page → Attach the name). Remove the apex's old A/AAAA records, and addwwwtoo (a CNAME to the apex).
- Subdomains (
-
ZoCloud checks DNS every minute. Once DNS is right, the status goes from waiting for DNS to active, and an HTTPS certificate is issued automatically within a few minutes and renewed automatically.
For names in ZoCloud DNS or in a connected Cloudflare account, the records are created automatically. See Domains. CLI: zo domains add www.example.vn.
Security (firewall and blocking)
Web services only. Settings tab → Security. Applies to every domain of the service.
Firewall (OWASP Core Rule Set, in front of the app):
| Mode | Effect |
|---|---|
| Off | Requests reach the app unchecked |
| Record only (default) | Attacks (SQL injection, XSS, scanners…) are written to the logs (Firewall filter), not blocked |
| Block | Attacks are rejected with a 403 before they reach the app |
Recommended approach: leave it on Record only for a few days, check the Firewall logs for false positives, then switch to Block. ZoCloud suggests it when the service is ready.
- Application: choose WordPress, Drupal or Nextcloud to use the built-in exceptions (otherwise the admin pages and editors trigger false positives easily), or Other.
- Silenced rules: the numbers of rules (taken from the firewall log lines) that block legitimate traffic, separated by commas, for example
942100, 920350. - Blocked countries: two-letter codes (
CN, RU…). Visitors from there get a 403 page. - Blocked addresses: one IP or network range per line (
203.0.113.7,198.51.100.0/24).
Click Save.
Deleting a service
Settings tab → Danger zone → Delete service, and type the service's name to confirm. The app stops and its domains stop being served.