# zaneops.dev Full Documentation

# Authentication

All API requests require a session `Cookie`, which you get when you login to the app. 

For mutative requests (`DELETE`, `POST`, `PUT`, `PATCH`), you need add a `csrftoken` to the cookie header and the same value need to be sent as a header `X-CSRFToken`.

## Get a session cookie

To get a session cookie, you need to login, then get the cookie in `sessionid`.

```http "sessionid=tvmt1xp0c2ep33htukqm140fb4igkz4u;" {" Here is the session cookie:":13} {5-8}
### Request
POST /api/auth/login HTTP/1.1
Content-Type: application/json

{
  "username": "<your-username>",
  "password": "<your-password>"
}

### Response
HTTP/1.1 201 Created
Content-Type: application/json

Set-Cookie: sessionid=tvmt1xp0c2ep33htukqm140fb4igkz4u; Domain=.127-0-0-1.sslip.io; expires=Wed, 24 Jul 2024 16:49:05 GMT; HttpOnly; Max-Age=1209600; Path=/; SameSite=Lax

{
  "id": 2,
  "name": "New Resource Name",
  "description": "New Resource Description"
}
```


## Perform an authorized Request



```http {3}
### Request
GET /api/auth/me HTTP/1.1
Cookie: sessionid=tvmt1xp0c2ep33htukqm140fb4igkz4u;

### Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "user": {
    "username": "fredkiss3",
    "first_name": "",
    "last_name": ""
  }
}
```


## Perform a mutative request 

To perform a mutative request i.e `POST`, `PUT`, `PATCH`, `DELETE` requests, you need to follow 2 steps : 

1. Obtain a csrf token : 

```http "csrftoken=zydcEbNXQGJFxzLphKEO8Mg88VdEwi8c;" {" Here is the CSRF Token:":6}
### Request
GET /api/csrf HTTP/1.1

### Response
HTTP/1.1 200 OK

Set-Cookie: csrftoken=zydcEbNXQGJFxzLphKEO8Mg88VdEwi8c; expires=Wed, 09 Jul 2025 17:03:09 GMT; Max-Age=31449600; Path=/; SameSite=Lax
```

2. Then add the `csrftoken` both in the cookie and in `X-Csrftoken` header :

```http {4-5}
### Request
POST /api/projects HTTP/1.1
Content-Type: application/json
Cookie: sessionid=tvmt1xp0c2ep33htukqm140fb4igkz4u; csrftoken=zydcEbNXQGJFxzLphKEO8Mg88VdEwi8c;
X-Csrftoken: zydcEbNXQGJFxzLphKEO8Mg88VdEwi8c

{
  "slug": "sandbox"
}

### Response
HTTP/1.1 201 Created
Content-Type: application/json

{
  "description": null,
  "id": "prj_GxCy6Tg35ax",
  "slug": "sandbox-2",
  "created_at": "2024-07-10T17:05:56.276194Z",
  "updated_at": "2024-07-10T17:05:56.276180Z"
}
```

# Introduction

## Common Errors status codes

### 405 Method Not Allowed

This is returned when an endpoint is called with an unexpected http method. For example, if updating a user requires
a POST request and a PATCH is issued instead, this error is returned. Here's how it looks like:

```json
{
  "type": "client_error",
  "errors": [
    {
      "code": "method_not_allowed",
      "detail": "Method “patch” not allowed.",
      "attr": null
    }
  ]
}
```

### 406 Not Acceptable

This is returned if the `Accept` header is submitted and contains a value other than `application/json`. Here's how the
response would look:

```json
{
  "type": "client_error",
  "errors": [
    {
      "code": "not_acceptable",
      "detail": "Could not satisfy the request Accept header.",
      "attr": null
    }
  ]
}
```

### 415 Unsupported Media Type

This is returned when the request content type is not json. Here's how the response would look:

```json
{
  "type": "client_error",
  "errors": [
    {
      "code": "not_acceptable",
      "detail": "Unsupported media type “application/xml” in request.",
      "attr": null
    }
  ]
}
```

### 500 Internal Server Error

This is returned when the API server encounters an unexpected error. Here's how the response would look:

```json
{
  "type": "server_error",
  "errors": [
    {
      "code": "error",
      "detail": "A server error occurred.",
      "attr": null
    }
  ]
}
```

# Architecture

import { ASSETS_SERVER_DOMAIN } from "astro:env/client"
import {Steps, Aside} from '@astrojs/starlight/components';

