**Tags:** "Hello World" Examples · Frameworks Examples · React # Wasp Hello World A full-stack [Wasp](https://wasp.sh/) application — React client, Node.js API, and [PostgreSQL](https://www.postgresql.org) — deployed on [Zerops](https://zerops.io). The client ships as static Nginx assets; the API runs on Node.js 24 with Prisma migrations. ### Available Environments - [AI Agent](https://app.zerops.io/recipes/wasp-hello-world.md?environment=ai-agent) - [Remote (CDE)](https://app.zerops.io/recipes/wasp-hello-world.md?environment=remote-cde) - [Local](https://app.zerops.io/recipes/wasp-hello-world.md?environment=local) - [Stage](https://app.zerops.io/recipes/wasp-hello-world.md?environment=stage) - [Small Production](https://app.zerops.io/recipes/wasp-hello-world.md?environment=small-production) - **Highly-available Production** ← current ### Services in this Environment **Services:** - **core** (core:ha@2) - Containers: 3 × Shared Core, 0.00 GB RAM, 0 GB Disk - **app** (alpine/static@1.0) - Containers: 2 × Shared Core, 0.38 GB RAM, 1 GB Disk - Repository: [zerops-recipe-apps/wasp-hello-world-app](https://github.com/zerops-recipe-apps/wasp-hello-world-app) - **api** (ubuntu/nodejs@24) :3001 - Containers: 2 × Shared Core, 0.75 GB RAM, 1 GB Disk - Repository: [zerops-recipe-apps/wasp-hello-world-app](https://github.com/zerops-recipe-apps/wasp-hello-world-app) - **db** (postgresql:ha@16) :5432, :6432, :5433 - Containers: 1 × Shared Core, 1.25 GB RAM, 1 GB Disk **Total Resources:** 8 containers, 3.50 GB RAM, 5 GB Disk ### One-Click Deploy (Import YAML) Use this YAML with `zcli project import` to deploy this environment: ```yaml #zeropsPreprocessor=on # Wasp hello world — highly-available production environment. # HA PostgreSQL and scaled client/API containers — lightweight # demo resources (oltp-staging DB, shared CPU on API). # # Project vault are a value store — zerops.yaml maps them: # REACT_APP_API_URL / WASP_SERVER_URL ← ${API_URL} # WASP_WEB_CLIENT_URL ← ${APP_URL} project: name: wasp-hello-world-ha-prod corePackage: SERIOUS vault: APP_URL: https://app-${zeropsSubdomainHost}.prg1.zerops.app API_URL: https://api-${zeropsSubdomainHost}-3001.prg1.zerops.app services: - hostname: app type: static priority: 5 zeropsSetup: prod-client buildFromGit: https://github.com/zerops-recipe-apps/wasp-hello-world-app enableSubdomainAccess: true minContainers: 2 verticalAutoscaling: minRam: 0.25 minFreeRamGB: 0.125 - hostname: api type: nodejs@24 priority: 5 zeropsSetup: prod-api buildFromGit: https://github.com/zerops-recipe-apps/wasp-hello-world-app enableSubdomainAccess: true minContainers: 2 maxContainers: 6 verticalAutoscaling: minRam: 0.5 minFreeRamGB: 0.25 - hostname: db type: postgresql:ha@16 # Hello-world HA demo — oltp-staging, not oltp-production (~4 GB). profile: oltp-staging priority: 10 ``` --- ## Next Steps After deploying one of the environments and getting to know Zerops, you have two paths to choose from: 1. **Template Flow** — Clone our GitHub repositories and use the whole recipe as a template 2. **Integrate Flow** — If you already have an existing application on a similar stack, integrate the recipe setup with your application Select a flow: [Template Flow](https://app.zerops.io/recipes/wasp-hello-world.md?environment=highly-available-production&guideFlow=template) or [Integrate Flow](https://app.zerops.io/recipes/wasp-hello-world.md?environment=highly-available-production&guideFlow=integrate) Both flows are shown below: ## How to take over the Highly-available Production environment ### 📦 Clone the template repositories Fork or clone the following repositories to your local machine or GitHub account: - [zerops-recipe-apps/wasp-hello-world-app](https://github.com/zerops-recipe-apps/wasp-hello-world-app) - [zerops-recipe-apps/wasp-hello-world-app](https://github.com/zerops-recipe-apps/wasp-hello-world-app) ### 1. Find your service name Many commands and configurations need the exact name of your service. You can find it in the Zerops Dashboard. - Open your project in the Zerops Dashboard. - In the project overview, find the service you want to manage. - Use this exact name whenever a command or pipeline configuration asks for ``. Zerops GUI: Locating the Service Name ### 2. Configure deployment pipeline Go to Service Settings > Pipelines & CI/CD Settings in the Zerops Dashboard and connect your repository. For production, use a trigger on new tags. This keeps deployments intentional and tied to a specific version. You can also add a regex filter, such as `^v[0-9]+\.[0-9]+\.[0-9]+$`, if you want to allow only semantic version tags. Alternatively, add `zcli push` to your existing CI/CD pipeline if you want full control over when deployments happen. Learn more about pipeline triggers: https://docs.zerops.io/features/pipeline ### 3. Deploy to production Create and push a new Git tag to deploy a specific version of your app: ```bash git tag -a v1.0.0 -m "Release version 1.0.0" git push origin v1.0.0 ``` > [!TIP] > Open the pipeline detail in the Zerops Dashboard to check the build progress and verify that all steps finish successfully. ### 4. Configure high availability Review the autoscaling settings in Service Settings > Automatic Scaling Configuration in the Zerops Dashboard. For high availability, make sure your service runs at least two containers: ```yaml minContainers: 2 maxContainers: 6 verticalAutoscaling: cpuMode: DEDICATED minRam: 2 minFreeRamGB: 0.5 minFreeRamPercent: 20 ``` > [!CAUTION] > Pay attention to `minFreeRamGB`. This value tells Zerops when to scale RAM vertically. Adjust it based on your app’s real memory needs to avoid memory limits under load. In HA mode, each container runs on a different physical server. A load balancer distributes traffic across healthy instances. Because of this setup, your application should be stateless. Avoid local file storage for sessions or user uploads. Use external stores such as Redis or Valkey instead. ### 5. Set up your domain To send real traffic to your app, configure public HTTP access in Service Settings > Public Access & Internal Ports in the Zerops Dashboard. Add your custom domain and point your DNS records to the Zerops IPs shown in the dashboard: ```text Type Name Content TTL A example.com Auto AAAA example.com Auto ``` Check the public access documentation for full details, including wildcard domain configuration: https://docs.zerops.io/features/access > [!TIP] > When changing DNS records for production, start with a low TTL value. Make sure SSL certificates are active before you disable the fallback Zerops subdomain. Once everything works, you can disable the Zerops subdomain so all traffic goes through your custom domain. --- ### 🎉 You are good to go! Your application is live in production and the core setup is complete. The following sections are optional. They cover extra production features such as observability, backups, and diagnostic access. You can stop here and come back later when you need them. --- ### 6. Set up observability (Optional) Forward logs and metrics to external services or self-hosted tools from Project Settings > Log Forwarding & Logs Overview in the Zerops Dashboard. Zerops supports log forwarding to services such as Better Stack, Papertrail, and self-hosted ELK stacks. For metrics, you can use the Prometheus and Grafana recipes available in the Zerops recipe marketplace. These can help you monitor PostgreSQL, MariaDB, and other services. Learn more about log forwarding: https://docs.zerops.io/references/logging ### 7. Configure database backups (Optional) Manage automated encrypted backups in Service Settings > Backups in the Zerops Dashboard. For HA production, consider increasing backup frequency and testing restore procedures regularly. HA database services on Zerops run as primary-replica clusters. Backups are taken from replicas, which helps reduce performance impact on the primary database. Before a major deployment or migration, create a manual protected backup: ```bash zcli backup create --tags pre-deploy,protected ``` Read the backup documentation for more options: https://docs.zerops.io/features/backup ### 8. Set up diagnostic access (Optional) Use zCLI and VPN access when you need to inspect or maintain production services directly. For runtime services: ```bash zcli vpn up ssh .zerops ``` For HA services with multiple containers, you can connect to specific instances. Find the full DNS names for individual containers in Service Settings > Service Containers & Overview in the Zerops Dashboard. For databases, connect through the VPN to reach the project’s private network, or set up secure direct IP access for your database admin tools. Check the VPN documentation: https://docs.zerops.io/references/cli/commands#vpn-up ## How to integrate app with Zerops ### 1. Adding `zerops.yaml` The main application configuration file you place at the root of your repository. It tells Zerops how to build, deploy, and run your Wasp app. Wasp deploys as **two production services** from one repo: - `prod-client` — builds the React SPA (`wasp build` + `vite build`) and serves static assets via Nginx. - `prod-api` — runs the bundled Node.js server from `.wasp/out/server/bundle/` and applies Prisma migrations on deploy. ```yaml zerops: - setup: prod-client build: base: nodejs@24 buildCommands: - npm install --min-release-age=0 - npx wasp install - node scripts/generate-build-env.cjs - npx wasp build - npm run build:client envVariables: RUNTIME_APP_ENV: production deployFiles: - .wasp/out/web-app/build/~ cache: - node_modules - .wasp/out run: base: static - setup: prod-api build: base: nodejs@24 os: ubuntu buildCommands: - NPM_CONFIG_PRODUCTION=false NPM_CONFIG_ENGINE_STRICT=false NPM_CONFIG_AUDIT=false npm install --min-release-age=0 - npx wasp install - npx wasp build - cp -R migrations/. .wasp/out/db/migrations/ - sh scripts/bundle-server.sh - node scripts/prepare-api-deploy.cjs deployFiles: - .zerops/deploy/~ cache: - node_modules - .wasp/out deploy: readinessCheck: httpGet: port: 3001 path: /auth/me failureTimeout: 300 retryPeriod: 10 run: base: nodejs@24 os: ubuntu initCommands: - zsc execOnce ${appVersionId} --retryUntilSuccessful -- node scripts/migrate-prod.cjs - zsc execOnce ${appVersionId} --retryUntilSuccessful -- node scripts/seed-demo-user.cjs ports: - port: 3001 httpSupport: true envVariables: NODE_ENV: production PORT: 3001 DATABASE_URL: postgresql://${db_user}:${db_password}@${db_hostname}:${db_port}/${db_dbName} APP_DB_NAME: ${db_dbName} JWT_SECRET: wasp-zerops-hello-world-demo-jwt-v1 start: sh -c 'cd .wasp/out/server && NODE_ENV=production node --enable-source-maps bundle/server.js' - setup: dev build: base: nodejs@24 os: ubuntu buildCommands: - npm install --min-release-age=0 - npx wasp install deployFiles: ./ cache: - node_modules run: base: nodejs@24 os: ubuntu ports: - port: 3000 httpSupport: true - port: 3001 httpSupport: true envVariables: DATABASE_URL: ${db_connectionString} start: zsc noop --silent ``` ### 2. Environment variables Set these at the **project** level in your recipe `import.yaml` as a value store (not Wasp runtime key names). `zerops.yaml` maps them into the app: | Import variable | Mapped in `zerops.yaml` | Purpose | |-----------------|-------------------------|---------| | `API_URL` | `REACT_APP_API_URL` (prod-client build), `WASP_SERVER_URL` (prod-api) | Public API URL (port 3001) | | `APP_URL` | `WASP_WEB_CLIENT_URL` (prod-api) | Public SPA URL (hostname `app`) | Keep them at the project level, because both services read them. `envVariables` on a single service in `import.yaml` are kept as well, but only that service sees them. Demo login (seeded on deploy): **username** `demo`, **password** `demo-zerops1`. The home page requires auth; unauthenticated users are redirected to `/login`. The API service receives `DATABASE_URL` from `${db_*}` placeholders and runs `migrate-prod.cjs` plus `seed-demo-user.cjs` on deploy. If the API returns 502, verify `APP_URL` and `API_URL` exist on the project (re-import `import.yaml` env if needed). ### 3. Local development ```bash npm install --min-release-age=0 npx wasp install npx wasp start db # optional local Postgres via Wasp npx wasp db migrate-dev npx wasp db seed seedDemoUser npx wasp start # client :3000, server :3001 — sign in with demo / demo-zerops1 ``` Production build locally: ```bash export DATABASE_URL='postgresql://user:pass@localhost:5432/wasp' wasp build REACT_APP_API_URL='http://localhost:3001' npm run build:client ``` ## How to integrate api with Zerops ### 1. Adding `zerops.yaml` The main application configuration file you place at the root of your repository. It tells Zerops how to build, deploy, and run your Wasp app. Wasp deploys as **two production services** from one repo: - `prod-client` — builds the React SPA (`wasp build` + `vite build`) and serves static assets via Nginx. - `prod-api` — runs the bundled Node.js server from `.wasp/out/server/bundle/` and applies Prisma migrations on deploy. ```yaml zerops: - setup: prod-client build: base: nodejs@24 buildCommands: - npm install --min-release-age=0 - npx wasp install - node scripts/generate-build-env.cjs - npx wasp build - npm run build:client envVariables: RUNTIME_APP_ENV: production deployFiles: - .wasp/out/web-app/build/~ cache: - node_modules - .wasp/out run: base: static - setup: prod-api build: base: nodejs@24 os: ubuntu buildCommands: - NPM_CONFIG_PRODUCTION=false NPM_CONFIG_ENGINE_STRICT=false NPM_CONFIG_AUDIT=false npm install --min-release-age=0 - npx wasp install - npx wasp build - cp -R migrations/. .wasp/out/db/migrations/ - sh scripts/bundle-server.sh - node scripts/prepare-api-deploy.cjs deployFiles: - .zerops/deploy/~ cache: - node_modules - .wasp/out deploy: readinessCheck: httpGet: port: 3001 path: /auth/me failureTimeout: 300 retryPeriod: 10 run: base: nodejs@24 os: ubuntu initCommands: - zsc execOnce ${appVersionId} --retryUntilSuccessful -- node scripts/migrate-prod.cjs - zsc execOnce ${appVersionId} --retryUntilSuccessful -- node scripts/seed-demo-user.cjs ports: - port: 3001 httpSupport: true envVariables: NODE_ENV: production PORT: 3001 DATABASE_URL: postgresql://${db_user}:${db_password}@${db_hostname}:${db_port}/${db_dbName} APP_DB_NAME: ${db_dbName} JWT_SECRET: wasp-zerops-hello-world-demo-jwt-v1 start: sh -c 'cd .wasp/out/server && NODE_ENV=production node --enable-source-maps bundle/server.js' - setup: dev build: base: nodejs@24 os: ubuntu buildCommands: - npm install --min-release-age=0 - npx wasp install deployFiles: ./ cache: - node_modules run: base: nodejs@24 os: ubuntu ports: - port: 3000 httpSupport: true - port: 3001 httpSupport: true envVariables: DATABASE_URL: ${db_connectionString} start: zsc noop --silent ``` ### 2. Environment variables Set these at the **project** level in your recipe `import.yaml` as a value store (not Wasp runtime key names). `zerops.yaml` maps them into the app: | Import variable | Mapped in `zerops.yaml` | Purpose | |-----------------|-------------------------|---------| | `API_URL` | `REACT_APP_API_URL` (prod-client build), `WASP_SERVER_URL` (prod-api) | Public API URL (port 3001) | | `APP_URL` | `WASP_WEB_CLIENT_URL` (prod-api) | Public SPA URL (hostname `app`) | Keep them at the project level, because both services read them. `envVariables` on a single service in `import.yaml` are kept as well, but only that service sees them. Demo login (seeded on deploy): **username** `demo`, **password** `demo-zerops1`. The home page requires auth; unauthenticated users are redirected to `/login`. The API service receives `DATABASE_URL` from `${db_*}` placeholders and runs `migrate-prod.cjs` plus `seed-demo-user.cjs` on deploy. If the API returns 502, verify `APP_URL` and `API_URL` exist on the project (re-import `import.yaml` env if needed). ### 3. Local development ```bash npm install --min-release-age=0 npx wasp install npx wasp start db # optional local Postgres via Wasp npx wasp db migrate-dev npx wasp db seed seedDemoUser npx wasp start # client :3000, server :3001 — sign in with demo / demo-zerops1 ``` Production build locally: ```bash export DATABASE_URL='postgresql://user:pass@localhost:5432/wasp' wasp build REACT_APP_API_URL='http://localhost:3001' npm run build:client ``` ### 🎯 What's next? **Deploy other environments** — Ready to scale? Deploy additional environments for different stages of your workflow: - [AI Agent](https://app.zerops.io/recipes/wasp-hello-world.md?environment=ai-agent) - [Remote (CDE)](https://app.zerops.io/recipes/wasp-hello-world.md?environment=remote-cde) - [Local](https://app.zerops.io/recipes/wasp-hello-world.md?environment=local) - [Stage](https://app.zerops.io/recipes/wasp-hello-world.md?environment=stage) - [Small Production](https://app.zerops.io/recipes/wasp-hello-world.md?environment=small-production) ## Knowledge Base ### Platform Reference - [Routing & Domains](https://docs.zerops.io/features/access) - [Scaling](https://docs.zerops.io/features/scaling) - [Environment Variables](https://docs.zerops.io/features/env-variables) - [CLI (zcli)](https://docs.zerops.io/references/cli) ### Service Type Reference **Static** - [Build & Deploy Pipeline](https://docs.zerops.io/alpine/how-to/build-pipeline) - [Customize Runtime](https://docs.zerops.io/alpine/how-to/customize-runtime) **Node.js** - [Build & Deploy](https://docs.zerops.io/nodejs/how-to/build-pipeline) - [Customize Runtime](https://docs.zerops.io/nodejs/how-to/customize-runtime) **PostgreSQL** - [Connect](https://docs.zerops.io/postgresql/how-to/connect) - [Backup & Restore](https://docs.zerops.io/postgresql/how-to/backup) - [Manage](https://docs.zerops.io/postgresql/how-to/manage) - [Scale](https://docs.zerops.io/postgresql/how-to/scale) --- ## Related Recipes - [TanStack Start Hello World](https://app.zerops.io/recipes/tanstack-start-hello-world-app.md) - [React (Vite) Static Hello World](https://app.zerops.io/recipes/react-static-hello-world.md) - [React Router Static Hello World](https://app.zerops.io/recipes/react-router-static-hello-world.md) - [React Router SSR Hello World](https://app.zerops.io/recipes/react-router-ssr-hello-world.md)