Installing ZaneOps

Quick-start

You can install ZaneOps with one script:

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 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 :

  # 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

1. Initialize Docker Swarm:

   docker swarm init --advertise-addr <MANAGER_IP>

   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), use 127.0.0.1.

2. Create the installation directory:

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

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

3. Download the makefile for the project:

   curl https://cdn.zaneops.dev/makefile > Makefile

   The source code for this file is available on github.

4. Launch the setup process:

   make setup

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

   • Directoryzaneops

     • Directory.fluentd/

       • …
     • Directorytemporalio/

       • …
     • docker-stack.prod-http.yaml
     • docker-stack.prod.yaml
     • .env
     • fluent.conf
     • Makefile

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 ?

   /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:

   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 :

   

   Installing locally

   Please continue with the instructions below if you are installing ZaneOps locally.

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 :

  /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 :

  /var/www/zaneops/.env

  # ... other env variables
  MODE=http
  __DANGEROUS_ALLOW_HTTP_SESSION="true"

• be sure to top zaneops first :

  make stop

• run the deploy command :

  make deploy

• You can now access zaneops dashboard at http://127-0-0-1.sslip.io

  __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 for more info.

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 (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://