ZaneOps is a self-hosted PaaS platform designed to manage, deploy, and monitor services with [docker swarm](https://docs.docker.com/engine/swarm/). 
Each service and app deployed on ZaneOps correspond one-to-one to a [swarm service]((https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/)).


## Components

<img src={`${ASSETS_SERVER_DOMAIN}/images/main-architecture.svg`} alt="Main architecture" />


**🔌 Proxy (`caddy`)**
Acts as the single entrypoint for all HTTP traffic. Routes API and service requests appropriately and serves static assets.

**🧠 App (Backend + Frontend)**
- **Backend**: Django + Django REST Framework
- **Frontend**: Single Page App (SPA) made with React Router
- Provides the user interface and the core API logic.

**⚙️ Workers**
- Run scheduled/background jobs.
- Use the same Docker image as the main app.

**🧾 Log Collector (`fluentd`)**
- Aggregates all logs from running services.
- Collects logs from proxy for [HTTP logs](/screenshots/#http-logs-page).

**🔍 Log Searcher (`grafana/loki`)**
- Stores and indexes logs for querying.

**⚡️ Cache (`valkey`)**
- Used for caching and session storage.

**🗃️ Database (`PostgreSQL`)**
- Stores all persistent application data.

**📬 Task Queue (`temporal`)**
- Orchestrates background tasks and worker coordination.

## Core Scenarios

### 1. Deploy a New Service

<img src={`${ASSETS_SERVER_DOMAIN}/images/initial-deploy-scenario.svg`} alt="Initial service deploy scenario" />

#### Step-by-Step

<Steps>
1. **User Action**:  
   `PUT /deploys/XYZ` is sent to the proxy.

2. **Routing**:  
   The proxy forwards it to the app backend.

3. **App Logic**:  
   App creates a new deployment record in the database with status `PENDING`.

4. **Task Queue**:  
   App sends a `deploy_service(XYZ)` message to the task queue (Temporal).

5. **Worker Execution**:  
   A worker picks up the task and runs the deployment logic (Docker service creation).

6. **Completion**:  
   Worker notifies the task queue that the task is done.

7. **State Update**:  
   Worker updates the Deployment state in the DB  to `HEALTHY` or `FAILED`.

8. **Proxy Mapping**:  
   The proxy maps `xyz.com` to the new service, e.g., `service_XYZ:3000`.
</Steps>

### 2. Deploy the same service again

<img src={`${ASSETS_SERVER_DOMAIN}/images/redeploy-service-scenario.svg`} alt="Redeploy service scenario" />

#### Step-by-Step

<Steps>
1. **User Action**:  
   `PUT /deploys/XYZ` sent again.

2. **App Processing**:  
   The app creates a new deployment version and sends a deploy task.

3. **Worker Logic**:
   * Stops (removes) the previous Docker service (v1).
   * Starts a new one with the updated spec (v2).

4. **State Update**:  
   DB updated accordingly (`HEALTHY` or `FAILED`).

5. **Proxy Keeps Same Mapping**:  
   `xyz.com` still points to `service_XYZ`, which now resolves to the new container.

</Steps>

### 3. Access a Running Service

<img src={`${ASSETS_SERVER_DOMAIN}/images/access-service-scenario.svg`} alt="Access service scenario" />

#### Step-by-Step

<Steps>
1. **User Request**:  
   Browser makes `GET xyz.com`.

2. **Proxy Resolution**:  
   Proxy resolves the domain to the correct internal service (Docker alias or internal hostname).

3. **Routing**:  
   The request is forwarded to the running container.

4. **Response**:  
   Container sends back the HTTP response via the proxy.
</Steps>

### 4. Logs Collection

<img src={`${ASSETS_SERVER_DOMAIN}/images/logs-collection-scenario.svg`} alt="Log collection scenario" />

#### Step-by-Step

<Steps>
1. **Logs Emitted**:  
   Each service sends logs to Fluentd over `stdout`.

2. **Collector Buffering**:  
   Fluentd waits ~5 seconds and tags/filters logs.

3. **Forward to App**:  
   Logs are forwarded to the API `/logs/ingest`.

4. **App Preprocessing**:  
   Enriches logs (adds metadata like service/deployment IDs).

5. **Send to Loki**:  
   App sends structured logs to Loki.
</Steps>


### 5. Logs Search

<img src={`${ASSETS_SERVER_DOMAIN}/images/logs-search-scenario.svg`} alt="Log search scenario" />

#### Step-by-Step

<Steps>
1. **User Request**:  
   `GET /search/logs` hits the proxy.

2. **Routing**:  
   Proxy forwards to the app backend.

3. **Query Execution**:  
   App translates filters and queries Loki.

4. **Return**:  
   Logs are returned to the frontend (paginated, filtered, etc.).
</Steps>

# ZaneOps v1.0

<span className='text-gray-600 dark:text-gray-400'>27 Feb 2025</span> by [**Fred KISSIE**](https://github.com/Fredkiss3)

ZaneOps v1.0 is finally here!

ZaneOps is a beautiful, self-hosted, open-source platform for hosting static sites, web apps, databases, services (like **Umami**, **WordPress**, **Supabase**), workers, or anything else you need—whether you’re launching a startup or managing an enterprise.

Today, ZaneOps is stable and production-ready.

## Install ZaneOps

Installation steps are detailled on the [installation page](/installation), but here is the TLDR:

```shell
# create directory to install zaneops
mkdir -p /var/www/zaneops && cd /var/www/zaneops

# download zaneops CLI
curl https://cdn.zaneops.dev/makefile > Makefile

# setup zaneops 
make setup 

# start zaneops app 
make deploy 
```

## Why ZaneOps exists ?

The goal of ZaneOps is to bring together the best features we could ~~steal~~ take inspiration from popular platforms like 
**Vercel**, **Railway**, and **Render**, while giving you full ownership of your data and complete control over your server costs.

## Features  

### Deploying Services from Docker Images  

<video muted src="https://assets.zaneops.dev/videos/deploy-using-docker.mp4" alt="Deploy using Docker" controls />  

### Environment Variables Management  

Supports adding single variables:  

<video muted src="https://assets.zaneops.dev/videos/add-env-variables.mp4" alt="Add environment variables" controls />  

And importing variables from `.env` files:  

<video muted src="https://assets.zaneops.dev/videos/add-from-dotenv.mp4" alt="Import from .env files" controls />  

### Advanced URL Management  

Supports wildcard domains:  

<video muted src="https://assets.zaneops.dev/videos/wildcard-support.mp4" alt="Wildcard domain support" controls />  

Generates default URLs for services:  

<video muted src="https://assets.zaneops.dev/videos/generate-url.mp4" alt="Generate default URLs" controls />  

Allows multiple services to share the same domain:  

![Multiple services sharing the same domain](https://assets.zaneops.dev/images/same-domain-services.png)  

### Persistent Logs  

Application logs are persisted per deployment:  

<video muted src="https://assets.zaneops.dev/videos/application-logs.mp4" alt="Application logs per deployment" controls />  

HTTP logs are persisted per deployment and per service:  

<video muted src="https://assets.zaneops.dev/videos/http-logs.mp4" alt="HTTP logs per service" controls />  

### Monitoring  

Provides metrics per service and deployment:  

<video muted src="https://assets.zaneops.dev/videos/metrics.mp4" alt="Service and deployment metrics" controls />  

### Git-Like Configuration Changes  

Allows you to review changes before deploying:  

<video muted src="https://assets.zaneops.dev/videos/changes-modal.mp4" alt="Review changes before deployment" controls />  

### Resource Limits  

<video muted src="https://assets.zaneops.dev/videos/resource-limits.mp4" alt="Set resource limits" controls />  

### Magic File Mounts  

Override the content of any file within your services or add new files required for configuration:  

<video muted src="https://assets.zaneops.dev/videos/config-files.mp4" alt="Magic file mounts for configuration" controls />  

### Deployment Webhook URLs  

Easily set up a [CI/CD workflow](/deploying-with-github-actions):  

<video muted src="https://assets.zaneops.dev/videos/deploy-webhook-url.mp4" alt="Deployment webhook URL" controls />  

## OK, I Like What I See 😍  

If you'd like to start using ZaneOps today, follow the [installation steps](/installation).  

You can also check out our tutorial on [deploying a React Router SSR app](/tutorials/react-router) on ZaneOps.

## What's Next?  

V1.0 is just the beginning! We have exciting features planned, including:

- **Git-based deployments** with GitHub integration and pull request preview environments
- **Multi-server support** with multiple replicas per service
- **Automated backups** for databases and other services

We’re just getting started, and we’d love for you to join us on this journey.

If you’ve made it this far, we have a small favor to ask:
Please, [give us a star on GitHub!](https://github.com/zane-ops/zane-ops) ⭐
It's one of the easiest ways to support the project. You can also help by resharing this post and spreading the word about ZaneOps.

**Thank you!** 🫶

# ZaneOps v1.10

import {Aside} from '@astrojs/starlight/components';

> Release notes: https://github.com/zane-ops/zane-ops/releases/tag/v1.10.0

<span className='text-gray-600 dark:text-gray-400'>25 May 2025</span> by [**Fred KISSIE**](https://github.com/Fredkiss3)

Today we release ZaneOps v1.10, introducing a web terminal for deployments and a web terminal to the server.

**To install:**

1. via the UI:
 <img className="block dark:hidden" src="https://assets.zaneops.dev/images/new-version-toast-light.png" alt="clone environment modal" />
 <img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/new-version-toast-dark.png" alt="clone environment modal" />
 <img className="block dark:hidden" src="https://assets.zaneops.dev/images/new-version-modal-light.png" alt="project environments page" />
 <img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/new-version-modal-dark.png" alt="project environments page" />

2. via the shell:
```shell
# assuming you are at /var/www/zaneops
curl https://cdn.zaneops.dev/makefile > Makefile
make setup
make deploy
```

### Shells to deployments

In this new version, we are introducing a new terminal directly to your service, allowing you to inspect containers created for your service by ZaneOps and debug or run any arbitrary script within it.

<video src="https://assets.zaneops.dev/videos/webshell.mp4" controls muted></video>

### Shell to the server

As well as terminals to your deployments, you can now connect to your server via SSH directly from the web UI.

In the demo below, you can see the user connecting via SSH to their server and triggering an update of ZaneOps via the shell directly.
*Pretty cool, huh?*

<video src="https://assets.zaneops.dev/videos/upgrade-with-shell.mp4" controls muted></video>

<Aside type='note' title='SSH keys'>
This feature works using SSH keys, [learn more about how to configure](/knowledge-base/ssh-keys).
</Aside>

### Persistent cache

In v1.10, we introduce a new performance improvement on the frontend. 
Between each new version, you will have persistent cache on the browser, so that next time you access your app, navigation is very snappy even if you refresh the browser.

Here is a demo where you can see:
- On top: without persistent storage
- On the bottom: with persistent storage

<video src="https://assets.zaneops.dev/videos/persistent-cache.mp4" controls muted></video>

### Anonymous Telemetry

We introduced a new anonymous telemetry feature to help us better understand the real usage of ZaneOps in production.

It works by sending a simple `PING` request at most every 30 minutes to the ZaneOps CDN ([cdn.zaneops.dev](https://cdn.zaneops.dev)).

The source code of the CDN can be found [here](https://github.com/zane-ops/cdn/tree/main/src/index.ts).

Anonymous telemetry can be disabled by modifying the env variable in `.env`:

```shell
# /var/www/zaneops/.env
TELEMETRY_ENABLED=false # or true
```

<Aside type='note' title='Documentation'>
More details [here](/knowledge-base/anonymous-telemetry).
</Aside>

### Docker Image Size reduction

The ZaneOps Docker image is lighter and has a smaller number of layers, going from **1.5GB** to **902MB**.

So downloading new versions of ZaneOps should be faster in future releases ⚡️.

### Thank you! 🫶

- We now have more than **500 stars** ⭐️ on the repository
- And **100+ more installs** 🔝 on ZaneOps

Thank you all for making this happen 🙏

# ZaneOps v1.11

import {Aside} from '@astrojs/starlight/components';
import { ASSETS_SERVER_DOMAIN } from "astro:env/client"


> Release notes: https://github.com/zane-ops/zane-ops/releases/tag/v1.11.0

<span className='text-gray-600 dark:text-gray-400'>22 July 2025</span> by [**Fred KISSIE**](https://github.com/Fredkiss3)


Today we release zaneOps v1.11 introducing support for private **GitHub** and **Gitlab** repositories as well as auto-deploy on git push
all via [Git apps](/knowledge-base/git/git-apps).

**To install :**


1. via the UI:
    <img className="block dark:hidden" src={`${ASSETS_SERVER_DOMAIN}/images/new-version-toast-light.png`} alt="clone environment modal" />
    <img className="!hidden dark:!block" src={`${ASSETS_SERVER_DOMAIN}/images/new-version-toast-dark.png`} alt="clone environment modal" />
    <img className="block dark:hidden" src={`${ASSETS_SERVER_DOMAIN}/images/new-version-modal-light.png`} alt="project environments page" />
    <img className="!hidden dark:!block" src={`${ASSETS_SERVER_DOMAIN}/images/new-version-modal-dark.png`} alt="project environments page" />

2. via the shell:
    ```shell
    # assuming you are at /var/www/zaneops
    curl https://cdn.zaneops.dev/makefile > Makefile
    make setup
    make deploy
    ```


<Aside type="note" title='Important'>
This version includes changes to the `Makefile`, please re-download the up-to-date `Makefile`:
```shell
# assuming you are at `/var/www/zaneops`
curl https://cdn.zaneops.dev/makefile > Makefile
```
</Aside>

### Git apps


[Git apps](/knowledge-base/git/git-apps) are integrations with [**GitHub**](/knowledge-base/git/github) and [**GitLab**](/knowledge-base/git/github) that allow you to
listen to Git events from your repositories and perform actions on your behalf.
They can be installed either on your personal profile or within an organization you’re a member of.

With Git apps on ZaneOps, you get:

- Support for private GitHub and GitLab repositories.
    <video src={`${ASSETS_SERVER_DOMAIN}/videos/private-github-repos.mp4`} controls muted></video>
- [Auto-deploy on Git push](/knowledge-base/git/auto-deploy):
    <video src={`${ASSETS_SERVER_DOMAIN}/videos/auto-deploy-github-gitlab.mp4`} controls muted></video>


<Aside type="note" title='supported providers'>
Currently, only **GitHub** and **GitLab** apps are supported.
</Aside>

### Cleanup deploy queue

You can now clean up the deployment queue when triggering a new deployment.
For example, if multiple deployments are queued, only the latest one will be kept, the others will be canceled.

- Choose to clean up the queue while preserving the latest deployment:
    <video src={`${ASSETS_SERVER_DOMAIN}/videos/cleanup-queue-preserve-latest.mp4`} controls muted></video>
- Or clean up all deployments in the queue:
    <video src={`${ASSETS_SERVER_DOMAIN}/videos/cleanup-deploy-queue.mp4`} controls muted></video>


### Your PaaS is ready for AI ✨

We added both [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt) endpoints to the documentation for easier digest from chatGPT, Claude and Cursor.

### Thank you 💖

We just reached **900 stars** on GitHub, it's thanks to supporters like you that this project is getting traction. 
Slowly but surely we are getting progress.

# ZaneOps v1.12

import {Aside} from '@astrojs/starlight/components';
import { ASSETS_SERVER_DOMAIN } from "astro:env/client"

> Release notes: https://github.com/zane-ops/zane-ops/releases/tag/v1.12

<span className='text-gray-600 dark:text-gray-400'>7 October 2025</span> by [**Fred KISSIE**](https://github.com/Fredkiss3)


Today we release zaneOps v1.12 introducing support for [preview environments](/knowledge-base/preview-environments), a new design for the homepage, account settings and more.

**To install :**


1. via the UI:
    <img className="block dark:hidden" src={`${ASSETS_SERVER_DOMAIN}/images/new-version-toast-light.png`} alt="clone environment modal" />
    <img className="!hidden dark:!block" src={`${ASSETS_SERVER_DOMAIN}/images/new-version-toast-dark.png`} alt="clone environment modal" />
    <img className="block dark:hidden" src={`${ASSETS_SERVER_DOMAIN}/images/new-version-modal-light.png`} alt="project environments page" />
    <img className="!hidden dark:!block" src={`${ASSETS_SERVER_DOMAIN}/images/new-version-modal-dark.png`} alt="project environments page" />

2. via the shell:
    ```shell
    # assuming you are at /var/www/zaneops
    curl https://cdn.zaneops.dev/makefile > Makefile
    make setup
    make deploy
    ```


### Preview environments

The major feature for this version is [preview environments](/knowledge-base/preview-environments). They allow you to test a feature in 
a branch or pull request on your app before merging to production. 

For services created via [Git applications](/knowledge-base/git/git-apps/), Pull request preview environments are activated by default.
You can create preview environments via API or Pull Request (GitHub)/Merge Request (GitLab).

#### GitHub PR preview environments
<video src="https://assets.zaneops.dev/videos/pull request preview with comment.mp4" alt="GitHub pull request preview deployments" muted controls />

#### GitLab MR preview environments

<Aside type="caution" title='Resync gitlab app'>
There was a bug with GitLab application webhooks where 
it didn't subscribe to merge request events, you need to resync repositories to fix this. 
</Aside>

<video src="https://assets.zaneops.dev/videos/giltab-merge-request.mp4" alt="GitLab merge request preview deployments" muted controls />


### New dashboard design

We revamped the dashboard with a nicer design. In this new dashboard, there is also a list of the 6 most recent deployments:

<img className="block dark:hidden" src="/images/new-dashboard-light.png" alt="New Dashboard page" />
<img className="!hidden dark:!block" src="/images/new-dashboard-dark.png" alt="New Dashboard page" />

We also updated the design on the project detail page, you will now get logos for services created from Docker images.

<img className="block dark:hidden" src="/images/new-project-detail-light.png" alt="New project detail page" />
<img className="!hidden dark:!block" src="/images/new-project-detail-dark.png" alt="New project detail page" />


### Account settings

You can now update the user's info (firstname, lastname, username) and password :

<video src="https://assets.zaneops.dev/videos/account-settings.mp4" alt="Account settings" muted controls />

### Other changes

- In the next versions of ZaneOps, a persistent toast will be shown while updating to a new version:
    <video src="https://assets.zaneops.dev/videos/auto-update-toast.mp4" alt="Auto update toast" muted controls />
    
- Terminals have now a light & Dark theme
    <img src="/images/terminal-light.png" alt="Terminal" />
    <img src="/images/terminal-dark.png" alt="Terminal" />

- When selecting branch for a repository, a list of branches will be shown for autocomplete:
   
    <img className="block dark:hidden rounded-md" src="/images/repo-branch-autocomplete-light.png" alt="Autocomplete git branches for a repository" />
    <img className="!hidden dark:!block rounded-md" src="/images/repo-branch-autocomplete-dark.png" alt="Autocomplete git branches for a repository" />

- Same for docker images in the service's settings page:
   
    <img className="block dark:hidden rounded-md" src="/images/docker-image-autocomplete-light.png" alt="Autocomplete docker images" />
    <img className="!hidden dark:!block rounded-md" src="/images/docker-image-autocomplete-dark.png" alt="Autocomplete docker images" />

- New theme switcher to allow you to select between light, dark mode or following the system's preferences:
    <video src="https://assets.zaneops.dev/videos/theme switcher.mp4" alt="Theme switcher" muted controls />

- Starting from `v1.12`, release notes for next versions will be shown directly in ZaneOps's dashboard: 
   <img src="/images/release-notes.png" alt="Changelog" className='rounded-md shadow-md my-4 mx-auto' />

# ZaneOps v1.13

import {Aside} from '@astrojs/starlight/components';
import { ASSETS_SERVER_DOMAIN } from "astro:env/client"

> Release notes: https://github.com/zane-ops/zane-ops/releases/tag/v1.13.0

<span className='text-gray-600 dark:text-gray-400'>28 February 2026</span> by [**Fred KISSIE**](https://github.com/Fredkiss3)


ZaneOps v1.13 is here with some big additions: [Docker Compose support](/knowledge-base/docker-compose), [templates](/knowledge-base/docker-compose/01-templates), shared volumes, build registries, and more.



<Aside type="caution" title='Before updating'>
This version includes changes to the Docker stack. Make sure to re-download the `Makefile` and rerun the `setup` script before deploying.
</Aside>

**To install:**

```shell
# assuming you are at /var/www/zaneops
curl https://cdn.zaneops.dev/makefile > Makefile
make setup
make stop # stop the services
make deploy
```

{/* ### ZaneOps Cloud ☁️ waitlist

The waitlist for [ZaneOps Cloud](/cloud) is now open. ZaneOps Cloud is the next evolution of the platform, designed for teams and enterprise users. It will ship with:

- **Multi-tenancy**: support for multiple teams with fine-grained permissions
- **OIDC Authentication**: enterprise-grade SSO via OpenID Connect
- **Audit logs**: full activity trail of logins, deployments, service changes, and more
- **Custom authentication pages**: protect any service behind a login page
- **Custom branding**: white-label your authentication pages
- ...and more

[Join the waitlist](/cloud) to be notified when the cloud version launches. [Sponsor the project](https://github.com/sponsors/zane-ops) to get **early access** when it does.

<Aside type="tip" title='Open Source'>
The self-hosted version will remain free and MIT-licensed.
</Aside> */}


### Docker Compose stacks

The headline feature of v1.13 is native [Docker Compose stack support](/knowledge-base/docker-compose). You can now deploy any `docker-compose.yml` file directly on ZaneOps.

Under the hood, compose files are deployed as [Docker stacks](https://docs.docker.com/reference/cli/docker/stack/), with:

- blue/green deployments out of the box
- domain assignment via service labels
- dynamic value generation via template expressions (e.g. `{{ generate_password | 8 }}` generates a secure 8-character password)

<video src={`${ASSETS_SERVER_DOMAIN}/videos/deploy-simple-nginx.mp4`} alt="Deploy simple nginx docker compose" muted controls />


### Templates

Beyond raw compose files, you can also deploy from pre-built [templates](/knowledge-base/docker-compose/01-templates). ZaneOps supports two template providers:

- Our own curated templates:
    <video src={`${ASSETS_SERVER_DOMAIN}/videos/deploy-umami-template.mp4`} alt="Deploy ZaneOps umami template" muted controls />

- Dokploy templates (experimental):
    <video src={`${ASSETS_SERVER_DOMAIN}/videos/deploy-dokploy-template.mp4`} alt="Deploy dokploy uptime-kuma template" muted controls />


### Shared volumes

You can now create volumes shared across multiple services. One service owns the volume, and others mount it as read-only. This is useful for sharing assets, media, or uploads between a backend and frontend, for example.

Shared volumes are fully compatible with blue/green deployments.

<video src={`${ASSETS_SERVER_DOMAIN}/videos/shared_volumes.mp4`} alt="Shared volumes across reader & writer" muted controls />


### Docker registry credentials

Deploying private images no longer requires entering credentials on every service. You can now create registry credentials once and reuse them across all your apps.

<video src={`${ASSETS_SERVER_DOMAIN}/videos/shared-credentials.mp4`} alt="Shared registry credentials" muted controls />


### Build registries

In preparation for multi-server support, you can now configure a build registry to store Docker images built by ZaneOps. Choose between storing images on your server's filesystem or pushing them to an S3-compatible provider (AWS S3, MinIO, R2, etc.).

<video src={`${ASSETS_SERVER_DOMAIN}/videos/build-registries.mp4`} alt="Build registries" muted controls />

![S3 settings build registries](/images/build-registries-s3.webp)


### Other changes

- Environment variables are now obfuscated in build logs and hidden by default in change fields
   ![obfuscated secrets in logs](/images/obfuscate-env-in-logs.png)
- Git services now receive `GIT_COMMIT_SHA` as both a build arg and an environment variable
    ![Git commit sha](/images/git-commit-sha.webp)
- After creating an SSH key in server settings, ZaneOps now shows the exact commands to add it to your server
    ![command after creating SSH key](/images/ssh-command-after-creation.webp)
- ZaneOps remembers the last SSH key used in the server terminal and automatically reconnects you on your next visit
    <video src={`${ASSETS_SERVER_DOMAIN}/videos/remember-last-ssh-on-console.mp4`} alt="Remember last ssh key" muted controls />

# ZaneOps v1.7

import {Aside} from '@astrojs/starlight/components';


> Release notes: https://github.com/zane-ops/zane-ops/releases/tag/v1.7.0

<span className='text-gray-600 dark:text-gray-400'>22 Mar 2025</span> by [**Fred KISSIE**](https://github.com/Fredkiss3)


Since the release of [v1.0](./announcing-v1.mdx), we added a lot more changes. 

**To install :**

```shell
# assuming you are at /var/www/zaneops
curl https://cdn.zaneops.dev/makefile > Makefile
make setup
make deploy
```

<Aside type="caution" title='Before updating'>
This version is potentially breaking. If you notice your services failing when deploying, 
please redeploy all of the services in that environment.
</Aside>

### Environments

Environments let you separate your services logically accross isolated instances. Within environments you 
can share environment variables available accross all the services within the environment. You can [learn more here](/knowledge-base/environments).

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/project-environments-light.png" alt="project environments page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/project-environments-dark.png" alt="project environments page" />

You can clone environments and copy all the services, variables and configurations to the new environment : 

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/project-clone-environment-light.png" alt="clone environment modal" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/project-clone-environment-dark.png" alt="clone environment modal" />

Accross environments you can also have multiple services with the same name :

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/project-environment-search-light.png" alt="searching a service accross multiple environments" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/project-environment-search-dark.png" alt="searching a service accross multiple environments" />



### New Onboarding Page

Now, when you install ZaneOps on a blank instance, you will be greated by an onboarding page allowing you to create
a first user directly from the UI rather than only from the terminal :

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/create-user-light.png" alt="onboarding page with a form for creating the first user" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/create-user-dark.png" alt="onboarding page with a form for creating the first user" />



### New Upgrading experience

Starting with [v1.7.0](https://github.com/zane-ops/zane-ops/releases/tag/v1.7.0), 
future upgrades will trigger a toast notification informing you of new ZaneOps versions,
 enabling you to upgrade directly from the UI instead of relying solely on the terminal.

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/new-version-toast-light.png" alt="clone environment modal" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/new-version-toast-dark.png" alt="clone environment modal" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/new-version-modal-light.png" alt="project environments page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/new-version-modal-dark.png" alt="project environments page" />


## Other changes

- Changed the logs configuration to only logs the result of monitoring health checks if they fail, significantly reducing clutter 
  on the logs page
- Added confirmation modals for destructive actions, for when you want to delete a project, environment or service :
  ![delete environment confirmation modal](https://assets.zaneops.dev/images/delete-environment-confirmation.png)
  ![delete project confirmation modal](https://assets.zaneops.dev/images/delete-project-confirmation.png)
  ![delete service confirmation modal](https://assets.zaneops.dev/images/delete-service-confirmation.png)
  ![toggle sleep service confirmation modal](https://assets.zaneops.dev/images/toggle-sleep-service-confirmation.png)

## Bug fixes

- We fixed some occasional `502 Bad Gateway` error you would encounter when you deploy services in [#406](https://github.com/zane-ops/zane-ops/pull/406)
- We fixed some bugs with the metrics not being collected correctly and resulting in you not seeing the metrics of certain services in [#383](https://github.com/zane-ops/zane-ops/pull/383)

# ZaneOps v1.8

import {Aside} from '@astrojs/starlight/components';

> Release notes: https://github.com/zane-ops/zane-ops/releases/tag/v1.8.0

<span className='text-gray-600 dark:text-gray-400'>31 Mar 2025</span> by [**Fred KISSIE**](https://github.com/Fredkiss3)


Today we release zaneOps v1.8 introducing our all new [Git services](/knowledge-base/git/public-repos). 

**To install :**

```shell
# assuming you are at /var/www/zaneops
curl https://cdn.zaneops.dev/makefile > Makefile
make setup
make deploy
```

### Git services

We made our first step towards supporting creating services from git repositories, you can now point a public repository 
which contains a `Dockerfile` to ZaneOps and it will build it for you :

<video muted src="https://assets.zaneops.dev/videos/git-services.mp4" alt="Git services" controls />  


### Bulk actions 

You can now select multiple services in one environment and apply bulk actions to them.
<video muted src="https://assets.zaneops.dev/videos/bulk-actions.mp4" alt="Bulk actions" controls />  

### other changes

Logs are now separated from deployments and runtime logs. with runtime logs being all the logs your services produce and deployment logs 
for build and logs produced by ZaneOps.

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/deployment-logs-light.png" alt="deployment logs" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/deployment-logs-dark.png" alt="deployment logs" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/runtime-logs-light.png" alt="runtime logs" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/runtime-logs-dark.png" alt="runtime logs" />

# ZaneOps v1.9

import {Aside} from '@astrojs/starlight/components';

> Release notes: https://github.com/zane-ops/zane-ops/releases/tag/v1.9.0

<span className='text-gray-600 dark:text-gray-400'>20 Apr 2025</span> by [**Fred KISSIE**](https://github.com/Fredkiss3)

Today we release zaneOps v1.9 introducing not 1, not 2, but [3 new builders](/knowledge-base/builders/nixpacks-builder) for your git services!


**To install :**

1. via the UI : 
    <img className="block dark:hidden" src="https://assets.zaneops.dev/images/new-version-toast-light.png" alt="clone environment modal" />
    <img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/new-version-toast-dark.png" alt="clone environment modal" />

    <img className="block dark:hidden" src="https://assets.zaneops.dev/images/new-version-modal-light.png" alt="project environments page" />
    <img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/new-version-modal-dark.png" alt="project environments page" />


3. via the shell :
    ```shell
    # assuming you are at /var/www/zaneops
    curl https://cdn.zaneops.dev/makefile > Makefile
    make setup
    make deploy
    ```

### Nixpacks builder

[Nixpacks](https://nixpacks.com) is an open source tool developped by [railway](https://railway.app) that automatically detects your stack, language or framework
and produce a Dockerfile for building your application. 

With this, when you want to deploy a new service, no need to specify a `Dockerfile` when deploying a service from a git repository, 
whether it is a next.js web application, a Svelte SPA or a Django backend API, it will automatically detect it for you. 

<video src='https://assets.zaneops.dev/videos/nixpacks-ssr.mp4' muted controls alt="Nixpacks SSR" />

#### Bonus: static websites

In some cases, you might want to deploy a statically generated websites. 
You can check static website checkbox when creating your service or in your service settings.


<video src='https://assets.zaneops.dev/videos/nixpacks-static.mp4' muted controls alt="Nixpacks static" />

### Railpack builder

[Railpack](https://railpack.com) is the new version of Nixpacks by Railway, still open source. The benefits over Nixpacks are 
faster builds and smaller image sizes. The railpack builder support all the same options as the Nixpacks builder. 

As of now the railpack builder is in **bêta** as a v1 of railpack hasn't been released yet. 

<video src='https://assets.zaneops.dev/videos/railpack-builder.mp4' muted controls alt="Railpack" />

### Static directory builder

In ZaneOps, you can deploy a simple HTML/CSS/JS pre-built static website, 
it will be deployed as a simple [Caddy](https://caddyserver.com) with alpine docker container.

<video src='https://assets.zaneops.dev/videos/static-dir-builder.mp4' muted controls alt="Static directory builder" />

### Other changes 

You can now deploy multiple services at once in the project details page:
  ![Bulk deploy services](https://assets.zaneops.dev/images/bulk-deploy.png)

# Configuring Domains and DNS Records for ZaneOps

import {Aside} from '@astrojs/starlight/components';

ZaneOps requires specific DNS records to be set up for your domains. The primary environment variables related to domains are:

- [`ROOT_DOMAIN`](#root_domain): Used to generate subdomains for deployed web apps.
- [`ZANE_APP_DOMAIN`](#zane_app_domain): The domain where the ZaneOps dashboard will be accessible after deployment. It can be the same as `ROOT_DOMAIN`.

<Aside type="tip" title="Important">
You can use any domain you want for services created in ZaneOps, you are not restricted to `ROOT_DOMAIN` or `ZANE_APP_DOMAIN`.

For example, your `ROOT_DOMAIN` might be [zaneops.dev](//zaneops.dev) and your `ZANE_APP_DOMAIN` [admin.zaneops.dev](//admin.zaneops.dev), but a service can still use a domain like [mysupersaas.com](//mysupersaas.com).
</Aside>

### Required DNS Records

You need to add the following records in your DNS provider:

```txt
*     IN  A    <your-server-ip>       # Wildcard Subdomain (`*.<ROOT_DOMAIN>`, to support subdomains dynamically)
app   IN  A    <your-server-ip>       # ZANE_APP_DOMAIN
```

On [cloudflare](//cloudflare.com), it looks like this : 

![example DNS records on cloudflare](https://assets.zaneops.dev/images/dns-records-for-zane-domains.png)

### Verifying DNS Records

Ensure that these records are correctly propagated by checking them with a DNS lookup tool such as `dig` or `nslookup` : 

```shell
# Using `dig`
dig +short admin.zaneops.dev A

# Using `nslookup`
nslookup admin.zaneops.dev
```


#### **`ROOT_DOMAIN`**

This variable is used for generating subdomains for your services. 

for example if your root domain is [zaneops.dev](https://zaneops.dev), urls for your services will be generated 
as [project-service-randomid.zaneops.dev](//project-service-randomid.zaneops.dev). This variable is also used for generating unique urls for your deployments.

In the dashboard, this is what is used when you leave the `domain` field empty when you add urls for your service : 

<img className="block" src="https://assets.zaneops.dev/images/url-with-root-domain.png" alt="Screenshot showing the usage of ROOT_DOMAIN" />

<Aside type='note' title='Default value'>
By default the setup script of zaneops generate a [sslip.io](https://sslip.io) domain based on the IP of your server (ex: https://198-19-249-134.sslip.io),
and you can change this at any moment. 
</Aside>



#### **`ZANE_APP_DOMAIN`**

This variable corresponds to the domain where the zaneops dashboard will be accessible. 
You can safely set this variable to the same value as the `ROOT_DOMAIN`, the domain itself is not used for anything else.

<Aside type='note' title='Default value'>
By default, the setup script of ZaneOps will generate this with the same value as `ROOT_DOMAIN`.
</Aside>

## Disabling SSL 

By default zaneops, will only expose the port `443` to the public, with all services served over https. 
But in some cases where you have another proxy on top on your server (ex: [Cloudflare tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/), [Cloudflare proxy](https://developers.cloudflare.com/dns/proxy-status/)),
 which handles SSL for you, you might want to disable SSL on your server. 

- To enable HTTP, you can modify the `.env` file and update the `MODE` variable to `http` :

    ```shell
    # /var/www/zaneops/.env
    # ... other env variables
    MODE=http
    ```

- You will need to restart your zaneops instance :

    ```shell
    make stop # stop zaneops and all the services managed by it
    make deploy # start zaneops again
    ``` 
 
<Aside type="note" title="Server without a public IP">
In some cases, you might want to disable secure connection to your server, if you are testing on a non production server
which doesn't have a public IP (meaning you can only access your server with `http://`).

For that you will need to modify the `__DANGEROUS_ALLOW_HTTP_SESSION` environment variable in your `.env` file to `"true"`.
However, this is strongly discouraged to use in production, 
as it allows for connecting to your dashboard using non secure cookies.

This can be perfectly OK though, for use-cases like using ZaneOps to host apps on a local network not accessible from the internet. 
</Aside>

## Using Cloudflare tunnel

[Cloudflare tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) is a popular way to host applications without needing 
to expose your server IP to the internet. 

For hosting zaneops behing cloudflare tunnel, you will need to : 
1. [Disable ssl](#disabling-ssl)
2. Add the records on the public hostname tab on your tunnel instance, all forwarded to http://127.0.0.1:80 :  
   ![Cloudflare tunnel public hostnames](https://assets.zaneops.dev/images/dns-records-for-cf-tunnel.png)

# Welcome

import LandingPage from "../../components/LandingPage.astro";

<LandingPage />

# Installing ZaneOps

import {FileTree, Steps, Aside} from '@astrojs/starlight/components';


## Quick-start

You can install ZaneOps with one script:

```shell
curl -fsSL https://cdn.zaneops.dev/install.sh | sudo bash
```


## System requirements

ZaneOps is designed to operate on a variety of environments. For optimal performance, we recommend these requirements for running zaneops and your services :

- **CPUs:** 2 cores 
- **Memory (RAM):** 2 GB
- **Disk:** At least 30 GB of free space


Keep in mind that this depends mainly on the resource requirements for your services, if you are running a lot of services that are resource intensive, 
you might need a bigger server, if you want to host static sites though, these requirements will totally be well enough.

## Supported OS and architectures

As of now ZaneOps has been tested on these platforms : 

- Debian-based Linux distributions (e.g., Debian, Ubuntu)
- Red Hat-based distributions (e.g., CentOS, Fedora)
- Raspberry Pi OS 64-bit (Raspbian) using ARM architecture
- MacOs Mx series
- Alpine Linux
- NixOS
- Arch Linux

We can't assure you that zaneops will work on other platforms, but if you try and succeed, we are more than happy to add 
it to our supported OS.



## Manual installation

### Prerequisites

- Ensure you have [Docker >= `v27.0.3`](https://docs.docker.com/engine/install/) installed and are using a Unix-based machine. It's recommended to use the latest version of Docker to avoid compatibility issues.
- Ensure you have `make`, `curl`, `jq` and `openssl` installed : 
  ```shell
  # on Debian based distributions
  sudo apt install make curl jq openssl

  # on Red Hat-based distributions
  sudo dnf install -y make curl jq openssl

  # on Alpine Linux
  sudo apk add make curl jq openssl

  # on NixOS
  nix-shell -p gnumake curl jq openssl

  # on Arch Linux
  sudo pacman -S --noconfirm make curl jq openssl

  # on Mac
  brew install make curl jq openssl
  ```

<Steps>
1. **Initialize Docker Swarm**:

    ```shell
    docker swarm init --advertise-addr <MANAGER_IP>
    ```

    <Aside type="note">
    `MANAGER_IP` is the IP address of your server:
    - You can use your server's public IP.
    - If you have private networking, use the private IP (e.g., **10.0.0.x**).
    - If you are  installing locally ([see instructions below](#installing-locally)), use **127.0.0.1**.
    </Aside>

2. **Create the installation directory**:

    Choose a directory for ZaneOps. This guide uses `/var/www/zaneops`:

    ```shell
    mkdir -p /var/www/zaneops 
    cd /var/www/zaneops
    ```

3. **Download the makefile for the project**:

    ```shell
    curl https://cdn.zaneops.dev/makefile > Makefile
    ```
    The source code for this file is available [on github](https://github.com/zane-ops/zane-ops/blob/main/deploy.mk).



4. **Launch the setup process**:

    ```shell
    make setup
    ```

    After this step, your directory structure should look like this:

    <FileTree>

    - zaneops
        - .fluentd/
        - temporalio/
        - docker-stack.prod-http.yaml
        - docker-stack.prod.yaml
        - .env
        - fluent.conf
        - Makefile

    </FileTree>

5. **Review environment variables in `.env`** :
    The setup process will generate sane defaults for environment variables, the main variables you might want 
    to modify are `ROOT_DOMAIN` and `ZANE_APP_DOMAIN` and they can be set to the same value if desired. See [How to configure DNS records for ZaneOps ?](/configuring-zaneops)
    
    ```shell
    # /var/www/zaneops/.env
    # ...other variables 
    ROOT_DOMAIN="<YOUR-IP>.sslip.io" # Root domain for generating app subdomains
    ZANE_APP_DOMAIN="<YOUR-IP>.sslip.io" # Domain for ZaneOps dashboard
    ```

6. **Start ZaneOps**:

    ```shell
    make deploy
    ```


7. Access the dashboard by connecting to the domain specified in `ZANE_APP_DOMAIN` in the `.env` file. Once the app is up, you will 
   see a **welcome** page asking you to create your first user :
   
   <img className="block dark:hidden" src="https://assets.zaneops.dev/images/create-user-light.png" alt="onboarding page with a form for creating the first user" />
   <img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/create-user-dark.png" alt="onboarding page with a form for creating the first user" />
   
   Alternatively, you can create your first user by running this command in the terminal :
   ```shell
   make create-user
   ```
   
   <Aside type="note" title='Installing locally'>
    Please [continue with the instructions below](#installing-locally) if you are installing ZaneOps locally.
   </Aside>

</Steps>


### Installing Locally 

ZaneOps can be installed locally with minimal configuration changes. 
To do this :
- keep the `ZANE_APP_DOMAIN` and `ROOT_DOMAIN` environment variables set to http://127-0-0-1.sslip.io :

  ```shell
  # /var/www/zaneops/.env
  # ... other env variables
  ZANE_APP_DOMAIN="127-0-0-1.sslip.io"
  ROOT_DOMAIN="127-0-0-1.sslip.io"
  ```
- add the `__DANGEROUS_ALLOW_HTTP_SESSION` environment variable, and update the `MODE` variable to open the port `80` :

  ```shell
  # /var/www/zaneops/.env
  # ... other env variables
  MODE=http
  __DANGEROUS_ALLOW_HTTP_SESSION="true"
  ```
- be sure to top zaneops first :

    ```shell
    make stop
    ``` 

- run the `deploy` command : 
  
  ```shell
  make deploy
  ```
- You can now access zaneops dashboard at http://127-0-0-1.sslip.io

  <Aside type="caution" title="__DANGEROUS_ALLOW_HTTP_SESSION">
  You can enable the `__DANGEROUS_ALLOW_HTTP_SESSION` environment variable in production to access your ZaneOps instance over HTTP.
  However, this is strongly discouraged, as it allows for connecting to your dashboard using non secure cookies.

  [See here](/configuring-zaneops#disabling-ssl) for more info.
  </Aside>


### Environment Variables Explained

1. `IMAGE_VERSION`: Specifies the ZaneOps version to install.
2. `ZANE_APP_DIRECTORY`: Defines the directory where ZaneOps will be installed.
3. `ZANE_DB_USER` / `ZANE_DB_PASSWORD`: Credentials for connecting to the database.
4. `DJANGO_SECRET_KEY`: Used by the API for various security functions, such as hashing user session tokens. Generate a secure key with at least 64 characters using a tool like [openssl](https://github.com/openssl/openssl) (e.g., `openssl rand -base64 64`).
5. `ROOT_DOMAIN`: Used to generate subdomains for deployed web apps, e.g., `my-web-app.127-0-0-1.sslip.io`. The root domain itself can also host the dashboard if desired.
6. `ZANE_APP_DOMAIN`: The domain where the ZaneOps dashboard will be accessible after deployment. It can be the same as `ROOT_DOMAIN`
7. `MODE` : the mode in which to deploy your zaneops instance, should be either `https` or  `http`, if you change this to `http`, it enables the port `80` on your instance, beware as it can be source of security vulnerabilities.
8. `__DANGEROUS_ALLOW_HTTP_SESSION` : allow for authenticating to zaneops using a domain on `http://`

# What is ZaneOps ?

import { Card, CardGrid, Aside } from '@astrojs/starlight/components';

ZaneOps is a **self-hosted, beautiful and fast** platform for deploying and managing static sites, web apps, databases, services (like Supabase, WordPress, Ghost), workers, or anything else you need. Whether you're launching a startup or managing an enterprise.  

It is a **free** and **open-source** alternative to platforms like **Heroku**, **Railway**, and **Render**, leveraging the **scalability** of [Docker Swarm](https://docs.docker.com/engine/swarm/) and the **flexibility** of [Caddy](https://caddyserver.com/).  

## Why Zaneops ?

### Exhibit A: It Looks Beautiful

Who said that open source projects had to look bad ? 👀

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/login-light.png" alt="Login page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/login-dark.png" alt="Login page" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/project-detail-light.png" alt="Project detail page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/project-detail-dark.png" alt="Project detail page" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/service-detail-light.png" alt="Service detail page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/service-detail-dark.png" alt="Service detail page" />


<Aside type="note" title="And more...">
more screenshots [here](/screenshots)
</Aside>



### Exhibit B: It Is Blazingly Fast!  

> Yes, this is the app running in production!

<video src="https://assets.zaneops.dev/videos/zaneops-is-fast.mp4" alt="" muted controls />

### Exhibit C: Packed with Features  

ZaneOps is loaded with powerful features:


<CardGrid >
    <Card title="Zero-Downtime Deployments">
        Deploying a new version doesn’t require stopping the old one,
        ensuring uninterrupted uptime.
    </Card>
    <Card title="Preview environments">
        Create preview deployments from Gitlab and GitHub repositories. Test & Preview your features before sending them to production.
        Either trigger them from API or from a pull request.
    </Card>
    <Card title="Free SSL Certificates">
        Every domain-custom or auto-generated gets a free SSL certificate that is automatically renewed on expiration.
    </Card>
    
    <Card title="Automatic Git deploys">
        ZaneOps can deploy your app everytime you do a push to your repository, 
        reducing the need to do manual CD.
    </Card>
        <Card title="Magic File Mounts"> 
        Override the content of any file inside your services using
        [configuration files](/knowledge-base/config-files).
    </Card>
    <Card title="HTTP Logs"> 
        You can [view and analyze](/screenshots#http-logs-page)
        all HTTP requests made to your service over time.
    </Card>
    <Card title="Built-in Monitoring"> 
        Automatic **health checks**, detailed **metrics**, and real-time **logs**
        for each service and deployment.
    </Card>
    <Card title="Advanced URL Support"> 
        Supports **wildcard URLs**, multiple services sharing the same domain
        (e.g., frontend on `domain.com/` and API on `domain.com/api`),
        **URL redirections** (permanent, temporary), and multiple URLs per service.
    </Card>
    <Card title="Git-Like Configuration System"> 
        [Review and validate](/screenshots#changes-modal) changes before deploying new versions.
    </Card>
    <Card title="Deployment Webhooks"> 
        Easily set up [CI/CD workflows](/tutorials/react-router/#setting-up-continuous-deployment).
    </Card>
    <Card title="Resource Limits"> 
        Set **maximum memory (RAM) and CPU usage** per service.
    </Card>
    <Card title="Flexible Volume Management"> 
        Attach as many volumes as needed and/or bind **them to local paths**.
    </Card>

    <Card title="Easy Environment Variable Management"> 
        Manage your [environment variables](/screenshots#service-environment-variables-page),
        export them as a `.env` file, or import them easily.
    </Card>
    <Card title="Flexible environments Management">
        Create and clone [environments](/knowledge-base/environments) from any other environment, 
        you can even choose to deploy automatically when you clone an env. it just works !
    </Card>
</CardGrid>

# Anonymous Telemetry

> Since [**v1.10**](/changelog/v110)

## How does it work?

The anonymous telemetry feature helps us better understand how ZaneOps is actually used in production environments.

It works by sending a simple `PING` request at most every 30 minutes to the ZaneOps CDN ([cdn.zaneops.dev](https://cdn.zaneops.dev)).

The complete source code of the CDN can be found [here](https://github.com/zane-ops/cdn/tree/main/src/index.ts).

## How to disable?

You can easily disable anonymous telemetry by modifying the environment variable in your `.env` file:

```shell
# /var/www/zaneops/.env
TELEMETRY_ENABLED=false # or true
```

## What does it collect?

When a PING request is sent to the CDN, we capture the requester's IP address and hash it twice: first using a SHA-256 hash, then a second time using HMAC-256 with a secret key that only the CDN knows. This process is irreversible, ensuring the data remains completely anonymous.

You can review the hashing implementation [here](https://github.com/zane-ops/cdn/blob/ab602e62e7013b3dc55c60eb29b5312e847c93fc/src/index.ts#L67-L79).

# Automated jobs

import {Aside} from '@astrojs/starlight/components';

ZaneOps regularly runs the following automated jobs:

- Log collection every **5 seconds**
- Metrics collection for each service every **30 seconds**
- Automated Docker system cleanup every **4 hours**
- Log and metrics cleanup every **day at midnight**

## Log & metrics retention policy

To optimize storage on your server, the log and metrics cleanup job:

- Deletes logs older than **14 days** (2 weeks)
- Deletes metrics older than **30 days**

Only **application logs** are deleted; **HTTP logs** are retained.


## Automated Docker System Cleanup

The automated system cleanup runs every **4 hours** and performs the following steps in order:

1. Remove all unused images
2. Remove all unused containers
3. Remove all unused volumes (except those managed by ZaneOps)
4. Remove all unused networks

You can find the source code for the system cleanup job [here](https://github.com/zane-ops/zane-ops/blob/ee40dc332427b332d7179d3f22f5bd43e5021299/backend/zane_api/temporal/workflows.py#L666-L705).

<Aside type="tip" title="Good to Know">
This job runs **only** when no deployments are in progress.
</Aside>

# Overview

import {Aside} from '@astrojs/starlight/components';

> Introduced in [**v1.8.0**](/changelog/v18)

Builders are tools used to package [Git services](/knowledge-base/git) into deployable containers.
They either detect or generate a **Dockerfile**, then build your application using `docker build`.

Supported builders include:
- [Nixpacks](./nixpacks-builder)
- [Railpack](./railpack-builder)
- [Dockerfile](./dockerfile-builder)
- [Static directory](./static-dir-builder)

<Aside type="caution" title='Docker build resource usage'>
The Docker build process can consume up to 100% of your server's resources, potentially slowing it to a crawl.
Make sure your server is powerful enough to handle it.

ZaneOps will try to limit the resource usage of the build process to **~33%** to avoid that, but 
it is not guaranteed to work for every builder.
</Aside>


#### Accessing other services

When building your application, all the services from the same project are available, you can reference them using their network alias.

# Dockerfile Builder

import {Aside} from '@astrojs/starlight/components';

> Introduced in [**v1.8.0**](/changelog/v18)

<Aside type="caution" title='Docker build resource usage'>
The Docker build process can consume up to 100% of your server's resources, potentially slowing it to a crawl.
Make sure your server is powerful enough to handle it.
</Aside>
<Aside type="tip" title='Network access'>
    When building your application, the build process will happen inside of the same network as your service,
    allowing you to access services inside of the same network.
</Aside>


You can deploy services from a git repository if you have a `Dockerfile` inside of it.

![Dockerfile settings](https://assets.zaneops.dev/images/dockerfile-builder-settings.png)

- You can specify a **build context directory** for where the dockerfile should build your application, relative to the root of your repository
- You can specify the path of your **Dockerfile**, relative to the root of your repository
- And you can specify a **Docker build stage target** if you build your image using a multi-stage build and want to stop at a certain step of the build

### Environment variables

When building your application, ZaneOps will put all the environment variables 
that need to be passed to the build process into an `.env` file at the root of the **build context directory** as well as 
pass them as [build-args](https://docs.docker.com/build/building/variables/#arg-usage-example) to the build process.

# Nixpacks Builder

import {Aside} from '@astrojs/starlight/components';

> Introduced in [**v1.9.0**](/changelog/v19)

<Aside type="caution" title='Docker build resource usage'>
The Docker build process can consume up to 100% of your server's resources, potentially slowing it to a crawl.
Make sure your server is powerful enough to handle it.
</Aside>

<Aside type="tip" title='Network access'>
    When building your application, the build process will happen inside of the same network as your service,
    allowing you to access services inside of the same network.
</Aside>

[Nixpacks](https://nixpacks.com) is an open source tool developped by [railway](https://railway.app) that automatically detects your stack, language or framework
and produce a Dockerfile for building your application. 

With this, when you want to deploy a new service, no need to specify a `Dockerfile` when deploying a service from a git repository, 
whether it is a next.js web application, a Svelte SPA or a Django backend API, it will automatically detect it for you. 


## How to create a service with nixpacks

You can specify the nixpacks builder when creating your service or modify the builder at any moment in the service's settings. 

![Create a service with Nixpacks builder](https://assets.zaneops.dev/images/create-git-service-nixpacks-builder.png)


- You need to specify a **build directory**, where nixpacks will detect and build your application, relative to the root of your repository
- You can specify custom **install**, **build** and **start** commands to configure nixpacks and override the auto-generated 
  commands by nixpacks 
    ![Nixpacks settings](https://assets.zaneops.dev/images/nixpacks-builder.png)


## Static websites

The nixpacks builder support deploying static websites, when deploying a static website with ZaneOps, it will be built as a service using a  [caddy on alpine](https://hub.docker.com/_/caddy) image,
with your build assets copied exposed as a file server.
For that you need to check the static website checkbox and specify a publish directory relative to the build directory.

- You can also specify the path for a custom not found page, relative to the **published directory**, used for handling all 404 errors.
- If your app is a **Single Page Application (SPA)**, you can check the box and specify the location of **index.html** page to redirect requests to, 
  the Not found page is ignored as all requests will be sent to the **index.html** page instead.

### Overriding the default Caddyfile

When updating your options in the UI, ZaneOps will show you a preview of the generated [Caddyfile](https://caddyserver.com/docs/caddyfile) that will be used to expose the static 
assets generated by your app.
![Nixpacks static settings](https://assets.zaneops.dev/images/nixpacks-builder-static.png)

You can override the generated file by providing a Caddyfile at the root of your **build directory**. 
When specifying this, ZaneOps use it over the default generated one. 
With this you can add things like caching or simple HTTP basic authentication to your static websites. 

When specifying a custom Caddyfile, you can use :
- the environment variable **`$PUBLIC_ROOT`** as the root for static files
- the environment variable **`$PORT`** as the port for exposing your app

Here is A fully working example of a custom Caddyfile : 
```ini
# ./Caddyfile
# expose your app to $PORT and use 80 if undefined
:{$PORT:80} {
    # Set the root directory for static files
    root * {$PUBLIC_ROOT}
    # Serve static files 
    file_server
    # Add `cache-control` header to static assets, images and videos
    @assets {
        path_regexp assets \.(css|js|png|jpg|jpeg|gif|svg|woff|woff2|eot|ttf|otf|mp4)$
    }
    header @assets Cache-Control "public, max-age=31536000, immutable"
    # For all 404 errors, show a custom page
    handle_errors {
        @404 {
            expression {http.error.status_code} == 404
        }
        rewrite @404 ./404/index.html
        file_server
    }
}
```


## Configuring nixpacks

To configure nixpacks, you can :

1. Alongside the custom **install/build/start** commands, you can customize nixpacks by passing all environment 
   variables supported by nixpacks, they all starts with `NIXPACKS_`.
   

   You can find the common Nixpacks environment variables here : https://nixpacks.com/docs/configuration/environment 
   
   For specific environment variables related to the provider detected by Nixpacks, you will need to refer to the docs for that provider. 
   For ex, you can override the node version with `NIXPACKS_NODE_VERSION` for the `Node` provider : https://nixpacks.com/docs/providers/node 

   Here is an example of environment variables you can add : 
   ```shell
   NIXPACKS_APT_PACKAGES="wget,git" # install wget & git with apt-get 
   NIXPACKS_NODE_VERSION="22.x" # install node `22`
   ```
2. You can add a custom [nixpacks.toml](https://nixpacks.com/docs/configuration/file) configuration file, at the root of your **build directory** : 
   
   With this you can add more steps to the build process, customize the different commands, and even change the auto-detected provider by nixpacks.

   Here's an example of a nixpacks configuration that : 
   - adds a new step
   - customize the build command 
   - and install custom apt packages
   ```toml
   # ./nixpacks.toml
   [phases.setup]
    aptPkgs = ["...", "wget", "git"]   # Install git & wget packages with apt-get

   [phases.lint] # add new `lint` step
    cmds = ["yarn run lint"]
    dependsOn = ["install"]

   [phases.build] 
    dependsOn = ["...", "lint"] # build should come after `lint`
    cmds = ["pnpm run db:generate && pnpm run build"]
   ```

    <Aside type="note" title='How to customize nixpacks.toml'>
     See here for more info about how to customize the config file : https://nixpacks.com/docs/guides/configuring-builds
   </Aside>

## Default Environment variables

when building with nixpacks, we will pass a default environment variable `FORCE_COLOR=true` for coloring build outputs.

# Railpack Builder

import {Aside} from '@astrojs/starlight/components';


> Introduced in [**v1.9.0**](/changelog/v19)

<Aside type="caution" title='Docker build resource usage'>
The Docker build process can consume up to 100% of your server's resources, potentially slowing it to a crawl.
Make sure your server is powerful enough to handle it.
</Aside>
<Aside type="tip" title='Network access'>
    When building your application, the build process will happen inside of the same network as your service,
    allowing you to access services inside of the same network.
</Aside>

[Railpack](https://railpack.com) is the new version of [Nixpacks](/knowledge-base/builders/nixpacks-builder/) by Railway, still open source. The benefits over Nixpacks are 
faster builds and smaller image sizes. The Railpack builder support all the same options as the Nixpacks builder. 

The Railpack builder is in **bêta** for now, as a **v1** of railpack hasn't been released yet. 

## How to create a service with railpack

You can specify the Railpack builder when creating your service or modify the builder at any moment in the service's settings. 

![Create a service with Railpack builder](https://assets.zaneops.dev/images/create-git-service-railpack-builder.png)

- You need to specify a **build directory**, where Railpack will detect and build your application, relative to the root of your repository
- You can specify custom **install**, **build** and **start** commands to configure Railpack and override the auto-generated 
  commands by Railpack 
    ![Railpack settings](https://assets.zaneops.dev/images/railpack-builder.png)

## Static websites

The Railpack builder support deploying static websites, when deploying a static website with ZaneOps, it will be built as a service using a [caddy on alpine](https://hub.docker.com/_/caddy) image,
with your build assets copied exposed as a file server.
For that you need to check the static website checkbox and specify a publish directory relative to the build directory.

- You can also specify the path for a custom not found page, relative to the **published directory**, used for handling all 404 errors.
- If your app is a **Single Page Application (SPA)**, you can check the box and specify the location of **index.html** page to redirect requests to, 
  the Not found page is ignored as all requests will be sent to the **index.html** page instead.

### Overriding the default Caddyfile

When updating your options in the UI, ZaneOps will show you a preview of the generated [Caddyfile](https://caddyserver.com/docs/caddyfile) that will be used to expose the static 
assets generated by your app.
![Nixpacks static settings](https://assets.zaneops.dev/images/nixpacks-builder-static.png)

You can override the generated file by providing a Caddyfile at the root of your **build directory**. 
When specifying this, ZaneOps use it over the default generated one. 
With this you can add things like caching or simple HTTP basic authentication to your static websites. 

When specifying a custom Caddyfile, you can use :
- the environment variable **`$PUBLIC_ROOT`** as the root for static files
- the environment variable **`$PORT`** as the port for exposing your app


Here is A fully working example of a custom Caddyfile : 
```ini
# ./Caddyfile
# expose your app to $PORT and use 80 if undefined
:{$PORT:80} {
    # Set the root directory for static files
    root * {$PUBLIC_ROOT}
    # Serve static files 
    file_server
    # Add `cache-control` header to static assets, images and videos
    @assets {
        path_regexp assets \.(css|js|png|jpg|jpeg|gif|svg|woff|woff2|eot|ttf|otf|mp4)$
    }
    header @assets Cache-Control "public, max-age=31536000, immutable"
    # For all 404 errors, show a custom page
    handle_errors {
        @404 {
            expression {http.error.status_code} == 404
        }
        rewrite @404 ./404/index.html
        file_server
    }
}
```



## Configuring railpack

Alongside the custom **install/build/start** commands, you can configure railpack by passing all environment 
variables supported by railpack, they all starts with `RAILPACK_`.


You can find the common Railpack environment variables here : https://railpack.com/config/environment-variables

For specific environment variables related to the provider detected by Railpack, you will need to refer to the docs for that provider. 
For ex, you can override the node version with `RAILPACK_BUN_VERSION` for the `Node` provider : https://railpack.com/languages/node

Here is an example of environment variables you can add : 
```shell
RAILPACK_DEPLOY_APT_PACKAGES="wget,git" # install wget & git with apt-get and persist it at build time
RAILPACK_BUN_VERSION=" 1.2.10" # install bun `1.2.10`
```


## Default Environment variables

when building with nixpacks, we will pass a default environment variable `FORCE_COLOR=true` for coloring build outputs.

# Static directory Builder

> Introduced in [**v1.9.0**](/changelog/v19)

With ZaneOps you can deploy **pre-built HTML/CSS/JS** websites using the static directory builder. 
It will be deployed using using a [caddy on alpine](https://hub.docker.com/_/caddy) image.


- You can specify the **directory to publish** 
- You can specify a custom **not found page** 
- You can specify if the page **is an SPA** and where to redirect all requests to

### Overriding the default Caddyfile

When updating your options in the UI, ZaneOps will show you a preview of the generated [Caddyfile](https://caddyserver.com/docs/caddyfile) 
that will be used to expose your app.
![Static directory service settings](https://assets.zaneops.dev/images/static-dir-builder.png)

You can override the generated file by providing a Caddyfile at the root of your **publish directory**. 
When specifying this, ZaneOps use it over the default generated one. 
With this you can add things like caching or simple HTTP basic authentication to your static websites. 

When specifying a custom Caddyfile, you can use :
- the environment variable **`$PUBLIC_ROOT`** as the root for static files
- the environment variable **`$PORT`** as the port for exposing your app

Here is A fully working example of a custom Caddyfile : 
```ini
# ./Caddyfile
# expose your app to $PORT and use 80 if undefined
:{$PORT:80} {
    # Set the root directory for static files
    root * {$PUBLIC_ROOT}
    # Serve static files 
    file_server
    # Add `cache-control` header to static assets, images and videos
    @assets {
        path_regexp assets \.(css|js|png|jpg|jpeg|gif|svg|woff|woff2|eot|ttf|otf|mp4)$
    }
    header @assets Cache-Control "public, max-age=31536000, immutable"
    # For all 404 errors, show a custom page
    handle_errors {
        @404 {
            expression {http.error.status_code} == 404
        }
        rewrite @404 ./404/index.html
        file_server
    }
}
```

# Config files

import {Aside} from '@astrojs/starlight/components';


> Since [**v1.0**](/changelog/announcing-v1)

Config files allow you to create or overwrite any arbitrary files within your services.

![Config file content](https://assets.zaneops.dev/images/tuto-bun-fn-config-file.png)

- You need specify a **mount path** for where the file should be located
- You can choose a **language** for syntax highlighting in the UI
- And you can set a **name** to show in the UI

# Overview

import {Steps, Aside} from '@astrojs/starlight/components';

> Introduced in [**v1.13.0**](/changelog/v113)

ZaneOps supports deploying multi-container applications from `docker-compose.yml` files, with built-in blue/green deployments, web routing, and more.

In ZaneOps, these are called **Compose Stacks**.


### How does it work ?

Under the hood, compose files are deployed as [Docker stacks](https://docs.docker.com/reference/cli/docker/stack/) via Docker Swarm, not plain `docker compose up`.

This is an important distinction: Swarm is what enables ZaneOps to orchestrate rolling blue/green deployments, whereas standard Docker Compose has no concept of that.


![Compose stack deployment logs](/images/deploy-compose-stack-logs.png)

---

### Ways to create a compose stack

There are three ways to create a compose stack in ZaneOps:

- **From a `docker-compose.yml` file**: paste your own compose file directly. [See below](#how-to-create-and-deploy-a-compose-stack).
- **From a curated template**: pick from ZaneOps' library of ready-to-deploy stacks (Postgres, Redis, WordPress, and more) to get a pre-filled compose file. [**Browse all templates ↗**](/templates).
   ![template list](/images/create-from-template-list.png)
   ![Deploy n8n](/images/deploy-n8n-on-zaneops.png)
- **From a Dokploy template** *(experimental)*: paste a base64-encoded Dokploy template and ZaneOps converts it to a native compose file automatically. [Learn more](./01-templates#dokploy-template-migration).
   ![Create dokploy template](/images/create-from-dokploy.png)

<Aside>
All compose stacks are backed by a `docker-compose.yml` file. The three creation methods differ only in how that file is initially populated. You can edit the compose file at any time after creation, regardless of how the stack was created.
</Aside>

---

### How to create and deploy a Compose Stack

<Steps>
1. In the ZaneOps dashboard go to your project and select **New > Compose Stack**
    ![Select new compose stack](/images/new-compose-stack.png)
2. Select **from docker-compose.yml**
    ![Create from docker-compose.yml](/images/create-from-compose-yml.png)
3. Paste your compose file
    ![Paste docker-compose.yml](/images/paste-compose-yml.png)
4. Click **Create** and  **Deploy**
    ![Deploy compose stack](/images/deploy-compose-stack.png)
5. Your services are now running
    ![Docker compose service list](/images/docker-compose-service-list.png)
</Steps>

---

### Compose file syntax

ZaneOps adds some flavor on top of the normal compose file.

- **Template expressions** for generating secrets, domains, and service aliases
  ```yaml title="docker-compose.yml"
  x-zane-env:
    DB_PASSWORD: "{{ generate_password | 32 }}"
    DB_NAME: "{{ generate_slug }}"

  services:
    db:
      image: postgres:16
      environment:
        POSTGRES_PASSWORD: ${DB_PASSWORD}
        POSTGRES_DB: ${DB_NAME}
  ```
- **Label-based routing** instead of port mappings for exposing services to the web
  ```yaml title="docker-compose.yml"
  services:
    web:
      image: nginx:alpine
      deploy:
        labels:
          zane.http.routes.0.domain: "myapp.com"
          zane.http.routes.0.port: "80"
  ```
- **Variable interpolation** using `${VAR}` syntax in env vars and configs
- **Config versioning** for inline configuration files

See the [Compose file syntax reference](./02-compose-file-reference) for the full details.

# Templates

import {Steps, Aside} from '@astrojs/starlight/components';


> Introduced in [**v1.13.0**](/changelog/v113)

ZaneOps allows you to deploy [Docker Compose Stacks](/knowledge-base/docker-compose/) from preexisting templates. 

There are two kinds: 
- Curated ZaneOps templates (Postgres, Redis, WordPress, and more) 
- Dokploy templates (experimental)

<Aside>
All compose stacks are backed by a `docker-compose.yml` file. The templates only fill in the initial content of the `docker-compose.yml`.
You can edit the compose file at any time after creation, regardless of how the stack was created.
</Aside>


## ZaneOps templates

ZaneOps maintains a curated library of ready-to-deploy templates including Postgres, Redis, WordPress, Plausible, etc. **[Browse all templates ↗](/templates)**

### How to deploy a ZaneOps template

<Steps>
1. In the ZaneOps dashboard go to your project and select **New > Compose Stack**
    ![Select new compose stack](/images/new-compose-stack.png)
2. Select **from ZaneOps template**
    ![Create from ZaneOps](/images/create-from-zaneops-template.png)
3. Search and select your template
    ![Search for plausible template](/images/search-plausible-template.png)
4. Review or modify the compose file, then click **Create** and **Deploy**
    ![Deploy plausible](/images/deploy-plausible-template.png)
5. Once deployed, explore your running services and follow any onboarding steps specific to the template
    ![Plausible stack details](/images/plausible-template-stack-details.png)
    ![Plausible onboarding](/images/plausible-template-onboarding.png)
</Steps>

## Dokploy templates (experimental)

ZaneOps includes an adapter to import templates from Dokploy. 
[Dokploy templates](https://templates.dokploy.com) are base64-encoded JSON containing a compose YAML and a TOML config.

<Aside type='caution' title='Compatibility'>
Not all Dokploy templates are compatible with ZaneOps. 
Some may contain syntax errors or reference outdated configurations. 
If you encounter an issue, please verify the template works on [Dokploy](https://github.com/Dokploy/dokploy) first before opening an issue on ZaneOps.
</Aside>

### How to deploy a dokploy template

<Steps>
1. In the ZaneOps dashboard go to your project and select **New > Compose Stack**
    ![Select new compose stack](/images/new-compose-stack.png)
2. Select **from Dokploy template**
    ![Create from Dokploy](/images/select-dokploy-template.png)
3. Copy and paste your template:

   You can either copy the encoded base64 configuration
    ![Copy Dokploy base64](/images/dokploy-base64-template.png)
    ![Create Dokploy from base64](/images/dokploy-create-from-base64.png)
   Or copy the individual compose file and config 
    ![Copy dokploy docker-compose template](/images/dokploy-compose-template.png)
    ![Create Dokploy from docker-compose](/images/dokploy-create-from-compose.png)
4. Click **Create** and **Deploy**
5. Once deployed, explore your running services and follow any onboarding steps specific to the template
    ![WordPress stack details](/images/wordpress-template-stack-details.png)
    ![WordPress onboarding](/images/wordpress-template-onboarding.png)
</Steps>


### Dokploy Template Migration

ZaneOps includes an adapter to import templates from Dokploy. If you have existing Dokploy templates, here's how to migrate them.

#### Dokploy Template Format

Dokploy templates are base64-encoded JSON containing:
- **compose**: Docker Compose YAML with placeholders
- **config**: TOML with variables, domains, env, and file mounts

Example Dokploy template structure (base64):

```
eyJjb21wb3NlIjogInNlcnZpY2VzOlxuICB3ZWI6XG4gICAgaW1hZ2U6IG5naW54XG4gICAgZW52aXJvbm1lbnQ6XG4gICAgICBQQVNTV09SRDogJHtQQVNTV09SRH1cbiIsICJjb25maWciOiAiW3ZhcmlhYmxlc11cbnBhc3N3b3JkID0gXCIke3Bhc3N3b3JkOjMyfVwiXG5cbltjb25maWcuZW52XVxuUEFTU1dPUkQ9JHtwYXNzd29yZH1cblxuW1tjb25maWcuZG9tYWluc11dXG5zZXJ2aWNlTmFtZSA9IFwid2ViXCJcbmhvc3QgPSBcImV4YW1wbGUuY29tXCJcbnBvcnQgPSA4MFxuIn0=
```

Which is the base64 encoding of this JSON:

```json
{
  "compose": "services:\n  web:\n    image: nginx\n    environment:\n      PASSWORD: ${PASSWORD}\n",
  "config": "[variables]\npassword = \"${password:32}\"\n\n[config.env]\nPASSWORD=${password}\n\n[[config.domains]]\nserviceName = \"web\"\nhost = \"example.com\"\nport = 80\n"
}
```

Which decodes to:

```yaml title="compose.yaml"
services:
  web:
    image: nginx
    environment:
      PASSWORD: ${PASSWORD}
```

```toml title="template.toml"
[variables]
password = "${password:32}"

[config.env]
PASSWORD=${password}

[[config.domains]]
serviceName = "web"
host = "example.com"
port = 80
```

---

#### Placeholder Mapping

Dokploy placeholders are automatically converted to ZaneOps template expressions:

| Dokploy Placeholder | ZaneOps Expression |
| --- | --- |
| `${domain}` | `{{ generate_domain }}` |
| `${email}` | `{{ generate_email }}` |
| `${username}` | `{{ generate_username }}` |
| `${uuid}` | `{{ generate_uuid }}` |
| `${password}`, `${hash}`, `${jwt}` | `{{ generate_password \| 32 }}` |
| `${password:N}`, `${hash:N}`, `${jwt:N}` | `{{ generate_password \| N }}` |
| `${base64}` | `{{ generate_base64 \| 32 }}` |
| `${base64:N}` | `{{ generate_base64 \| N }}` |

---

#### Conversion Process



<Steps>
1. **Decode**: the base64 JSON is decoded into a compose YAML and a TOML config (or used as-is if provided separately)
2. **Placeholder substitution**: Dokploy placeholders (e.g. `${domain}`, `${password:32}`) are replaced with their equivalent ZaneOps template expressions (see [Placeholder mapping](#placeholder-mapping) below)
3. **Process variables**: Extract `[variables]` and `[[config.env]]` section into `x-zane-env`
3. **Domain conversion**: each `[[config.domains]]` entry in the TOML config is converted to ZaneOps routing labels on the matching service
4. **Mount conversion**: each `[[config.mounts]]` entry is converted to an inline Docker config. If no matching mount is found for a `../files/` volume path, the path is converted to a named volume instead
6. **Clean up**: Remove `ports`, `expose`, `restart`
5. **Standard processing**: the resulting compose file goes through the same pipeline as any other ZaneOps compose file: template expressions are evaluated, service names are hashed, networks are injected, and the stack is deployed
</Steps>


---

#### Example Migration

**Dokploy template content**:
```yaml
# compose.yaml
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    environment:
      DB_PASSWORD: ${DB_PASSWORD}
      ADMIN_EMAIL: ${ADMIN_EMAIL}
    volumes:
      - ../files/nginx.conf:/etc/nginx/nginx.conf
```

```toml 
# template.toml
[variables]
main_domain = "${domain}"
db_password = "${password:32}"
admin_email = "${email}"

[[config.domains]]
serviceName = "web"
host = "${main_domain}"
port = 8080

[[config.env]]
DB_PASSWORD = "${db_password}"
ADMIN_EMAIL = "${admin_email}"

[[config.mounts]]
filePath = "nginx.conf"
content = """
server {
  listen 80;
}
"""
```

**Resulting ZaneOps compose.yaml**:
```yaml 
# docker-compose.yml
x-zane-env:
  main_domain: "{{ generate_domain }}"
  db_password: "{{ generate_password | 32 }}"
  admin_email: "{{ generate_email }}"
  DB_PASSWORD: ${db_password}
  ADMIN_EMAIL: ${admin_email}

services:
  web:
    image: nginx:alpine
    environment:
      DB_PASSWORD: ${DB_PASSWORD}
      ADMIN_EMAIL: ${ADMIN_EMAIL}
    configs:
      - source: nginx.conf
        target: /etc/nginx/nginx.conf
    deploy:
      labels:
        zane.http.routes.0.domain: "${main_domain}"
        zane.http.routes.0.port: "8080"
        zane.http.routes.0.base_path: "/"
        zane.http.routes.0.strip_prefix: "false"

configs:
  nginx.conf:
    content: |
      server {
        listen 80;
      }
```

---

#### Mount Processing

Dokploy uses `../files/` prefix for file mounts. The adapter converts these to Docker configs.

**Case 1: Directory mount**

**Dokploy:**
```yaml
# compose.yml
# ... rest of the file
volumes:
  - ../files/clickhouse_config:/etc/clickhouse-server/config.d

```

```toml 
# template.toml
[[config.mounts]]
filePath = "clickhouse_config/logging_rules.xml"
content = "..."

[[config.mounts]]
filePath = "clickhouse_config/network.xml"
content = "..."
```

**ZaneOps result:**
```yaml
# ... rest of the file
# docker-compose.yml
configs:
  - source: logging_rules.xml
    target: /etc/clickhouse-server/config.d/logging_rules.xml
  - source: network.xml
    target: /etc/clickhouse-server/config.d/network.xml

configs:
  logging_rules.xml:
    content: "..."
  network.xml:
    content: "..."
```

---

**Case 2: File mount**

**Dokploy:**
```yaml
# ... rest of the file
# compose.yml
volumes:
  - ../files/nginx.conf:/etc/nginx/nginx.conf:ro
```

```toml
# template.toml
[[config.mounts]]
filePath = "nginx.conf"
content = "..."
```

**ZaneOps result:**
```yaml
# ... rest of the file
# docker-compose.yml
configs:
  - source: nginx.conf
    target: /etc/nginx/nginx.conf

configs:
  nginx.conf:
    content: "..."
```

---

**Case 3: Non-existent path (becomes volume)**

**Dokploy:**
```yaml
# ... rest of the file
# compose.yml
volumes:
  - ../files/data:/app/data
```

If no matching mount exists → converted to named volume:
```yaml
# ... rest of the file
# docker-compose.yml
volumes:
  - data:/app/data

volumes:
  data:
```

#### Ports processing

`ports` entries are removed and replaced with ZaneOps routing labels derived from the `[[config.domains]]` entries in the TOML config.

**Dokploy:**
```yaml
# compose.yml
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
```

```toml
# template.toml
[variables]
main_domain = ${domain}

[[config.domains]]
serviceName = "web"
host = "${main_domain}"
port = 8080
```

**ZaneOps result:**
```yaml
# docker-compose.yml
x-zane-env:
  main_domain: '{{ generate_domain }}'

services:
  web:
    image: nginx:alpine
    deploy:
      labels:
        zane.http.routes.0.domain: "${main_domain}"
        zane.http.routes.0.port: "8080"
```

#### `depends_on`

The dict form of `depends_on` is converted to a plain list, since Docker Swarm only supports the list form. All `condition` values are dropped.

**Dokploy:**
```yaml
# compose.yml
depends_on:
  rybbit_clickhouse:
    condition: service_healthy
  rybbit_postgres:
    condition: service_started
```

**ZaneOps result:**
```yaml
# docker-compose.yml
depends_on:
  - rybbit_clickhouse
  - rybbit_postgres
```

---

#### Self-referencing variables in `config.env`

If a `config.env` entry references itself (e.g. `KEY = "${KEY}"`), the adapter ignores it and keeps the original template expression from `[variables]` instead. Cross-references and new values are kept as-is.

**Dokploy:**
```toml
# template.toml
[variables]
KENER_SECRET_KEY = "${password:64}"
DB_PASSWORD = "${password:32}"
MYSQL_PASSWORD = "${password:32}"

[config.env]
KENER_SECRET_KEY = "${KENER_SECRET_KEY}"  # self-reference — ignored
MYSQL_PASSWORD = "${MYSQL_PASSWORD}"       # self-reference — ignored
POSTGRES_PASSWORD = "${DB_PASSWORD}"       # cross-reference — kept
TZ = "Etc/UTC"                             # new value — added
```

**ZaneOps result:**
```yaml
# docker-compose.yml
x-zane-env:
  KENER_SECRET_KEY: "{{ generate_password | 64 }}"
  DB_PASSWORD: "{{ generate_password | 32 }}"
  MYSQL_PASSWORD: "{{ generate_password | 32 }}"
  POSTGRES_PASSWORD: "${DB_PASSWORD}"
  TZ: "Etc/UTC"
```

---

#### Static variables in `config.variables`

Variables without Dokploy placeholders in `[variables]` are kept as literal values.

**Dokploy:**
```toml
# template.toml
[variables]
pg_user = "authentik"
pg_db = "authentik"

[config.env]
PG_USER = "${pg_user}"
PG_DB = "${pg_db}"
PG_PASS = "${password:32}"
```

**ZaneOps result:**
```yaml
# docker-compose.yml
x-zane-env:
  pg_user: "authentik"
  pg_db: "authentik"
  PG_USER: "${pg_user}"
  PG_DB: "${pg_db}"
  PG_PASS: "{{ generate_password | 32 }}"
```

---

#### Empty environment variable entries

Environment entries without a value (list-style passthrough) are replaced with `${KEY}` if that key exists in `x-zane-env`. Entries with no matching key are dropped.

**Dokploy:**
```yaml
# compose.yml
services:
  docmost:
    environment:
      - APP_URL        # resolved from config.env
      - APP_SECRET     # resolved from config.env
      - APP_WHATEVER   # not in config.env — dropped
      - DATABASE_URL=postgresql://...  # has value — kept as-is
```

```toml
# template.toml
[config.env]
APP_URL = "http://${main_domain}:3000"
APP_SECRET = "${app_secret}"
```

**ZaneOps result:**
```yaml
# docker-compose.yml
x-zane-env:
  APP_URL: "http://${main_domain}:3000"
  APP_SECRET: "${app_secret}"

services:
  docmost:
    environment:
      APP_URL: "${APP_URL}"
      APP_SECRET: "${APP_SECRET}"
      DATABASE_URL: "postgresql://..."
```

---

#### Variable references without curly braces

`$VAR` (no braces) is normalized to `${VAR}`. `$$VAR` (shell escape) is preserved unchanged.

**Dokploy:**
```yaml
# compose.yml
services:
  wordpress:
    environment:
      WORDPRESS_DB_NAME: $DB_NAME
      WORDPRESS_DEBUG: ${WORDPRESS_DEBUG:-0}
  wp_db:
    healthcheck:
      test: ["CMD-SHELL", "exit | mysql -u root -p$$MYSQL_ROOT_PASSWORD"]
```

**ZaneOps result:**
```yaml
# docker-compose.yml
services:
  wordpress:
    environment:
      WORDPRESS_DB_NAME: "${DB_NAME}"
      WORDPRESS_DEBUG: "${WORDPRESS_DEBUG:-0}"
  wp_db:
    healthcheck:
      test: ["CMD-SHELL", "exit | mysql -u root -p$$MYSQL_ROOT_PASSWORD"]
```

---

#### `env_file` replacement

`env_file` references are removed and replaced with inline `environment` entries from `config.env`.

**Dokploy:**
```yaml
# compose.yml
services:
  plausible:
    image: ghcr.io/plausible/community-edition:v2.1.5
    env_file:
      - .env
```

```toml
# template.toml
[config.env]
BASE_URL = "http://${main_domain}"
SECRET_KEY_BASE = "${secret_base}"
TOTP_VAULT_KEY = "${totp_key}"
```

**ZaneOps result:**
```yaml
# docker-compose.yml
x-zane-env:
  main_domain: "{{ generate_domain }}"
  secret_base: "{{ generate_password | 64 }}"
  totp_key: "{{ generate_password | 32 }}"

services:
  plausible:
    image: ghcr.io/plausible/community-edition:v2.1.5
    environment:
      BASE_URL: "http://${main_domain}"
      SECRET_KEY_BASE: "${secret_base}"
      TOTP_VAULT_KEY: "${totp_key}"
```

# Compose file syntax reference

import {Aside, Steps} from '@astrojs/starlight/components'

> Introduced in [**v1.13.0**](/changelog/v113)

ZaneOps accepts standard Docker Compose files with a few extensions and restrictions described below.

## File structure

Any valid compose file with at least one `services` entry works. The ZaneOps-specific additions are all optional except when you need routing or generated secrets.

```yaml title="docker-compose.yml" title="docker-compose.yml"
# ZaneOps-specific: template expressions for generating values at deploy time
x-zane-env:
  VAR_NAME: "{{ template_expression }}"

# Standard services
services:
  service_name:
    image: image:tag
    environment:
      KEY: ${VALUE}        # references an x-zane-env variable
    deploy:
      labels:
        # ZaneOps-specific: label-based routing instead of ports
        zane.http.routes.0.domain: "example.com"
        zane.http.routes.0.port: "8080"

# Standard named volumes
volumes:
  data:

# Inline config files (standard content key, ZaneOps adds ${VAR} interpolation and auto-versioning)
configs:
  my_config:
    content: |
      server { listen 80; }
```

## How ZaneOps processes your file

Before deploying, ZaneOps transforms the compose file through these steps:

<Steps>
1. **Template processing**: `x-zane-env` expressions evaluated, `${VAR}` references expanded
2. **Service name hashing**: all service names prefixed with the stack's hash (e.g. `app` → `abc123_app`) to prevent DNS collisions across stacks
3. **Network injection**: three networks attached to every service automatically (see [Networks](#networks))
4. **Config versioning**: inline configs created as versioned Docker configs (`my_config_v1`, `my_config_v2`, ...)
5. **Computed file**: the fully processed compose file (with all variables resolved, service names hashed, and networks injected) is saved and visible in the ZaneOps UI so you can inspect exactly what gets deployed
   ![Docker compose yaml input](/images/docker-compose-yml-input.png)
   ![Computed docker compose yaml](/images/computed-docker-compose-yml.png)
6. **Stack deployment**: `docker stack deploy --with-registry-auth` is executed using the computed compose file
   ![Compose stack deployment logs](/images/deploy-compose-stack-logs.png)

</Steps>

---

## `x-zane-env`

`x-zane-env` is a ZaneOps-specific top-level key that replaces the role of a `.env` file. It lets you define stack-wide variables (either plain values or template expressions) that are then referenced throughout the rest of the compose file.

```yaml title="docker-compose.yml"
x-zane-env:
  # Plain value (behaves like a .env file entry)
  APP_PORT: "3000"

  # Template expression (generates a value at deploy time)
  DB_PASSWORD: "{{ generate_password | 32 }}"
```

All variables are referenced with **`${VAR_NAME}`** syntax (curly braces required). Variables referenced without curly braces (`$VAR_NAME`) are left as-is and not expanded. Referencing an undefined variable with `${VAR_NAME}` expands to an empty string.

```yaml title="docker-compose.yml"
x-zane-env:
  DB_PASSWORD: "{{ generate_password | 32 }}"

services:
  app:
    environment:
      PASSWORD: ${DB_PASSWORD}   # ✅ expanded to the generated value
      RAW: $DB_PASSWORD          # ❌ not expanded, kept literally as "$DB_PASSWORD"
      MISSING: ${UNDEFINED_VAR}  # ⚠️ expanded to an empty string
```


<Aside type='caution' title='template expressions outside of `x-zane-env`'>
Template expressions **only** work inside `x-zane-env`. Writing `{{ generate_password | 32 }}` directly in a service `environment` will not be evaluated.
</Aside>

- Values from template expressions are evaluated **once on the first deployment** and then persisted. A generated password won't change on subsequent deploys.
  ![compose content](/images/db-compose-stack-with-overrides.png)
- The variables are persisted as environment overrides:
  ![env overrides](/images/env-overrides.png)


### Available template functions

#### `generate_username`

Generates a random username in the format `{adjective}{animal}{number}`.

```yaml title="docker-compose.yml"
x-zane-env:
  DB_USER: "{{ generate_username }}"
# Output example: reddog65, bluecat42
```

---

#### `generate_password | <length>`

Generates a cryptographically secure random password as a hexadecimal string. Length must be an even number ≥ 8.

```yaml title="docker-compose.yml"
x-zane-env:
  DB_PASSWORD: "{{ generate_password | 32 }}"
  API_SECRET: "{{ generate_password | 64 }}"
```

```yaml title="docker-compose.yml"
# ❌ Wrong: odd length
PASSWORD: "{{ generate_password | 31 }}"

# ✅ Correct
PASSWORD: "{{ generate_password | 32 }}"
```

---

#### `generate_base64 | <bytes>`

Generates a base64-encoded random string of N bytes. Minimum value is 8.

```yaml title="docker-compose.yml"
x-zane-env:
  ENCRYPTION_KEY: "{{ generate_base64 | 32 }}"
  SESSION_SECRET: "{{ generate_base64 | 64 }}"
```

---

#### `generate_slug`

Generates a URL-friendly slug in the format `{adjective}-{noun}-{number}`.

```yaml title="docker-compose.yml"
x-zane-env:
  DB_NAME: "{{ generate_slug }}"
# Output example: happy-tree-91
```

---

#### `generate_domain`

Generates a unique domain scoped to your stack: `{project_slug}-{stack_slug}-{random}.{ROOT_DOMAIN}`.

```yaml title="docker-compose.yml"
x-zane-env:
  APP_URL: "{{ generate_domain }}"
  CALLBACK_URL: "https://{{ generate_domain }}/auth/callback"
# Output example: my-app-backend-a1b2c3.zaneops.dev
```

---

#### `generate_uuid`

Generates a UUID v4.

```yaml title="docker-compose.yml"
x-zane-env:
  INSTALLATION_ID: "{{ generate_uuid }}"
```

---

#### `generate_email`

Generates a fake but valid-looking email address.

```yaml title="docker-compose.yml"
x-zane-env:
  ADMIN_EMAIL: "{{ generate_email }}"
```

---

#### `network_alias | 'service_name'`

Generates a stable, environment-scoped hostname. Use this when you need to reference a service in this stack from another service or stack in the same environment.

**Format**: `{network_alias_prefix}-{service_name}`

```yaml title="docker-compose.yml"
x-zane-env:
  DB_HOST: "{{ network_alias | 'postgres' }}"
  REDIS_URL: "redis://{{ network_alias | 'redis' }}:6379"
# Output example: my-stack-postgres
```

The alias is stable across redeployments and scoped to the environment, so services in the same environment share the same alias space.

---

#### `global_alias | 'service_name'`

Generates a globally unique hostname, accessible across all projects and environments.

**Format**: `{hash_prefix}_{service_name}`

```yaml title="docker-compose.yml"
x-zane-env:
  GLOBAL_DB: "{{ global_alias | 'postgres' }}"
# Output example: abc123_postgres
```

Use this only for cross-project or cross-environment communication. Use `network_alias` to connect in the same environment 
and use the service name directly to reference it in the stack.

---

### Variable composition

Variables in `x-zane-env` can reference each other using `${VAR}` syntax to build composite values:

```yaml title="docker-compose.yml"
x-zane-env:
  DB_USER: "{{ generate_username }}"
  DB_PASSWORD: "{{ generate_password | 32 }}"
  DB_NAME: "{{ generate_slug }}"
  DB_HOST: "{{ network_alias | 'postgres' }}"

  DATABASE_URL: "postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:5432/${DB_NAME}"

services:
  app:
    image: myapp:latest
    environment:
      DATABASE_URL: ${DATABASE_URL}
```

### Exposed variables (`__` prefix)

Variables whose name starts with `__` are surfaced as **environment overrides** in the ZaneOps UI. This makes their resolved value visible and copyable, so it can easily be used by services outside the stack.

A typical use case is generating a connection URL for a database stack and exposing it so an external service (a git app, another stack) can reference it without having to reconstruct it manually.

```yaml title="docker-compose.yml"
x-zane-env:
  DB_USER: "{{ generate_username }}"
  DB_PASSWORD: "{{ generate_password | 32 }}"
  DB_HOST: "{{ network_alias | 'postgres' }}"
  DB_NAME: "{{ generate_slug }}"

  # Exposed in the UI as an environment override
  __DATABASE_URL: "postgres://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:5432/${DB_NAME}"
```

The `__DATABASE_URL` variable won't be injected into any service automatically. It exists purely to surface the resolved value in the UI so you can copy it into another service's environment variables.

<Aside type='note'>
The `__` prefix is part of the variable name. If you do reference it inside the stack, use `${__DATABASE_URL}` (double underscore included).
</Aside>

---

## Routing

ZaneOps uses label-based routing instead of port mappings. There is no concept of published ports; traffic is routed through ZaneOps' reverse proxy based on `deploy.labels`.

### Route labels

```yaml title="docker-compose.yml"
services:
  web:
    image: nginx:alpine
    deploy:
      labels:
        zane.http.routes.0.domain: "example.com"
        zane.http.routes.0.port: "80"
        zane.http.routes.0.base_path: "/"
        zane.http.routes.0.strip_prefix: "false"
```

| Label | Required | Description |
| --- | --- | --- |
| `zane.http.routes.{N}.domain` | ✅ | Domain name to match |
| `zane.http.routes.{N}.port` | ✅ | Container port to forward traffic to |
| `zane.http.routes.{N}.base_path` | No | Path prefix (default: `/`) |
| `zane.http.routes.{N}.strip_prefix` | No | Strip `base_path` before forwarding (default: `true`) |

`{N}` is a zero-based sequential index. Add more routes by incrementing the index:

```yaml title="docker-compose.yml"
deploy:
  labels:
    zane.http.routes.0.domain: "example.com"
    zane.http.routes.0.port: "8080"

    zane.http.routes.1.domain: "www.example.com"
    zane.http.routes.1.port: "8080"

    zane.http.routes.2.domain: "api.example.com"
    zane.http.routes.2.port: "3000"
    zane.http.routes.2.base_path: "/api"
    zane.http.routes.2.strip_prefix: "true"
```

Route domains can reference `x-zane-env` variables:

```yaml title="docker-compose.yml"
x-zane-env:
  APP_DOMAIN: "{{ generate_domain }}"

services:
  web:
    deploy:
      labels:
        zane.http.routes.0.domain: "${APP_DOMAIN}"
        zane.http.routes.0.port: "8080"
```

---

## Unsupported properties

The following standard Docker Compose properties are **silently stripped** before deployment:

| Property | Reason |
| --- | --- |
| `expose` | Not meaningful in Swarm mode |
| `restart` | Use `deploy.restart_policy` instead |
| `build` | ZaneOps requires pre-built images |
| `container_name` | Not meaningful in Swarm mode |

### `ports`

`ports` is not stripped and will work, but **it is strongly recommended to use routing labels instead**. Routing labels integrate with ZaneOps' reverse proxy to handle TLS termination, domain routing, and path-based routing automatically. Publishing raw ports bypasses all of that.

```yaml title="docker-compose.yml"
# ✅ Recommended: routing labels
services:
  web:
    image: myapp:latest
    deploy:
      labels:
        zane.http.routes.0.domain: "myapp.com"
        zane.http.routes.0.port: "8080"

# ⚠️ Works, but gives up ZaneOps routing features
services:
  web:
    image: myapp:latest
    ports:
      - "8080:8080"
```

---

## Pausing a service

Setting `deploy.replicas` to `0` pauses a service without removing it from the stack. Its status in ZaneOps becomes `SLEEPING`. Set it back to any positive number to resume.

```yaml title="docker-compose.yml"
services:
  worker:
    image: myapp/worker:latest
    deploy:
      replicas: 0  # paused; change to 1 or more to resume
```

This is useful for temporarily disabling background workers or non-critical services without tearing down the entire stack.

---

## Volumes

Relative path bind mounts are **not supported** and will fail validation:

```yaml title="docker-compose.yml"
# ❌ Will fail
volumes:
  - ./config:/etc/app/config
  - ../data:/app/data
```

Use inline configs for configuration files, or absolute paths for host directories:

```yaml title="docker-compose.yml"
# ✅ Inline config
services:
  web:
    configs:
      - source: app_config
        target: /etc/app/config.json

configs:
  app_config:
    content: |
      { "key": "value" }

# ✅ Absolute path
services:
  portainer:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
```

---

## Docker configs

ZaneOps supports inline configs using the standard `content` key. What ZaneOps adds on top is `${VAR}` interpolation inside config content and automatic versioning on redeploy.

```yaml title="docker-compose.yml"
services:
  web:
    image: nginx:alpine
    configs:
      - source: nginx_config
        target: /etc/nginx/nginx.conf

configs:
  nginx_config:
    content: |
      server {
        listen 80;
      }
```

Config content supports `${VAR}` interpolation from `x-zane-env`:

```yaml title="docker-compose.yml"
x-zane-env:
  DB_HOST: "{{ network_alias | 'postgres' }}"

configs:
  app_config:
    content: |
      { "db_host": "${DB_HOST}" }
```

A common use case is shipping database initialization scripts:

```yaml title="docker-compose.yml"
# docker-compose.yml
services:
  postgres:
    image: postgres:16
    configs:
      - source: init_sql
        target: /docker-entrypoint-initdb.d/init.sql

configs:
  init_sql:
    content: |
      CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
      CREATE TABLE users (
        id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
        email TEXT UNIQUE NOT NULL
      );
```

### Automatic versioning

Docker configs are immutable, so ZaneOps appends a version suffix to every config name and manages the lifecycle automatically.


![Docker config versioned](/images/config-versioning-in-compose.png)

| Deployment | `content` changed? | Config name used | Old config |
| --- | --- | --- | --- |
| 1st deploy | — | `nginx_config_v1` | — |
| 2nd deploy | No | `nginx_config_v1` (reused) | unchanged |
| 3rd deploy | **Yes** | `nginx_config_v2` (new) | not used anymore |

<Aside type='note' title='Version increment'>
The version is **only incremented when the content actually changes**. Redeploying with identical config content reuses the existing version and no new config is created.
</Aside>



---

## Networks

### Automatic network injection

You don't need to declare networks for basic service communication. ZaneOps automatically attaches every service to three networks:


| Network | Scope | Purpose |
| --- | --- | --- |
| `zane` (global overlay) | All ZaneOps services | Proxy and ZaneOps-internal communication |
| Environment network (`zn-env-*`) | Same environment | Services in the same env can talk to each other |
| Stack default network | Same stack | Services within the stack use their original names as hostnames |

![ZaneOps added networks to compose](/images/networks-in-compose.png)


### Service name hashing

ZaneOps prefixes all service names with a stack-specific hash to prevent DNS collisions across stacks:

```
# In your compose file:    app, postgres
# Deployed as:             abc123_app, abc123_postgres
```

Because of this, **do not hardcode hashed names as hostnames**. Use one of these instead:

- **Original service name**: works within the stack's default network:
  ```yaml title="docker-compose.yml"
  environment:
    DB_HOST: postgres  # resolves in the stack default network
  ```

- **`network_alias`**: works across services in the same environment:
  ```yaml title="docker-compose.yml"
  x-zane-env:
    DB_HOST: "{{ network_alias | 'postgres' }}"  # e.g. my-stack-postgres
  ```

- **`global_alias`**: for cross-stack or cross-environment references:
  ```yaml title="docker-compose.yml"
  x-zane-env:
    DB_HOST: "{{ global_alias | 'postgres' }}"  # e.g. abc123_postgres
  ```

---

## `depends_on`

ZaneOps converts the dict form of `depends_on` to a list for Docker Swarm compatibility:

```yaml title="docker-compose.yml"
# ❌ Dict form: converted automatically
depends_on:
  postgres:
    condition: service_healthy

# ✅ Equivalent after conversion
depends_on:
  - postgres
```

The `condition` field is dropped. `depends_on` controls startup ordering only; it does not wait for a service to become healthy or ready.

---

## Troubleshooting

### Template expression not evaluated

Template expressions only work inside `x-zane-env`:

```yaml title="docker-compose.yml"
# ❌ Not evaluated
services:
  app:
    environment:
      PASSWORD: "{{ generate_password | 32 }}"

# ✅ Correct
x-zane-env:
  PASSWORD: "{{ generate_password | 32 }}"

services:
  app:
    environment:
      PASSWORD: ${PASSWORD}
```

### Unexpected empty value

`${VAR}` references are always expanded. If the variable is not declared in `x-zane-env`, it expands to an empty string rather than keeping the literal `${VAR}` text. Make sure every variable you reference is defined.

### Service can't connect to another service

Don't use the hashed service name (`abc123_postgres`) as a hostname; it's an implementation detail. Use the original service name (works in the stack default network) or `network_alias` (works across the environment):

```yaml title="docker-compose.yml"
x-zane-env:
  DB_HOST: "{{ network_alias | 'postgres' }}"
```

### Route validation failed

Both `domain` and `port` are required per route. `strip_prefix` must be `"true"` or `"false"` (not `"yes"`/`"no"`).

### Config not updated after redeployment

ZaneOps only creates a new config version when the `content` changes. If the content is identical to the previous deployment, the existing version is reused. This is expected behavior.

### `generate_password` invalid length error

Length must be an even number ≥ 8 (e.g. 8, 10, 12, 16, 32, 64).


---

## Complete example

PostgreSQL stack using generated credentials, a network alias, and an exposed connection URL:

```yml title="docker-compose.yml"
version: "3.8"
x-zane-env:
  # Generated once on first deploy and persisted
  POSTGRES_PASSWORD: "{{ generate_password | 32 }}"
  POSTGRES_USER: "{{ generate_slug }}"
  POSTGRES_DB: "{{ generate_slug }}"

  POSTGRES_VERSION: "18-alpine"

  # Stable hostname for other services in the same environment to connect to
  DB_HOST_ENV_NAME: "{{ network_alias | 'postgres' }}"

  # Exposed in the UI so external services can copy the full connection string
  __DATABASE_URL: "postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${DB_HOST_ENV_NAME}:5432/${POSTGRES_DB}?schema=public"

services:
  postgres:
    image: docker.io/library/postgres:${POSTGRES_VERSION:-18-alpine}
    restart: unless-stopped
    healthcheck:
      # $$ escapes the $ so it's passed literally to the shell instead of being expanded by ZaneOps
      test: ["CMD-SHELL", "pg_isready -d $$POSTGRES_DB -U $$POSTGRES_USER"]
      start_period: 20s
      interval: 30s
      retries: 5
      timeout: 5s
    volumes:
      - database:/var/lib/postgresql
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_DB: ${POSTGRES_DB}
volumes:
  database:
    driver: local
```

# Environment variables

> Since [**v1.0**](/changelog/announcing-v1)

### How to add a variable to a service

To add a variable to a service, you can go to the **service details page** > **Env variables tab**. 

- You can either add a single variable 
  ![Add a single variable](https://assets.zaneops.dev/images/single-env-variable.png)
- or add multiple variables from a `.env` file
  <img className="block dark:hidden" src="https://assets.zaneops.dev/images/service-envs-modal-light.png" alt="service environment variables page with a modal open for adding multiple environment variable page" />
  <img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/service-envs-modal-dark.png" alt="service environment variables page with a modal open for adding multiple environment variable page" />



### How to add a variable to an environment 

You can add variables to an environment by going to the **project details page** > **Variables tab**. 
Each variable added to an environment is available to all services in that environment. 

  ![Environment's variables](/images/environment-variables-dark.png)

You can also reference them in individual services by using a placeholder `{{env.VARIABLE_NAME}}`. All 
referenced variables are replaced at runtime when your app has been deployed. if the 
referenced variable doesn't exist in the environment, the placeholder will not be replaced. 



## System environment variables

ZaneOps provides a set of predefined variables you can use in your service.

- `ZANE`
  - Example: `true`
  - Flag indicating the service is deployed on ZaneOps.

- `ZANE_DOMAINS`
  - Example: `example.com,admin.example.com`
  - Comma-separated list of all public domains where this service is accessible.

- `ZANE_ENVIRONMENT`
  - Example: `production`
  - The environment name where the service is deployed (for example: `production`, `staging`).

- `ZANE_PRIVATE_DOMAIN`
  - Example: `service.project.internal.zaneops`
  - Internal project-scoped domain used to reach this service from other services in the same project.

- `ZANE_GLOBAL_PRIVATE_DOMAIN`
  - Example: `service.global.zaneops`
  - Global domain used to reach this service across the ZaneOps platform (across projects).

- `ZANE_DEPLOYMENT_TYPE`
  - Example: `docker` or `git`
  - The type of deployment for the service. `docker` indicates a container image; `git` indicates a source-based deployment.

- `ZANE_SERVICE_ID`
  - Example: `srv_01F2ABC3D4`
  - The unique identifier for the service.

- `ZANE_SERVICE_NAME`
  - Example: `my-service`
  - The slug or short name of the service.

- `ZANE_PROJECT_ID`
  - Example: `proj_0123ABCD`
  - The id of the project this service belongs to.

- `ZANE_DEPLOYMENT_SLOT`
  - Example: `blue` or `green`
  - The deployment slot for the running deployment (used for blue/green deployments).
    This is also sent as the HTTP header `x-zane-dpl-slot` on internal platform requests.

- `ZANE_DEPLOYMENT_HASH`
  - Example: `dpl_dkr_aBcDeFgHiJkLmN`
  - The unique hash for this specific deployment. This is also sent as the HTTP header `x-zane-dpl-hash`.

# Environments

import {Steps, Aside} from '@astrojs/starlight/components';


> Introduced in [**v1.7.0**](/changelog/v17)

ZaneOps supports complex development workflows through environments, giving you isolated instances of all services in a project.
When you create a project, by default it comes with a **production** environment, you cann't rename or delete that environment.

## Create an Environment

<Steps>

1. In the project environments page `+ New Environment` 
    <img className="block dark:hidden" src="https://assets.zaneops.dev/images/project-environments-light.png" alt="project environments page" />
    <img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/project-environments-dark.png" alt="project environments page" />


2. Choose which type of environment to create :
    <img className="block dark:hidden" src="https://assets.zaneops.dev/images/project-clone-environment-light.png" alt="clone environment modal" />
    <img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/project-clone-environment-dark.png" alt="clone environment modal" />

    1. If you select one environment in the `Clone Environment` dropdown, it will creates a copy of the selected environment, including services, variables, and configurations.
        - If you check  `deploy services ?` all the services will be deployed upon cloning
        - If you don't check  `deploy services ?`, all services and their configuration will be staged for deployment, You will need to review and deploy manually all the staged changes.

    2. If you don't select any environment in the dropdown, it will create an empty environment with no services in it. 
</Steps>



<Aside type="tip" title='Use case for cloning'>
One neat use-case of cloning environments is that it allows you to create a **staging** environment based on the default **production** environment
</Aside>


## Shared Environment variables

Shared variables are inherited by all the services in this environment. 
If a service has the same variable, that will take precedence over the variable defined in this environment.
You can reference these variables in services with `{{env.VARIABLE_NAME}}`.

![Shared environment variables](https://assets.zaneops.dev/images/env-shared-variables.png)

ZaneOps will automatically replace the variable in the service :

![Shared environment variables referenced in a service](https://assets.zaneops.dev/images/env-shared-variables-referenced.png)

# Overview

import { ASSETS_SERVER_DOMAIN } from "astro:env/client"

ZaneOps supports creating and deploying applications from Git repositories.  
These applications are **built directly on the server** using [builders](/knowledge-base/builders) that detect or define how your code should be packaged and built.

Learn more about the available options in the [builders documentation](/knowledge-base/builders).

### From GitHub and GitLab

You can connect your account on ZaneOps using [Git applications](./git-apps). 
Using Git apps, you can deploy your public and private repositories with automatic deploys on Git push.


### From any provider

As well as GitHub and GitLab, you can deploy any repository as long as it is a public repository. 
You do so by specifying its repository URL. 

Keep in mind that using the repository URL, auto-deploy on Git push are not activated by default.
However you can setup a CI/CD script to deploy your apps using the API, [Learn more here](./auto-deploy#auto-deploy-via-api). 

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/create-git-service-light.png" alt="create git service page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/create-git-service-dark.png" alt="create git service page" />

# Auto-deploy

import { ASSETS_SERVER_DOMAIN } from "astro:env/client"
import {Aside, Steps} from '@astrojs/starlight/components';

### Auto-deploy with Git apps


When creating a service from a [Git app](../git-apps), **auto-deploy on Git push is enabled by default**.

You can customize this behavior:

- **Disable auto-deploy** if you don’t want deployments triggered on every push
    <Aside type="note" title="On every push ?">
      Deployments are only triggered when the push is made to the same branch configured for the service.
    </Aside>
- **Automatically clean up the deployment queue** (enabled by default), this ensures that if multiple pushes happen in quick succession, only the latest one is deployed.
- **Add watch paths** to restrict auto-deploys to changes in specific files or directories.  
  These are defined using [Glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)) (e.g., `frontend/**`, `{packages/trpc,packages/db,apps/web}/**`).

<img src={`${ASSETS_SERVER_DOMAIN}/images/auto-deploy-options.png`} alt="Service Auto-deploy options" />

Deployments triggered by a Git push will appear with the label `git push`:

<img src={`${ASSETS_SERVER_DOMAIN}/images/git-push-deployment.png`} alt="Git push deployment" />


### Auto-deploy via API

Using the API, you can trigger a new deployment for a service without needing to create a git apps. 
This can be used to trigger a deployment in a Continuous Integration script after a git push.

#### Example usage: Github actions

Automate your deployment workflow with GitHub Actions to update your application whenever changes are pushed to your repository:

<Steps>
1. Get your ZaneOps deployment webhook URL:
   Navigate to **service details page > settings > Deploy section > deploy webhook url**
   ![Locating the deployment webhook URL](https://assets.zaneops.dev/images/tuto-rr7-webhook-url.png)
   
2. Store your secrets in GitHub:
   Navigate to **GitHub repository > settings > secrets and variables > actions** and add:
   - `DEPLOY_WEBHOOK_URL`: Your ZaneOps webhook URL
   ![Adding repository secrets](https://assets.zaneops.dev/images/tuto-rr7-secrets.png)
   
3. Create a GitHub Actions workflow file in your repository:
    ```yaml
    # .github/workflows/ci.yaml
    name: Deploy
    on:
      push:
        branches: [main] # customize as needed
    jobs:
      build-push-app:
        name: Build and Deploy Guestbook
        runs-on: ubuntu-latest
        steps:
            - name: Checkout
              uses: actions/checkout@v4
            - name: Deploy to ZaneOps
              run: curl -f -o /dev/null -X PUT "${{ secrets.DEPLOY_WEBHOOK_URL }}" 
    ```
5. With this workflow in place, changes pushed to your main branch will automatically trigger a new deployment, 
   it will show in the list with the label `API` :
    
   <img src={`${ASSETS_SERVER_DOMAIN}/images/deploy-via-api.png`} alt="Service deployed via API" />

</Steps>

<Aside type="note" title="API reference">
More information in the API documentation for the [deployment endpoint](/api-reference/openapi/#tag/deploy-service/put/api/deploy-service/git/{deploy_token}/).
</Aside>

# Git applications

import { ASSETS_SERVER_DOMAIN } from "astro:env/client"
import {Aside} from '@astrojs/starlight/components';

> Introduced in [**v1.11.0**](/changelog/v111)

Git apps are integrations with Git providers that allow you to listen to Git events from your repositories and perform actions on your behalf.

They can be installed either on your personal profile or within an organization you’re a member of.

<Aside type="note" title="Public repositories">
ZaneOps supports both **public and private repositories**. 
However, only repositories where you are an **owner or maintainer** will appear in the list when creating a service.
</Aside>

### Supported providers

- [GitHub](../github)
- [GitLab](../gitlab)


### What you get with Git apps

- **Support for private repositories**  
    <video src={`${ASSETS_SERVER_DOMAIN}/videos/private-github-repos.mp4`} controls muted></video>
- **Automatic deployment on Git push**  
    <video src={`${ASSETS_SERVER_DOMAIN}/videos/auto-deploy-github-gitlab.mp4`} controls muted></video>

# GitHub apps

import { ASSETS_SERVER_DOMAIN } from "astro:env/client"
import {Steps, Aside} from '@astrojs/starlight/components';

> Introduced in [**v1.11.0**](/changelog/v11)

To connect your GitHub account to ZaneOps, you use GitHub apps. 


### How to create a GitHub app

<Steps>
1. Go to **Settings > Git**: 
   <img src={`${ASSETS_SERVER_DOMAIN}/images/settings-git.png`} alt="Git settings" />
2. Choose Create GitHub app: 
   <img src={`${ASSETS_SERVER_DOMAIN}/images/create-github-app.png`} alt="Create GitHub app" />

   If you want to deploy repos from your organization, you can check **Install into organization ?** and fill 
   in the organization name:
   <img src={`${ASSETS_SERVER_DOMAIN}/images/create-github-app-org.png`} alt="Create GitHub app with Org" />

   <Aside type="caution" title="webhook URL">
    The webhook URL should be on a publicly accessible domain on https.
    
    If testing ZaneOps locally, you can use a service like https://webhook.site/ for forwarding webhooks 
    to your local instance.
   </Aside>

3. Once you submit the form, you will be redirected to GitHub where you will need to give the app a name: 
   <img src={`${ASSETS_SERVER_DOMAIN}/images/create-github-app-github.com.png`} alt="Create GitHub app on Github.com" />

4. After submitting, you will be redirected back to ZaneOps where you will see the newly created app.
   You will need to install the application on GitHub to get access to the repositories you want to deploy on ZaneOps:
   <img src={`${ASSETS_SERVER_DOMAIN}/images/install-git-app.png`} alt="Install github app" />
   <img src={`${ASSETS_SERVER_DOMAIN}/images/install-git-app-github.com.png`} alt="Install github app on GitHub" />

5. Once the application is installed, you can test the application installation to make sure it has access to your repositories: 
   <img src={`${ASSETS_SERVER_DOMAIN}/images/test-github-app.png`} alt="Test github app" />
</Steps>

### How to deploy a service from a GitHub app

<Steps>
1. Go to your **project > new service** and choose **Create from Git Provider**:
   <img src={`${ASSETS_SERVER_DOMAIN}/images/create-from-git-provider.png`} alt="New service page" />
2. Choose the newly created Github app in the list of available apps:
   <img src={`${ASSETS_SERVER_DOMAIN}/images/choose-github-app.png`} alt="Select Git app" />
3. There you can select the repository you want to deploy:
   <img src={`${ASSETS_SERVER_DOMAIN}/images/create-github-service.png`} alt="Create new github service" />
4. Once deployed, you will notice in the logs, that your app is cloned using github access token, meaning that it worked !
   <img src={`${ASSETS_SERVER_DOMAIN}/images/git-clone-access-token.png`} alt="Git clone with access token" />
</Steps>

# GitLab apps

import { ASSETS_SERVER_DOMAIN } from "astro:env/client"
import {Steps, Aside} from '@astrojs/starlight/components';

> Introduced in [**v1.11.0**](/changelog/v11)

<Aside title="Version support">
ZaneOps supports both [gitlab.com](https://gitlab.com) and self-managed GitLab instances from version `16.9.0` or higher.
</Aside>

To connect your GitLab account to ZaneOps, you use GitLab apps. 

### How to create a GitLab app

<Steps>
1. Go to **Settings > Git**: 
   <img src={`${ASSETS_SERVER_DOMAIN}/images/settings-git.png`} alt="Git settings" />
2. Choose Create GitHub app: 
   <img src={`${ASSETS_SERVER_DOMAIN}/images/create-gitlab-app.png`} alt="Create GitLab app" />

   <Aside type="caution" title="Redirect URI">
    The **Redirect URI** should be on a publicly accessible domain, 
    no need for https absolutely, but it is strongly recommended.
    
    If testing ZaneOps locally, you can use a service like https://webhook.site/ for forwarding webhooks 
    to your local instance.
   </Aside>

3. To get the credentials for the new app (`Application ID` and `Application Secret`) you need to create the app on your Gitlab instance: 
    
    At [https://\{your-gitlab-instance\}/-/profile/applications](https://{your-gitlab-instance}/-/profile/applications) click on 
   ** Add new application**:
   <img src={`${ASSETS_SERVER_DOMAIN}/images/gitlab-app-list-gitlab.com.png`} alt="List gitlab apps" />
    
    Create a new application, with the scopes `api`, `read_user` and `read_repository`, 
    and use the same value for the Redirect URI as in the previous step:
   <img src={`${ASSETS_SERVER_DOMAIN}/images/add-new-gitlab-app-gitlab.com.png`} alt="Add new gitlab app on gitlab.com" />

4. After submitting, you will be redirected to your GitLab instance and asked to authorize the application:
   <img src={`${ASSETS_SERVER_DOMAIN}/images/authorize-gitlab-app-on-gitlab.com.png`} alt="Authorize gitlab app on gitlab.com" />

5. Once authorized, you will be redirected back to ZaneOps where you will see the newly created app.
   
   you can test the application installation to make sure it has access to your repositories: 
   <img src={`${ASSETS_SERVER_DOMAIN}/images/test-gitlab-app.png`} alt="Test GitLab app" />
</Steps>

### How to deploy a service from a GitLab app

<Steps>
1. Go to your **project > new service** and choose **Create from Git Provider**:
   <img src={`${ASSETS_SERVER_DOMAIN}/images/create-from-git-provider.png`} alt="New service page" />
2. Choose the newly created GitLab app in the list of available apps:
   <img src={`${ASSETS_SERVER_DOMAIN}/images/select-gitlab-app.png`} alt="Select Git app" />
3. There you can select the repository you want to deploy:
   <img src={`${ASSETS_SERVER_DOMAIN}/images/choose-gitlab-repo.png`} alt="Create new Gitlab service" />
4. Once deployed, you will notice in the logs, that your app is cloned using the Gitlab access token, meaning that it worked !
   <img src={`${ASSETS_SERVER_DOMAIN}/images/gitlab-access-token.png`} alt="Git clone with access token" />
</Steps>


### Synchronize New repositories

Newly created repositories are not Synchronized by default with Gitlab apps, instead you need to manually synchronize 
them from the dashboard:

   <img src={`${ASSETS_SERVER_DOMAIN}/images/sync-gitlab-repos.png`} alt="Sync GitLab repositories" />

### Updating GitLab app

If you rotated the secret or updated the redirect URI of your application on your GitLab instance, you can edit the gitlab app 
and paste in the new credentials:

<img src={`${ASSETS_SERVER_DOMAIN}/images/edit-gitlab-app.png`} alt="Edit Gitlab app" />

Once done, you will be redirected to your gitlab instance and will need to authorize the app again:

<img src={`${ASSETS_SERVER_DOMAIN}/images/authorize-gitlab-app-on-gitlab.com.png`} alt="Authorize gitlab app on gitlab.com" />

# Overview

import { ASSETS_SERVER_DOMAIN } from "astro:env/client"
import {Aside} from '@astrojs/starlight/components';

> Introduced in [**v1.12.0**](/changelog/v112)

Preview environments let you spin up **ephemeral copies of your apps** for testing and review.  
They are ideal when you want to:  

- Test features in isolation before merging to production  
- Run product experiments or proofs of concept  
- Conduct A/B testing with real services  
- Share a working feature branch with your team or stakeholders  

---

### How do they work?

When you create a preview environment:  

- All services from a **base environment** (production by default) are **cloned** into a new environment.  
- Service configuration and environment variables are preserved.  
- **Volumes are not cloned**. Instead, fresh volumes are created to ensure data stays isolated between environments.  

You can control which services get cloned by defining a [preview template](./a-preview-templates).  
This allows you to include only the services needed for your feature or experiment.  


### Creating preview environments

There are two ways to create a preview environment:  

1. **Via API** — programmatically spin up previews for custom workflows. See [API guide](./c-create-preview-from-api).  
2. **Via Pull Request** — automatically create a preview when opening or updating a PR. See [PR integration](./b-create-preview-from-pull-request).  

---

<Aside type="note" title="Good to know">
Preview environments are temporary by design. Once the feature branch is merged, closed or deleted, the preview is cleaned up automatically to save resources.
</Aside>

# Preview enviroment templates

import { ASSETS_SERVER_DOMAIN } from "astro:env/client"
import {Aside} from '@astrojs/starlight/components';

> Introduced in [**v1.12.0**](/changelog/v112)

Preview templates let you define **how preview environments should be created**.  
They give you fine-grained control over what gets cloned, how previews are exposed, and how long they live.  

---

### What can you configure?

A template can define:  

- **Base environment**: the source environment to clone from (defaults to production).  
- **Services to clone**: include or exclude specific services from the base environment (defaults to all services).  
- **Default environment variables**: inject common vars into all preview deployments.  
- **Root domain**: set the domain under which preview URLs will be created.  
- **Preview limit**: maximum number of previews per template (defaults to **5**).  
- **Automatic cleanup**: whether previews are automatically deleted when a branch is closed or deleted.  
- **TTL (time-to-live)**: how long previews remain active (defaults to **infinite**).  
- **Authentication**: enable or disable access protection for preview environments.  


### Where to configure templates

You can create and manage templates under **Project > Settings > Preview templates**.  

- Templates are scoped to a specific project.  
- Only one template can be marked as the **default**.  
- The default template is automatically used for pull requests and when you omit the `template` field in the API.  

  <img className="block dark:hidden" src={`/images/preview-templates-light.png`} alt="Preview templates" />
  <img className="!hidden dark:!block" src={`/images/preview-templates-dark.png`} alt="Preview templates" />
  


### Cloning strategies

You can choose how services are cloned into a preview environment:  

- **All services**: spin up a full copy of the base environment.  
  Use this to test features in complete isolation.  
      
      <img className="block dark:hidden" src={`/images/clone-all-strategy-light.png`} alt="Clone all services strategy" />
      <img className="!hidden dark:!block" src={`/images/clone-all-strategy-dark.png`} alt="Clone all services strategy" />

    <Aside title="Network alias" type="tip">
      If your services communicate using environment network aliases, no extra configuration is required.  
      <img src={`/images/environment-alias.png`} alt="Environment network alias" />
    </Aside>
- **Only selected services**: clone only the services you need.  
  This is useful for sharing heavy or persistent services across environments (e.g. reusing the same database in previews).  
 

      <img className="block dark:hidden" src={`/images/clone-selected-strategy-light.png`} alt="Clone selected services strategy" />
      <img className="!hidden dark:!block" src={`/images/clone-selected-strategy-dark.png`} alt="Clone selected services strategy" />


    <Aside title="Network alias" type="tip">
         To connect across environments, use the **global network alias** of the shared service.    
        <img src={`/images/global-alias.png`} alt="Global network alias" />
    </Aside>

### Root domain

By default, ZaneOps uses the `ROOT_DOMAIN` environment variable as the base domain for preview environments.  

Each preview gets a unique subdomain under this root.  
You can override the root domain in a preview template if you want previews to live under a different domain.  


### Time to live (TTL)

Preview environments can be configured with a **time-to-live** (in seconds).  

- When the TTL expires, the preview is automatically deleted.  
- If not set, previews live indefinitely until either manually removed or automatically cleaned up (default behavior).  



### Authentication

You can optionally protect preview environments with **Basic Authentication**.  

- When enabled, users must enter a username and password before accessing any web service in the preview.  
- Credentials are defined per template

### Preview limit

You can restrict how many preview environments a template is allowed to create.  

- By default, the limit is **5** previews per template.  
- When the limit is reached, **no new previews will be created** until an existing one is deleted.  

This is to prevent uncontrolled growth of preview environments and ensures resource usage stays within limits.

# Pull request previews

import {Aside} from '@astrojs/starlight/components';

> Introduced in [**v1.12.0**](/changelog/v112)

When creating a service from a [Git application](/knowledge-base/git/git-apps), **pull request previews** are enabled by default.  
You can manage this behavior in the service’s settings under **Auto-deploy options**:

<div className="flex flex-col gap-2">
  <img className="block dark:hidden" src={`/images/auto-deploy-settings-light.png`} alt="Auto-deploy settings" />
  <img className="!hidden dark:!block" src={`/images/auto-deploy-settings-dark.png`} alt="Auto-deploy settings" />
</div>

---

### How it works

When a pull request is opened, ZaneOps automatically creates a **preview environment** for that PR.  

The associated Git application will also post a comment on the pull request, updating you on the **status of the preview deployment**.

<img className="block dark:hidden" src={`/images/pr-preview-comment-light.png`} alt="PR Preview comments" />
<img className="!hidden dark:!block" src={`/images/pr-preview-comment-dark.png`} alt="PR Preview comments" />

---

### Note about preview deployments from forks

When a pull request originates from a **forked repository**, ZaneOps will **create** the preview environment  but **will not automatically trigger its deployment**.  

The repository owner (or ZaneOps project owner) must **approve or decline** the preview deployment manually.

<div className="flex flex-col gap-2">
  <img className="block dark:hidden" src={`/images/preview-deploy-blocked-comment-light.webp`} alt="Preview deployment blocked GitHub comment" />
  <img className="!hidden dark:!block" src={`/images/preview-deploy-blocked-comment-dark.png`} alt="Preview deployment blocked GitHub comment" />
  <img src={`/images/preview-deploy-blocked.png`} alt="Preview deployment blocked UI" />
</div>

### Troubleshooting

#### Preview not appearing or stuck

- Check that **auto-deploy for pull requests** is enabled in your service settings.  
- Ensure the **Git app webhook** is correctly configured and hasn’t been disabled by your Git provider.  
- If the pull request comes from a fork, the deployment may be waiting for **manual approval**.  

#### No comment on the pull request

- The Git app needs write access to post comments.  
  Verify that the app has the required permissions under your repository’s **installed integrations**.  
- Check if commenting is disabled for bots or third-party apps in your repository settings.  

#### Preview not updating on new commits

- Make sure the preview was created with `"commit_sha": "HEAD"` (for branch-based previews).  
- If it was triggered manually with a specific commit SHA, new commits will be ignored.  

---

<Aside type="tip" title="Still stuck?">
You can always check detailed deployment logs from the **Service > Deployments** tab or redeploy the application manually via the dashboard.
</Aside>

# Triggering preview environments via API

import {Aside} from '@astrojs/starlight/components';

> Introduced in [**v1.12.0**](/changelog/v112)

You can use the [API](/api-reference/openapi/#tag/trigger-preview) to **programmatically trigger preview environments**.  
This gives you more control and flexibility over how previews are created and linked to your Git workflow.  

The main way to predefine preview behavior is through [preview templates](./a-preview-templates),  
which let you configure which services are cloned, what environment variables to use, and other parameters.  

You can trigger preview environments via the API and associate them with either a **branch** or a **pull request**.  

---

### Getting the trigger URL

Preview environments are always linked to a **Git service**.  
To find the API endpoint used to trigger a preview, go to:  

**Service details → Settings → Deploy section**

<img className="block dark:hidden" src={`/images/preview-deploy-url-light.png`} alt="Preview env trigger webhook URL" />
<img className="!hidden dark:!block" src={`/images/preview-deploy-url-dark.png`} alt="Preview env trigger webhook URL" />



### Triggering a preview environment from a branch

You can trigger a preview for a specific branch.  
If you set `"commit_sha": "HEAD"`, the preview will automatically update on each new push to the branch.  
If you provide a specific commit SHA instead, future pushes to that branch will be ignored.

```http
### Request
POST /api/trigger-preview/{deploy_token}
Content-Type: application/json

{
  "branch_name": "feat/experiment-a",
  "commit_sha": "HEAD"
}
```


### Triggering a preview environment from a pull request

You can also trigger previews tied to a pull request.
This is commonly used to spin up an environment for review as soon as a PR is opened.

```http
### Request
POST /api/trigger-preview/{deploy_token}
Content-Type: application/json

{
  "pr_number": 511
}
```

<Aside type='tip' title='PR integration'>
When tying the preview to a pull request, you will receive the same comment appearing on the pull request as if 
you triggered from a pull request. 

<img className="block dark:hidden" src={`/images/pr-preview-comment-light.png`} alt="PR Preview comments" />
<img className="!hidden dark:!block" src={`/images/pr-preview-comment-dark.png`} alt="PR Preview comments" />

</Aside>

### Common arguments

You can control how previews are created by specifying a **template** and extra **environment variables**.
If you don’t pass a `template`, ZaneOps will use the project’s default preview template.

```http
### Request
POST /api/trigger-preview/{deploy_token}
Content-Type: application/json

{
  "branch_name": "feat/experiment-a",
  "template": "a-b-testing", // template slug
  "env_variables": [
    {
      "key": "V3_ENABLE_SSO",
      "value": "true"
    }
  ]
}
```

# Shared volumes

> Introduced in [**v1.13.0**](/changelog/v113)

> TODO...

# SSH keys

import {Steps, Aside} from '@astrojs/starlight/components';

> Introduced in [**v1.10**](/changelog/v110)

To access your server through the ZaneOps web UI, you will need to use SSH keys.
Each key is associated with a user on your server.

![server shell screenshot](https://assets.zaneops.dev/images/server-shell.png)

### How to use SSH Keys

<Steps>
1. You can access the SSH keys in the settings.
    ![settings dropdown](https://assets.zaneops.dev/images/settings-dropdown.png)

2. Once there, you can create a new key with a **valid user on your server** and a name for the key.
    ![Create new SSH key](https://assets.zaneops.dev/images/create-ssh-key.png)

3. After clicking _"Add new Key"_, ZaneOps will generate a public/private key pair.
    You can then use the public key on your server.
    ![SSH key list](https://assets.zaneops.dev/images/ssh-key-list.png)

4. Next, you will need to add the key to your server in your user directory: 
    ```shell
    # create `~/.ssh` folder if it doesn't exist
    mkdir -p $HOME/.ssh 
    # create `~/.ssh/authorized_keys` file if it doesn't exist
    touch $HOME/.ssh/authorized_keys
    # Allow permissions to use `authorized_keys` for authentication with SSH
    chmod 600 $HOME/.ssh/authorized_keys
    ```

5. Copy the public SSH key and add it at the end of the file on a new line in `$HOME/.ssh/authorized_keys` 

    ![Copy public SSH key](https://assets.zaneops.dev/images/copy-public-ssh-key.png)

    <Aside type='caution' title='Warning'>
        You need to add the public SSH key in the folder of the user that you specified when creating the key. 
    </Aside>

6. You can now use the key to SSH to your server from ZaneOps:
    ![Login using SSH key](https://assets.zaneops.dev/images/login-via-ssh-key.png)
  
</Steps>

### Troubleshooting

1. **Cannot connect to PORT 22**: 

    ```shell
    Failed to connect to port 22: Connection refused
    ``` 

    You will need to modify the SSH port to **22** to have access through the web UI:
    ```shell
    # /etc/ssh/sshd_config
    #... other options
    Port 22
    #... other options
    ```

2. **Public key authentication is disabled**:

    ```shell
    Failed publickey for <username> from 192.168.1.100 port 22 ssh2: RSA SHA256:...
    ``` 
    You will need to enable it in the SSH configuration: 
    ```shell
    # /etc/ssh/sshd_config
    PubkeyAuthentication yes
    AuthorizedKeysFile .ssh/authorized_keys
    ```

# Zero-downtime deployments

import {Aside} from '@astrojs/starlight/components';


ZaneOps automatically attempts to deploy your app using the [blue/green deployment](https://en.wikipedia.org/wiki/Blue%E2%80%93green_deployment) strategy.
This ensures that your current version remains running and accessible while the new version is being deployed.

![New deployment starting](https://assets.zaneops.dev/images/new-deployment.png)

## Health Checks

To ensure your service is fully operational before switching it to production, we recommend using health checks.

Health checks provide an additional verification step during deployment and continuously monitor your app's health.

You can define a health check using either: 

- **Path**: ZaneOps will check that the specified endpoint returns a response with a succesful status code (`2xx`) during deployment.

    <img className="block dark:hidden" src="https://assets.zaneops.dev/images/healthcheck-path-light.png" alt="Service settings page - Healthcheck path section" />
    <img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/healthcheck-path-dark.png" alt="Service settings page - Healthcheck path section" />

- **Command**: ZaneOps will execute the specified command and ensure it exits with code `0`.

    <img className="block dark:hidden" src="https://assets.zaneops.dev/images/healthcheck-cmd-light.png" alt="Service settings page - Healthcheck command section" />
    <img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/healthcheck-cmd-dark.png" alt="Service settings page - Healthcheck command section" />

For each new deployment, ZaneOps creates a monitoring job with the following settings:

- **Interval**: Specifies how often the health check runs.
- **Timeout**: Used only during the initial deployment, not for continuous monitoring.



<Aside type="tip" title="Good to Know">  
If you don’t specify a health check, ZaneOps will only verify that the service container starts correctly and will continuously monitor that it remains running.

The default values for **timeout** and **interval** are both **30 seconds**.
</Aside>  


## Situations That Disable Zero-Downtime Deployment

Zero-downtime deployment is disabled in two cases:

1. **When exposing ports**: To prevent conflicts with already exposed ports.

    <img className="block dark:hidden" src="https://assets.zaneops.dev/images/zero-downtime-warning-port-light.png" alt="Warning for exposed ports disabling zero-downtime deployment" />
    <img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/zero-downtime-warning-port-dark.png" alt="Warning for exposed ports disabling zero-downtime deployment" />

2. **When adding volumes without a host path**: To prevent conflicting writes to the same path.

    <img className="block dark:hidden" src="https://assets.zaneops.dev/images/zero-downtime-warning-volume-light.png" alt="Warning for volume configuration disabling zero-downtime deployment" />
    <img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/zero-downtime-warning-volume-dark.png" alt="Warning for volume configuration disabling zero-downtime deployment" />

    However, volumes with a **host path** still allow zero-downtime deployments, as ZaneOps mounts them in **read-only** mode.

If zero-downtime deployment is disabled for a service, ZaneOps will put the previous version to sleep while deploying the new version, making it temporarily inaccessible.

![Zero downtime disabled](https://assets.zaneops.dev/images/zero-downtime-disabled.png)

<Aside type="tip" title="Good to Know">  
If the new version of the service fails the health check, ZaneOps will restart the previous version if it was put to sleep.
</Aside>

# Reset password

You can reset your user's password if you forget it by running this command : 

```shell
make reset-password user=<your-username>
```

# Screenshots

### Onboarding

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/create-user-light.png" alt="onboarding page with a form for creating the first user" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/create-user-dark.png" alt="onboarding page with a form for creating the first user" />


### Login

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/login-light.png" alt="Login page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/login-dark.png" alt="Login page" />

### Dashboard


<img className="block dark:hidden" src="/images/new-dashboard-light.png" alt="Dashboard page" />
<img className="!hidden dark:!block" src="/images/new-dashboard-dark.png" alt="Dashboard page" />

### Project detail

<img className="block dark:hidden" src="/images/new-project-detail-light.png" alt="New project detail page" />
<img className="!hidden dark:!block" src="/images/new-project-detail-dark.png" alt="New project detail page" />


### Creating a Project


<img className="block dark:hidden" src="https://assets.zaneops.dev/images/create-project-light.png" alt="Create project page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/create-project-dark.png" alt="Create project page" />


### Create service

1. Create Docker service :

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/create-service-step1-light.png" alt="Create docker service step 1" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/create-service-step1-dark.png" alt="Create docker service step 1" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/create-service-step2-light.png" alt="Create docker service step 2" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/create-service-step2-dark.png" alt="Create docker service step 2" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/create-service-step3-light.png" alt="Create docker service step 3" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/create-service-step3-dark.png" alt="Create docker service step 3" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/create-service-step4-light.png" alt="Create docker service step 4" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/create-service-step4-dark.png" alt="Create docker service step 4" />

### Service Detail

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/service-detail-light.png" alt="Service detail page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/service-detail-dark.png" alt="Service detail page" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/service-detail-combobox-light.png" alt="Service detail page with combobox for deployment status open" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/service-detail-combobox-dark.png" alt="Service detail page with combobox for deployment status  open" />


### Runtime Logs page

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/deployment-detail-light.png" alt="service runtime logs page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/deployment-detail-dark.png" alt="Service runtime logs page" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/logs-filter-light.png" alt="service runtime logs page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/logs-filter-dark.png" alt="Service runtime logs page" />


<img className="block dark:hidden" src="https://assets.zaneops.dev/images/logs-max-light.png" alt="service runtime logs page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/logs-max-dark.png" alt="Service runtime logs page" />


<img className="block dark:hidden" src="https://assets.zaneops.dev/images/logs-octane-light.png" alt="service runtime logs page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/logs-octane-dark.png" alt="Service runtime logs page" />


### HTTP Logs page

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/http-logs-light.png" alt="service http logs page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/http-logs-dark.png" alt="Service http logs page" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/http-logs-with-details-open-light.png" alt="service http logs page with a request" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/http-logs-with-details-open-dark.png" alt="Service http logs page with a request" />


### Service metrics page

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/service-metrics-light.png" alt="service metrics page showing CPU and memory usage" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/service-metrics-dark.png" alt="Service metrics page showing CPU and memory usage" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/service-metrics-net-light.png" alt="service metrics page showing network I/O and disk I/O" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/service-metrics-net-dark.png" alt="service metrics page showing network I/O and disk I/O" />


### Service environment variables page

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/service-envs-light.png" alt="service environment variables page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/service-envs-dark.png" alt="service environment variables page" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/service-envs-modal-light.png" alt="service environment variables page with a modal open for adding multiple environment variable page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/service-envs-modal-dark.png" alt="service environment variables page with a modal open for adding multiple environment variable page" />


### Service settings page

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/service-settings-1-light.png" alt="service settings page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/service-settings-1-dark.png" alt="service settings page" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/service-settings-2-light.png" alt="service settings page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/service-settings-2-dark.png" alt="service settings page" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/service-settings-3-light.png" alt="service settings page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/service-settings-3-dark.png" alt="service settings page" />

### Configuration files

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/service-settings-4-light.png" alt="service settings page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/service-settings-4-dark.png" alt="service settings page" />


### Changes modal

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/changes-modal-light.png" alt="service settings page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/changes-modal-dark.png" alt="service settings page" />

### Project Environments

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/project-environments-light.png" alt="project environments page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/project-environments-dark.png" alt="project environments page" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/project-clone-environment-light.png" alt="clone environment modal" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/project-clone-environment-dark.png" alt="clone environment modal" />


### New version popup

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/new-version-toast-light.png" alt="clone environment modal" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/new-version-toast-dark.png" alt="clone environment modal" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/new-version-modal-light.png" alt="project environments page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/new-version-modal-dark.png" alt="project environments page" />

### Creating git services 

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/create-git-service-light.png" alt="create git service page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/create-git-service-dark.png" alt="create git service page" />


### Terminal

    <img className="block dark:hidden rounded-md"  src="/images/terminal-light.png" alt="Terminal" />
    <img className="!hidden dark:!block rounded-md" src="/images/terminal-dark.png" alt="Terminal" />



> More to come ✨

# Stopping ZaneOps

This process will stop zaneops and scale down all services managed by zaneops to `0`, effectively removing all the running containers.
You can always restart everything using `make deploy`.

```shell
# Shut down ZaneOps and all managed services
make stop
```

# Templates Directory

import TemplatesSearch from "../../../components/templates/TemplatesSearch.astro";

<TemplatesSearch />

# Troubleshooting

import { ASSETS_SERVER_DOMAIN } from "astro:env/client"
import {Steps, Aside} from '@astrojs/starlight/components';

In this section, we provides solutions for resolving issues you might encounter with ZaneOps.

## ZaneOps installation is stuck

ZaneOps typically takes less than 5 minutes to start. If it's stuck longer than that, it may be due to several possible issues.
```shell
# make deploy
====== Deploying ZaneOps with HTTPS 🔒 ======
# other logs...
🏁 Deploy initiated
Waiting for all services to reach desired state, this should take less than 5 minutes... ◐
```

### General debugging steps

To check that ZaneOps started correctly: 

<Steps>
1. You need to verify that all ZaneOps docker services started correctly:
   ```shell
   docker service ls --filter label="zane.stack=true"
   ```

   You should have an output like this in the terminal where `1/1` means **OK** except for `zane_temporal-admin-tools` which should be `0/1 (1/1 completed)` :
   ```shell
    ID             NAME                            MODE             REPLICAS              IMAGE                                                 PORTS
    inpyph774s3l   zane_app                        replicated       1/1                   ghcr.io/zane-ops/app:canary                           
    otewzijsmzaj   zane_db                         replicated       1/1                   postgres:16-alpine                                    
    adv0qcj7fqga   zane_fluentd                    replicated       1/1                   fluentd:v1.16.2-1.1                                   
    fa7t7r508bd9   zane_loki                       replicated       1/1                   grafana/loki:3.4                                      
    kisb92em589i   zane_pgbouncer                  replicated       1/1                   edoburu/pgbouncer:v1.23.1-p3                          
    t432gf67whmx   zane_proxy                      replicated       1/1                   ghcr.io/zane-ops/proxy:canary                         
    ux5vuucsm9cv   zane_temporal-admin-tools       replicated job   0/1 (1/1 completed)   temporalio/admin-tools:1.24.2-tctl-1.18.1-cli-1.0.0   
    flwwyuihygay   zane_temporal-main-worker       replicated       1/1                   ghcr.io/zane-ops/app:canary                           
    wldqkpahhuyr   zane_temporal-schedule-worker   replicated       1/1                   ghcr.io/zane-ops/app:canary                           
    m8wk18qer4ys   zane_temporal-server            replicated       1/1                   temporalio/auto-setup:1.24.2                          
    limmbrl9o0ub   zane_valkey                     replicated       1/1                   valkey/valkey:7.2.5-alpine                            
   ```
2. If one of the services is not starting correctly, you can check the tasks for the service with:

   ```shell
   docker service ps zane_{service} # ex: `zane_app` 
   ```

   You should get an output similar to this where the latest task (the first task from the top) state is `Running`:
   ```shell {2} 
   ID             NAME             IMAGE                         NODE      DESIRED STATE   CURRENT STATE          ERROR                              PORTS
   7b21smevkj6l   zane_app.1       ghcr.io/zane-ops/app:canary   ubs01     Running         Running 2 hours ago                                 
   ppfheeofce3t    \_ zane_app.1   ghcr.io/zane-ops/app:canary   ubs01     Shutdown        Shutdown 2 hours ago                                      
   ```

3. If the latest task state show `Failed`, you can check the logs of the failed status: 
    ```shell
    docker inspect --format '{{ json .Status }}' <TASK-ID> | jq # ex: `7b21smevkj6l` the ID above
    ```

    You will get a JSON object like this:
    ```json {5}
    {
        "Timestamp": "2025-07-16T19:31:21.277975012Z",
        "State": "failed",
        "Message": "started",
        "Err": "No such container: zane_app.1.ypqk8horkrofmsij7r6xtn7kf",
        // ... other fields
    }
    ```

    The `Err` field might have a full explanation of the error. 
    
    Examples:
      - **"no suitable node (host-mode port already in use on 1 node)"**: meaning the port is already used by another service
      - **"invalid pool request: Pool overlaps with other one in this address space"**: meaning the address pool (subnet) is already used by another network

4. You can also see the application logs of the services using: 
   ```shell
   docker service logs zane_{service}
   ``` 

   <Aside type="caution" title="main app logs">
    Running logs for `zane_app` might not show you any actionable logs. You can instead run: 

    ```shell
    # to see error logs
    docker exec -it $(docker ps -qf "name=zane_app") /bin/bash -c "cat /app/logs/daphne/stderr"
    # to see access logs
    docker exec -it $(docker ps -qf "name=zane_app") /bin/bash -c "cat /app/logs/daphne/stdout"
    ```
   </Aside>

5. Still stuck? [create an issue](https://github.com/zane-ops/zane-ops/issues/new?template=bug_report.md)
</Steps>


### Something is running on either port `80` or `443`

ZaneOps’ proxy (Caddy) uses ports 80 & 443 to expose applications.
If another app is using these ports, ZaneOps won’t start.

<Aside type="note" title="Solution">
Stop the applications running in those ports.
</Aside>

If you must use another proxy alongside ZaneOps, you can run it as a service inside ZaneOps and proxy requests internally using the service's network alias:
<img src={`${ASSETS_SERVER_DOMAIN}/images/proxy-inception.png`} alt="running a proxy inside Zaneops" />

```nginx "service-xyz.zaneops.internal" {"Your service network alias: ":7}
#/etc/nginx/nginx.conf
server {
    listen 80;
    server_name xyz.com;

    location / {

        proxy_pass http://service-xyz.zaneops.internal:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```


### Another network already uses the subnet

ZaneOps services share a common docker network: `zane` <br/>
If another network already uses its subnet, ZaneOps won't start.

<Aside type="note" title="Solution">
Delete and recreate ZaneOps network with a free subnet.
</Aside>

First list all docker networks and their subnets:

```shell
docker network ls -q | xargs docker network inspect -f '{{.Name}}: {{range .IPAM.Config}}{{.Subnet}}{{end}}'
```

You should see zane network and another one sharing the same subnet:

```shell
bridge: 10.0.0.0/24
host:
none:
my_network: 10.0.1.0/24
zane: 10.0.1.0/24
```

Make sure to stop all ZaneOps remaining processes:

```shell
# assuming you are in /var/www/zaneops
make stop
```

You can proceed to delete `zane` network:

```shell
docker network rm zane
```

Then recreate the network with a subnet not in use, for example: `172.28.0.0/16`

```shell "--attachable" "--driver overlay"  "--label zane.stack=true"
docker network create --attachable --driver overlay --label zane.stack=true  --subnet 172.28.0.0/16 zane
```

<Aside type="caution" title="Warning">
The network needs to be attachable and with the label `zane.stack=true` or else it might cause unwanted errors.
</Aside>

Restart ZaneOps

```shell
# assuming you are in /var/www/zaneops
make deploy
```


### You are connected to GitHub Container Registry (`ghcr.io`)

ZaneOps images are hosted on GitHub Container Registry (public). 
Auth conflicts may happen if your token is not longer valid.

To check if you are connected:

```shell
cat ~/.docker/config.json
```

If `ghcr.io` appear in the `auths` key, you are authenticated to GitHub container:

```jsonc
{
    "auths": {
         "https://ghcr.io": {}
    },
    // other keys ...
}
```

<Aside type="note" title="Solution">
Logout from the container registry
```shell
docker logout ghcr.io
```
You may need to login again to the container registry with a new valid access token
</Aside>


Note that you can also deploy any application hosted on a private container registry by specifying 
the credentials in the **source** in the service settings page:

<img src={`${ASSETS_SERVER_DOMAIN}/images/docker-credentials.png`} alt="Docker credentials" />


### Issues with a VPN

You might get this error if you have a VPN installed:
```shell {7}
$ docker inspect --format '{{ json .Status }}' <task-id> | jq 

{
        "Timestamp": "2025-07-16T19:31:21.277975012Z",
        "State": "failed",
        "Message": "started",
        "Err": "network sandbox join failed: subnet sandbox join failed for \"10.0.1.0/24\": error creating vxlan interface: operation not supported",
        # ... other fields
}
```

This error means Docker couldn't create a VXLAN interface—usually due to missing kernel modules or VPN conflicts.

<Aside type="note" title="Potential solution">
The best solution is to disable the VPN and restart ZaneOps: 

```shell
# assuming you are in /var/www/zaneops
make stop
make deploy
```

In other cases, you can try solutions outlined here: 
https://forums.docker.com/t/debian-9-error-creating-vxlan-interface-operation-not-supported-resolved/39995/8
</Aside>

## Service metrics aren't shown in the dashboard

If your app deployed successfully but no metrics appear (usually after ~30s), 
it may be because [cgroups](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/cgroups.html) are not enabled on your server.

<img src={`${ASSETS_SERVER_DOMAIN}/images/empty-metrics.png`} alt="Empty metrics" />


<Aside type="note" title="Solution">
Enable cgroups. Here are some resources for how to do so in debian/ubuntu: 

- [Enabling memory cgroup in Ubuntu 20.04](https://askubuntu.com/questions/1237813/enabling-memory-cgroup-in-ubuntu-20-04)
- [What is required to activate cgroups in Linux](https://serverfault.com/questions/525162/what-is-required-to-activate-cgroups-in-linux)
</Aside>

# Bun function

import { Aside, Steps } from '@astrojs/starlight/components';

## Introduction

Railway recently introduced [functions support](https://railway.com/changelog/2025-02-07-railway-functions#railway-functions) 
based on bun. It allows you to quickly wip up a simple API.

You can achieve the same thing in ZaneOps too leveraging our [Config files](/knowledge-base/config-files) feature.

### Live demo

You can find a production version of this application at: https://bun-function.fkiss.me

## Prerequisites

- A working ZaneOps instance. If you need help with installation, refer to our [ZaneOps setup guide](/installation).



## Process

<Steps>
1. Create a Docker service using `oven/bun` image:
    ![Creating the bun service](https://assets.zaneops.dev/images/tuto-bun-fn-new-service.png)

2. Go to the service settings page and add a new config file with the the mount path of `/app/index.ts` containing your code:
    ![Config file content](https://assets.zaneops.dev/images/tuto-bun-fn-config-file.png)

    ```ts
    // /app/index.ts
    // index.tsx (Bun v1.2 runtime)
    import { Hono } from "hono@4";
    import { cors } from 'hono/cors';

    const app = new Hono();

    app.use("/*", cors());
    app.get("/", (c) => c.text("Hello world!"));
    app.get("/api/health", (c) => c.json({ status: "ok" }));

    Bun.serve({
        port: import.meta.env.PORT ?? 3000,
        fetch: app.fetch,
    });
    ```

3. Update the start command to run the script on startip:
   ```shell
   bun run /app/index.ts
   ```
    ![Updating the start command](https://assets.zaneops.dev/images/tuto-bun-fn-command.png)

4. Add a URL to the service Forwarded to the port `3000`:
    ![Adding a URL to the service](https://assets.zaneops.dev/images/tuto-bun-fn-create-url.png)

5. Deploy the service:
    ![service successfully deployed](https://assets.zaneops.dev/images/tuto-bun-fn-deploy.png)
</Steps>

# React Router v7 app with SSR

import { Aside, Steps } from '@astrojs/starlight/components';

## Introduction

[React Router v7](https://reactrouter.com) has evolved into a comprehensive full-stack web framework that prioritizes user interface development while leveraging web standards to create fast, responsive, and resilient applications. This guide walks you through deploying a React Router v7 application on ZaneOps.

### Live demo

You can find a production version of this application at: https://guestbook.fredkiss.dev


## Prerequisites

- A working ZaneOps instance. If you need help with installation, refer to our [ZaneOps setup guide](/installation).

## Deployment Process

### Project Overview

We'll be working with a fully-featured guestbook application built with React Router v7. You can clone or fork the repository:

```shell
git clone https://github.com/zane-ops/guestbook.git
```

This application showcases several key features:
- **Authentication**: login/register with username+password with sessions stored in Redis
- **Data persistence**: Message storage in PostgreSQL with Drizzle ORM
- **Modern architecture**: Full server-side rendering with progressive enhancement (works even with JavaScript disabled)

![Guestbook in action](https://assets.zaneops.dev/images/guestbook-screenshot.png)


### Creating a ZaneOps Project

Log in to your ZaneOps dashboard and create a new project named **guestbook**:

![Creating a new project in ZaneOps](https://assets.zaneops.dev/images/tuto-rr7-new-project.png)
![Successfully created project](https://assets.zaneops.dev/images/tuto-rr7-project-created.png)

### Configuring Database and Caching Services

#### Setting up Redis with Valkey

First, we'll create a Redis-compatible service using [Valkey](https://valkey.io/), an open-source Redis alternative:

<Steps>
1. Create a Docker service with the `valkey/valkey` image:
    ![Creating a Valkey service](https://assets.zaneops.dev/images/tuto-rr7-create-valkey.png)
2. Deploy the service:
    ![Valkey service created](https://assets.zaneops.dev/images/tuto-rr7-valkey-created.png)
3. Verify the deployment status on the service details page:
    ![Successful Valkey deployment](https://assets.zaneops.dev/images/tuto-rr7-valkey-deployed.png)
</Steps>

#### Setting up PostgreSQL

Next, let's configure a PostgreSQL database service:

<Steps>
1. Create a Docker service using the official `postgres` image:
    ![Creating a PostgreSQL service](https://assets.zaneops.dev/images/tuto-rr7-create-pg.png)

2. Configure the necessary environment variables by navigating to the service details page and selecting the environment variables tab:
    ![PostgreSQL environment configuration](https://assets.zaneops.dev/images/tuto-rr7-pg-env-tab.png)

3. Click **Add from .env** and enter these database credentials:
   ```shell
    POSTGRES_DB="guestbook"
    POSTGRES_USER="guestbook"
    POSTGRES_PASSWORD="guestbook"
   ```
    ![Adding PostgreSQL environment variables](https://assets.zaneops.dev/images/tuto-rr7-pg-env-modal.png)
    ![Environment variables successfully added](https://assets.zaneops.dev/images/tuto-rr7-pg-env-added.png)

4. Configure data persistence by adding a volume in the settings tab set it's **container path** to `/var/lib/postgresql/data` :
    ![Adding a volume for PostgreSQL data](https://assets.zaneops.dev/images/tuto-rr7-pg-add-volume.png)

5. Review your configuration and deploy the service:
    ![Reviewing PostgreSQL configuration changes](https://assets.zaneops.dev/images/tuto-rr7-pg-changes.png)
    ![PostgreSQL service successfully deployed](https://assets.zaneops.dev/images/tuto-rr7-pg-deployed.png)
</Steps>

### Deploying the Main Application

Now let's deploy the guestbook application itself:

<Steps>
1. Create a new Git service using the repository url `https://github.com/zane-ops/guestbook`:
    ![Creating the main application service](https://assets.zaneops.dev/images/tuto-rr7-create-gb-app.png)
    
2. Configure the authentication environment variables:
    ```shell
    SESSION_DOMAIN="guestbook.127-0-0-1.sslip.io"
    SESSION_SECRET="yoursupersecretvalue"
    SESSION_SECURE="false"
   ``` 
   ![Adding authentication environment variables](https://assets.zaneops.dev/images/tuto-rr7-gb-env-1.png)
   <Aside type='note'>
   For production environments, always set `SESSION_SECURE` to `true` to enforce HTTPS for session authentication.
   </Aside>

3. Configure database and cache connection strings using service network aliases:

   First, locate the Redis network alias on the **Redis service details page > settings > Networking section**:
   ![Finding the Redis network alias](https://assets.zaneops.dev/images/tuto-rr7-alias-redis.png)

   Add the Redis connection string as an environment variable:
   ```shell
   REDIS_URL="redis://<redis_network_alias>:6379"
   ```
   ![Adding Redis connection environment variable](https://assets.zaneops.dev/images/tuto-rr7-gb-env-2.png)

   Next, locate the PostgreSQL network alias on the **PostgreSQL service details page > settings > Networking section**:
   ![Finding the PostgreSQL network alias](https://assets.zaneops.dev/images/tuto-rr7-alias-pg.png)

   Add the PostgreSQL connection string as an environment variable:
   ```shell
   DATABASE_URL="postgresql://guestbook:guestbook@<postgres_network_alias>:5432/guestbook"
   ```
   ![Adding PostgreSQL connection environment variable](https://assets.zaneops.dev/images/tuto-rr7-gb-env-3.png)
   
4. Configure public access by adding a domain:
    Navigate to the **service details page > settings > Networking section > URLS** and create a URL entry with:
    - Domain: `guestbook.127-0-0-1.sslip.io`
    - Forwarded port: `3000` (the application's listening port)

    ![Configuring public access](https://assets.zaneops.dev/images/tuto-rr7-gb-add-url.png)

5. Implement a health check to ensure reliable deployments:
   Navigate to **service details page > settings > Deploy section > Healthcheck** and configure:
   - Type: `Path`
   - Value: `/api/health`
   - Listening port: `3000`

   ![Adding a health check](https://assets.zaneops.dev/images/tuto-rr7-gb-add-healthcheck.png)

6. Review all configuration changes and deploy the service:
   ![Reviewing the application configuration](https://assets.zaneops.dev/images/tuto-rr7-gb-changes-modal.png)

7. Monitor the deployment logs to ensure everything is working correctly:
   ![Deployment completion status](https://assets.zaneops.dev/images/tuto-rr7-gb-deployed.png)
   ![Checking deployment logs](https://assets.zaneops.dev/images/tuto-rr7-gb-logs.png)
   
8. Once deployed successfully, your application will be available at http://guestbook.127-0-0-1.sslip.io
   ![Guestbook application running](https://assets.zaneops.dev/images/tuto-rr7-gb-demo.png)
</Steps>

### Setting Up Continuous Deployment

Automate your deployment workflow with GitHub Actions to update your application whenever changes are pushed to your repository:

<Steps>
1. Get your ZaneOps deployment webhook URL:
   Navigate to **main app service details page > settings > Deploy section > deploy webhook url**
   ![Locating the deployment webhook URL](https://assets.zaneops.dev/images/tuto-rr7-webhook-url.png)
   
2. Store your secrets in GitHub:
   Navigate to **GitHub repository > settings > secrets and variables > actions** and add:
   - `DEPLOY_WEBHOOK_URL`: Your ZaneOps webhook URL
   ![Adding repository secrets](https://assets.zaneops.dev/images/tuto-rr7-secrets.png)
   
3. Create a GitHub Actions workflow file in your repository:
    ```yaml
    # .github/workflows/ci.yaml
    name: Deploy
    on:
      push:
        branches: [main] # customize as needed
    jobs:
      build-push-app:
        name: Build and Deploy Guestbook
        runs-on: ubuntu-latest
        steps:
            - name: Checkout
              uses: actions/checkout@v4
            - name: Deploy to ZaneOps
              run: curl -f -o /dev/null -X PUT "${{ secrets.DEPLOY_WEBHOOK_URL }}" 
    ```
5. With this workflow in place, changes pushed to your main branch will automatically trigger a new build and deployment
    ![Service deployed via github](https://assets.zaneops.dev/images/tuto-rr7-github-deploy.png)
</Steps>

# Uninstalling ZaneOps

import {Aside} from '@astrojs/starlight/components';


This process will stop and delete all services managed by zaneops including zaneops itself : 

```shell
# Delete ZaneOps and all managed services
make delete-resources
```

<Aside type="note" title="Information">
This will run `docker system prune -f --volumes` at the end. 
</Aside>

# Upgrading ZaneOps

import { Aside} from '@astrojs/starlight/components';

<Aside type="tip">
While zaneops is being upgraded, all your services will still be available, including the zaneops dashboard. 
</Aside>

### Upgrading zaneops via the UI

> Introduced in [**v1.7.0**](/changelog/v17)

When a new version of ZaneOps is available, you will get a toast notification in the dashboard, allowing you to 
update via the UI :

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/new-version-toast-light.png" alt="clone environment modal" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/new-version-toast-dark.png" alt="clone environment modal" />

<img className="block dark:hidden" src="https://assets.zaneops.dev/images/new-version-modal-light.png" alt="project environments page" />
<img className="!hidden dark:!block" src="https://assets.zaneops.dev/images/new-version-modal-dark.png" alt="project environments page" />



### Upgrading zaneops via the terminal

zaneops is updated automatically to the version specified in the `.env` file in `IMAGE_VERSION`. 
However if you use the `canary` version, you will automatically be updated to the latest version on the `main` branch, **which can contain breaking changes ⚠️**.

To update the version, change it in `.env` : 

```shell
# /var/www/zaneops/.env
IMAGE_VERSION="v1.11.1"
# ... other env variables
```

Then deploy again with : 

```shell
make setup # re-download configuration files to run zaneops 
make deploy
```

<Aside type="caution" title='Auto update'>
  When switching to `canary` if your env file, you don't get notification popups for when there are new versions.
  You need to manually upgrade the version in the `.env` file if you want to get new versions popups.

```shell
# /var/www/zaneops/.env
IMAGE_VERSION="v1" # automatically the latest `v1.x` version
# ... other env variables
```

</Aside>