Nginx Quickstart

This guide will help you deploy static content with Nginx on Zerops. You’ll create a service, configure it, and deploy your application.

Prerequisites

A Zerops account (sign up if you don’t have one)
A project in Zerops (create one in the GUI if needed)

Step 1: Create Nginx Service

You can create an Nginx service using either the Zerops GUI or zCLI.

Using GUI
Using zCLI

Navigate to your project dashboard
Click Add new service in the Services menu
Select Nginx as the service type
Choose your Nginx version (or use latest)
Set a unique hostname (e.g., app, web, frontend)
Optionally configure:
- Secret environment variables
- Auto scaling settings
Click Create service

The hostname must be unique within your project, contain only lowercase letters (a-z) or numbers (0-9), and be maximum 25 characters.

First, install and set up zCLI if you haven’t already.Create a description.yaml file:

description.yaml

project:
  name: my-project
services:
  - hostname: app
    type: nginx@latest
    minContainers: 1
    maxContainers: 6

Then import the project:

zcli project project-import description.yaml

Add to Existing Project

If you already have a project, create an import.yaml file with just the services section:

import.yaml

services:
  - hostname: app
    type: nginx@latest
    minContainers: 1
    maxContainers: 6

Then run:

zcli project service-import import.yaml

Step 2: Configure Your Application

Create a zerops.yaml file in the root of your repository to configure how Zerops builds and runs your application.

Pre-built Files
Build + Deploy
Advanced

If you already have built static files and just want to deploy them:

zerops.yaml

zerops:
  - setup: app
    run:
      base: nginx@latest
      documentRoot: public

This minimal configuration:

Uses the latest Nginx version
Serves files from the /var/www/public directory
Uses default settings for everything else

If you need to build your application (e.g., using Node.js, npm, etc.):

zerops.yaml

zerops:
  - setup: app
    build:
      base: nodejs@20
      buildCommands:
        - npm install
        - npm run build
      deployFiles:
        - dist/~
      cache: node_modules
    run:
      base: nginx@latest
      documentRoot: dist

This configuration:

Uses Node.js 20 for building
Installs dependencies and runs build
Deploys everything from the dist folder
Caches node_modules for faster builds
Serves the built files from /var/www/dist

For more complex scenarios with custom commands and environment variables:

zerops.yaml

zerops:
  - setup: app
    build:
      base: nodejs@20
      prepareCommands:
        - npm install -g pnpm
      buildCommands:
        - pnpm install
        - pnpm run build
      deployFiles:
        - dist/~
      cache:
        - node_modules
        - .pnpm-store
    run:
      base: nginx@latest
      documentRoot: dist
      initCommands:
        - rm -rf ./cache
      envVariables:
        APP_ENV: production
        API_URL: https://api.example.com

This advanced setup:

Installs pnpm as a custom package manager
Caches both node_modules and pnpm store
Clears cache on each container start
Sets environment variables for runtime

Step 3: Deploy Your Application

From Git
Using zCLI

The recommended approach is to connect your Git repository:

Go to your service detail in Zerops GUI
Click Connect to GitHub/GitLab
Authorize Zerops and select your repository
Choose the branch to deploy from
Zerops will automatically detect your zerops.yaml
Click Deploy

Set up automatic deployments by enabling Deploy on push. Every commit to your selected branch will trigger a new deployment.

Deploy directly from your local machine using zCLI:

# Login to Zerops
zcli login

# Deploy your application
zcli push

The zcli push command will:

Package your application
Upload it to Zerops
Trigger the build and deploy pipeline
Show real-time logs

Make sure you’re in the directory containing your zerops.yaml file when running zcli push.

Step 4: Configure Public Access

By default, your service is only accessible within the Zerops private network. To make it publicly accessible:

Go to your service detail in Zerops GUI
Navigate to Public access & routing in the left menu
Click Add new routing rule
Configure your domain:
- Use a Zerops subdomain (e.g., app.zerops.app)
- Or add your custom domain
Save the routing rule

For custom domains, you’ll need to add DNS records pointing to Zerops. The GUI will show you exactly what records to create.

Example: Deploy a React App

Here’s a complete example for deploying a React application:

zerops.yaml

zerops:
  - setup: app
    build:
      base: nodejs@20
      buildCommands:
        - npm ci
        - npm run build
      deployFiles:
        - build/~
      cache: node_modules
    run:
      base: nginx@latest
      documentRoot: build

Project structure:

my-react-app/
├── public/
├── src/
├── package.json
├── package-lock.json
└── zerops.yaml

Deployment steps:

Add zerops.yaml to your React project root
Commit and push to your Git repository
Connect the repository in Zerops GUI
Watch the build and deploy process
Access your app via the provided URL

Next Steps

Environment Variables

Configure environment variables

Custom Nginx Config

Customize your web server

SEO Optimization

Set up Prerender.io for better SEO

Scaling

Configure auto scaling

Common Issues

My app shows a blank page

Check that your documentRoot in zerops.yaml matches where your build output is located. For example, if your build creates a dist folder, use documentRoot: dist.

Client-side routing doesn't work (404 errors)

The default Nginx configuration handles this automatically with try_files $uri $uri/ /index.html. If you’ve customized your Nginx config, make sure you have this directive.

Build fails with 'command not found'

Make sure you’re using the correct base image for your build. For example, if you’re using npm commands, you need base: nodejs@<version> in your build section.

How do I see build logs?

Go to your service detail in Zerops GUI, click on Service dashboard & runtime containers, then Open pipeline detail to see complete build and deploy logs.

JavaScript Runtimes

Backend Languages

Web Servers & Static

Nginx Quickstart

Prerequisites

Step 1: Create Nginx Service

Step 2: Configure Your Application

Step 3: Deploy Your Application

Step 4: Configure Public Access

Example: Deploy a React App

Next Steps

Environment Variables

Custom Nginx Config

SEO Optimization

Scaling

Common Issues

Build docs developers (and LLMs) love

JavaScript Runtimes

Backend Languages

Web Servers & Static

​Prerequisites

​Step 1: Create Nginx Service

​Step 2: Configure Your Application

​Step 3: Deploy Your Application

​Step 4: Configure Public Access

​Example: Deploy a React App

​Next Steps

Environment Variables

Custom Nginx Config

SEO Optimization

Scaling

​Common Issues

Build docs developers (and LLMs) love

Prerequisites

Step 1: Create Nginx Service

Step 2: Configure Your Application

Step 3: Deploy Your Application

Step 4: Configure Public Access

Example: Deploy a React App

Next Steps

Common Issues