Static Service Quickstart

This guide will help you deploy a static site to Zerops using the Static service. You’ll learn how to set up the service, configure routing, 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)
Static files to deploy (HTML, CSS, JS) or a framework that builds to static files

Step 1: Create Static Service

Using GUI
Using zCLI

Go to your project dashboard in Zerops
Click Add new service
Select Static as the service type
Set a unique hostname (e.g., app, web, site)
Configure scaling settings (optional)
Click Create service

Create a description.yaml file:

description.yaml

project:
  name: my-static-site
services:
  - hostname: app
    type: static
    minContainers: 1
    maxContainers: 3

Import the project:

zcli project project-import description.yaml

Step 2: Configure Your Application

Create a zerops.yaml file in your repository root.

Simple Static Files
With Build Step
With Custom Routing

If you have pre-built static files:

zerops.yaml

zerops:
  - setup: app
    run:
      base: static

That’s it! This minimal configuration:

Serves your static files
Handles SPA routing automatically
Uses sensible defaults

Deploy your files using zcli push from your project directory.

For frameworks like React, Vue, or Angular:

zerops.yaml

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

This configuration:

Uses Node.js to build your app
Deploys the dist folder content
Caches node_modules for faster builds
Serves with the Static service

Add custom redirects and CORS:

zerops.yaml

