Skip to content
ZaneOps documentation

Installing ZaneOps

ZaneOps is a deployment platform that simplifies the process of managing and deploying web applications. This guide will walk you through the steps to install ZaneOps either locally or on a remote server with minimal configuration.

Prerequesites

  • Ensure you have Docker 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 :
    Terminal window
    # on Linux
    sudo apt install make curl jq openssl
    

    # on Mac
    brew install make curl jq openssl

Process

  1. Create the installation directory:

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

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

  2. Download the makefile for the project :

    Terminal window
    curl https://raw.githubusercontent.com/zane-ops/zane-ops/main/deploy.mk > Makefile

  3. Launch the setup process :

    Terminal window
    make setup

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

    • Directoryzaneops
      • Directory.fluentd/
        • …
      • Directorytemporalio
        • Directoryconfig
          • development.yaml
        • entrypoint.sh
      • docker-stack.prod-http.yaml
      • docker-stack.prod.yaml
      • .env
      • Makefile

  4. Update environment variables in .env : The setup process will generate sane defaults for environment variables, but you can modify the contents to better suit your needs (see here for how to customize):

    /var/www/zaneops/.env
    # Example configuration - Modify before production use
    IMAGE_VERSION=canary # ZaneOps version to install
    ZANE_APP_DIRECTORY="/var/www/zaneops" # Installation directory for ZaneOps
    ZANE_DB_USER= # Generate with: "curl -s https://randomuser.me/api/ | jq -r '.results[0].login.username'"
    ZANE_DB_PASSWORD= # Generate with: "$(openssl rand -base64 32)"
    DJANGO_SECRET_KEY= # Generate with: "$(openssl rand -base64 64)"
    

    # ⚠️ Update if ZaneOps is not hosted locally ⚠️
    ROOT_DOMAIN="127-0-0-1.sslip.io" # Root domain for generating app domains
    ZANE_APP_DOMAIN="127-0-0-1.sslip.io" # Domain for ZaneOps dashboard

  5. Deploy ZaneOps :

    Terminal window
    make deploy

  6. Create your first user to login to the dashboard :

    Terminal window
    make create-user

  7. Log in to the dashboard by connecting to the domain specified in ZANE_APP_DOMAIN. If hosted locally (see instructions below), you can use http://127-0-0-1.sslip.io.

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

Additional Commands

Use these commands for managing your ZaneOps installation:

Terminal window
# Shut down ZaneOps
make stop


# Delete ZaneOps and all its associated resources
make delete-resources

Updating zaneops

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 version.

To update the version, change the version in .env :

/var/www/zaneops/.env
IMAGE_VERSION="v2"
# ... other env variables

Then deploy again :

Terminal window
make deploy

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 :

    /var/www/zaneops/.env
    # ... other env variables
    __DANGEROUS_ALLOW_HTTP_SESSION="true"

  • run the deploy command :

    Terminal window
    make deploy