zerops:
  - setup: app
    build:
      base: nodejs@20
      buildCommands:
        - npm install
        - npm run build
      deployFiles:
        - build/~
    run:
      base: static
      routing:
        # Enable CORS for API calls
        cors: "*"
        
        # Custom redirects
        redirects:
          # Permanent redirect
          - from: /old-page
            to: /new-page
            status: 301
          
          # Redirect old blog posts
          - from: /blog/*
            to: /articles/
            preservePath: true
            status: 301

Step 3: Deploy

From Git Repository
Using zCLI

Go to your service in Zerops GUI
Click Connect to GitHub/GitLab
Authorize and select your repository
Choose the branch
Enable Deploy on push for automatic deployments
Click Deploy

Every push to your selected branch will trigger an automatic deployment.

From your project directory:

# Login if needed
zcli login

# Push and deploy
zcli push

Watch the build and deployment logs in real-time.

Step 4: Set Up Public Access

Navigate to your service in Zerops GUI
Go to Public access & routing
Click Add new routing rule
Choose:
- Zerops subdomain (e.g., myapp.zerops.app), or
- Custom domain (requires DNS configuration)
Save the routing rule

Your site is now live!

Common Examples

React Application

zerops.yaml

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

Vue Application with Custom Redirects

zerops.yaml

zerops:
  - setup: app
    build:
      base: nodejs@20
      buildCommands:
        - npm install
        - npm run build
      deployFiles:
        - dist/~
    run:
      base: static
      routing:
        redirects:
          # Redirect www to non-www
          - from: https://www.example.com/*
            to: https://example.com
            status: 301
            preservePath: true

Gatsby Site with SEO

zerops.yaml

zerops:
  - setup: app
    build:
      base: nodejs@20
      buildCommands:
        - npm install
        - npm run build
      deployFiles:
        - public/~
      cache:
        - node_modules
        - .cache
    run:
      base: static
      # Prerender.io token set as secret in Zerops GUI

Multi-Domain Landing Pages

zerops.yaml

zerops:
  - setup: app
    build:
      base: nodejs@20
      buildCommands:
        - npm install
        - npm run build
      deployFiles:
        - dist/~
    run:
      base: static
      routing:
        redirects:
          # Product promo domain
          - from: https://promo.example.com/*
            to: https://example.com/special-offer
            status: 302
          
          # Legacy domain
          - from: https://old-site.com/*
            to: https://example.com
            status: 301
            preservePath: true

Routing Patterns

Masked Redirects

Show content from one URL while keeping another URL in the browser:

routing:
  redirects:
    # URL stays /about, but shows content from /about-us
    - from: /about
      to: /about-us

No status code means it’s a masked redirect. Perfect for URL aliases.

Path Preservation

Maintain the path when redirecting:

routing:
  redirects:
    # /blog/post-1 → /articles/post-1
    - from: /blog/*
      to: /articles/
      preservePath: true
      status: 301

When using preservePath with wildcards, ensure the to path ends with / for proper concatenation.

Domain Redirects

routing:
  redirects:
    # Redirect old domain to new
    - from: https://old-domain.com/*
      to: https://new-domain.com
      status: 301
      preserveQuery: true
    
    # Redirect all subdomains
    - from: https://*.staging.com/*
      to: https://production.com
      status: 302

SEO Optimization

Enable Prerender.io for search engine visibility:

Sign up for Prerender.io
In Zerops GUI, add secret variable:
- Name: PRERENDER_TOKEN
- Value: Your Prerender.io token
(Optional) Set custom host in zerops.yaml:

run:
  base: static
  envVariables:
    PRERENDER_HOST: custom.prerender.host

Prerender automatically detects crawlers from Google, Bing, social media platforms, and AI tools (ChatGPT, Perplexity, Claude).

Security Headers

Add security headers for production:

zerops:
  - setup: app
    run:
      base: static
      routing:
        headers:
          - for: "/"
            values:
              X-Frame-Options: "'DENY'"
              X-Content-Type-Options: "'nosniff' always"
              X-XSS-Protection: "'1; mode=block' always"
              # CSP with escaped quotes
              Content-Security-Policy: '"default-src ''self''" always'

Troubleshooting

404 on page refresh (SPA routing)

The Static service handles this automatically. If you’re getting 404s:

Check that you have an index.html in your root
Verify your deployFiles path is correct
Make sure you haven’t overridden the default routing

CORS errors

Add CORS configuration:

routing:
  cors: "*"

Redirect not working

Check:

Status code is required for absolute URLs
Path preservation needs trailing / in target
Exact matches take priority over wildcards
Review logs in Zerops GUI for errors

Build files not found

Verify your framework’s output directory matches deployFiles:

React: build/ (Create React App) or dist/ (Vite)
Vue: dist/
Angular: dist/<project-name>/
Next.js: .next/ (static export)

Custom headers not applied

Remember to quote header values:

Correct: X-Frame-Options: "'DENY'"
Wrong: X-Frame-Options: DENY

Migration from Full Nginx

If you’re migrating from a full Nginx service:

Review your current Nginx configuration
Map Nginx directives to Static service YAML:
- try_files → Built-in default behavior
- rewrite → routing.redirects
- add_header for CORS → routing.cors
- Other headers → routing.headers
Test thoroughly in a development environment
Deploy to production

If you need features not available in Static service, you can always switch back to full Nginx using the migration tool in the GUI.

Next Steps

Advanced Routing

Learn complex routing patterns

Framework Examples

See framework-specific guides

Custom Headers

Set up security headers

Environment Variables

Configure environment variables

JavaScript Runtimes

Backend Languages

Web Servers & Static

Static Service Quickstart

Prerequisites

Step 1: Create Static Service

Step 2: Configure Your Application

Step 3: Deploy

Step 4: Set Up Public Access

Common Examples

React Application

Vue Application with Custom Redirects

Gatsby Site with SEO

Multi-Domain Landing Pages

Routing Patterns

Masked Redirects

Path Preservation

Domain Redirects

SEO Optimization

Security Headers

Troubleshooting

Migration from Full Nginx

Next Steps

Advanced Routing

Framework Examples

Custom Headers

Environment Variables

Build docs developers (and LLMs) love

JavaScript Runtimes

Backend Languages

Web Servers & Static

​Prerequisites

​Step 1: Create Static Service

​Step 2: Configure Your Application

​Step 3: Deploy

​Step 4: Set Up Public Access

​Common Examples

​React Application

​Vue Application with Custom Redirects

​Gatsby Site with SEO

​Multi-Domain Landing Pages

​Routing Patterns

​Masked Redirects

​Path Preservation

​Domain Redirects

​SEO Optimization

​Security Headers

​Troubleshooting

​Migration from Full Nginx

​Next Steps

Advanced Routing

Framework Examples

Custom Headers

Environment Variables

Build docs developers (and LLMs) love

Prerequisites

Step 1: Create Static Service

Step 2: Configure Your Application

Step 3: Deploy

Step 4: Set Up Public Access

Common Examples

React Application

Vue Application with Custom Redirects

Gatsby Site with SEO

Multi-Domain Landing Pages

Routing Patterns

Masked Redirects

Path Preservation

Domain Redirects

SEO Optimization

Security Headers

Troubleshooting

Migration from Full Nginx

Next Steps