Zioan VPS Installation Guide

Complete step-by-step guide for deploying Zioan on your own server.

Important Notice

This guide represents the ideal environment setup for most deployment scenarios. Please note:

- 99% of these steps are host environment configuration (Ubuntu, Docker, Nginx, Cloudflare, etc.)
- The actual Zioan installation takes only 2 minutes if your host environment is already properly configured
- Core requirements for Zioan installation:
- - Nginx reverse proxy configuration
- - Internet connectivity for the deployment script
- - Meeting the basic system requirements for your team size

Flexible Installation Options:
- Zioan can be installed on any compatible environment that meets the bare minimum requirements
- This Ubuntu VPS setup is recommended but not mandatory
- Alternative setups (different Linux distributions, cloud providers, etc.) are supported

Installation & Management Command

This single command handles fresh installations, updates, backups, and rollbacks automatically:

Replace YOUR_CLIENT_ID with the Client ID from your account dashboard.

Choose Your Deployment Method

Why Caddy is Recommended

- Automatic SSL certificates from Let's Encrypt - zero manual configuration
- No nginx setup or configuration files required
- Full video/audio call support out of the box
- Simpler firewall rules and maintenance

Prerequisites

Before You Start - Technical Requirements

- Comfortable using command line/terminal
- Ability to connect to servers via SSH
- Domain nameserver management access

Required Accounts & Services

- Domain name (from any registrar)
- VPS with static IP (Hetzner, DigitalOcean, Linode, Vultr, etc.)
- Zioan license with Client ID

Step 1: System Preparation

# Connect to your VPS via SSH

ssh root@YOUR_VPS_IP

# Update system

apt update && apt upgrade -y

# Install required packages (NO nginx needed for Caddy setup)

apt install -y dialog curl openssl docker.io docker-compose-v2

# Start and enable Docker

systemctl start docker && systemctl enable docker

# Verify Docker installation

docker --version && docker compose version

Step 2: Create Installation Directory

# Create and navigate to installation directory

mkdir -p /opt/zioan-workflow && cd /opt/zioan-workflow

Step 3: Domain DNS Setup

DNS Configuration (Simple)

1. Create an A record at your domain registrar:
- - Type: A
- - Name: @ (for root domain) or subdomain name
- - Value: YOUR_VPS_IP (your server's public IP address)
- - TTL: Auto or 300
2. Wait for DNS propagation (usually 5-15 minutes, can take up to 48 hours)
3. Verify DNS is pointing to your server:
nslookup yourdomain.com
Should return your server's IP address

Important: If using Cloudflare, set the proxy status to "DNS only" (gray cloud), NOT "Proxied" (orange cloud). Caddy needs direct access to your server for SSL certificate issuance, and video/audio calls require direct UDP access.

Step 4: Run Installation Script

Installation Command

Run this command on your server:

Replace YOUR_CLIENT_ID with the Client ID from your account dashboard. Don't have one yet? Register for a free trial.

The installation script will prompt you for:

1. Domain name (enter: example.com or subdomain.example.com)
2. Enable automatic HTTPS with Caddy?
Select YES - this enables automatic SSL certificates
3. Admin account creation:
- - Admin username
- - Admin email address
- - Admin password

What happens automatically: Caddy obtains SSL certificates from Let's Encrypt, configures HTTPS, and handles all certificate renewals. No manual SSL setup required!

Step 5: Firewall Configuration

# Allow SSH

ufw allow 22/tcp

# Allow HTTP (for Let's Encrypt certificate verification)

ufw allow 80/tcp

# Allow HTTPS

ufw allow 443/tcp

# Allow TURN ports (for video/audio calls)

ufw allow 3479/udp && ufw allow 3479/tcp && ufw allow 5349/tcp

# Allow RTP media ports (for video/audio streams)

ufw allow 40000:40100/udp

# Enable firewall and check status

ufw enable && ufw status

Step 6: Verification and First Access

Verify containers are running:

docker ps

You should see containers including caddy, workflow_app, workflow_db, etc.

Access Your Application

1. Open in browser: https://yourdomain.com
2. Login with: Admin credentials created during installation

SSL certificate is automatically provisioned. If you see a certificate warning, wait a few minutes for Let's Encrypt to issue the certificate.

Advanced Setup - For Experienced Users

- Requires manual nginx configuration
- SSL handled by Cloudflare proxy (orange cloud mode)
- Video/audio calls will NOT work with Cloudflare proxy enabled
- Best for users who need Cloudflare DDoS protection and don't need video calls

Prerequisites

Before You Start - Technical Requirements

- Comfortable using command line/terminal
- Ability to connect to servers via SSH
- Basic text editing skills (nano/vim)
- Domain nameserver management access

Required Accounts & Services

- Domain name (from any registrar)
- VPS with static IP (Hetzner, DigitalOcean, Linode, Vultr, etc.)
- Cloudflare account (free tier is sufficient)
- Zioan license with Client ID

Server Requirements by Team Size

~5 Users

- 2 CPU cores

- 4GB RAM

- 40GB SSD

- Ubuntu 24.04 LTS

~20 Users

- 4 CPU cores

- 8GB RAM

- 80GB SSD

- Ubuntu 24.04 LTS

~50 Users

- 6-8 CPU cores

- 16GB RAM

- 160GB SSD

- Ubuntu 24.04 LTS

100+ Users

- 8+ CPU cores

- 32GB+ RAM

- 320GB+ SSD

- Ubuntu 24.04 LTS

Step 1: System Preparation

# Connect to your VPS via SSH

ssh root@YOUR_VPS_IP

# Update system and install required packages

apt update && apt upgrade -y

# Install required packages

apt install -y dialog curl openssl docker.io docker-compose-v2 nginx

# Start and enable Docker

systemctl start docker && systemctl enable docker

# Verify Docker installation

docker --version && docker compose version

Step 2: Create Installation Directory

# Create installation directory

mkdir -p /opt/zioan-workflow

# Navigate to installation directory

cd /opt/zioan-workflow

Important Directory Note:

This guide uses /opt/zioan-workflow as the installation directory. You can choose a different directory name if preferred. If you do, remember to update:

- Step 5: Nginx media files path (alias /opt/YOUR-DIRECTORY/mediafiles/)
- Docker commands referencing the installation path

Step 3: Domain and DNS Setup

Cloudflare Configuration

1. Add domain to Cloudflare:
- - Go to https://dash.cloudflare.com/
- - Click "Add a site"
- - Enter your domain name
- - Choose Free plan
2. Create DNS A record:
- - Type: A
- - Name: @ (for root domain)
- - IPv4 address: YOUR_VPS_IP
- - Proxy status: Proxied (orange cloud enabled)
- - TTL: Auto
3. Update nameservers:
Update nameservers at your domain registrar to Cloudflare's provided nameservers

Important - Video/Audio Calls: If you need video or audio calls, use DNS only mode (gray cloud) so your domain points directly to your server's IP. Cloudflare proxy (orange cloud) only handles HTTP traffic - WebRTC media (UDP) cannot pass through it.

Step 4: Run Installation Script

Installation Command

Run this command on your server to start the installation:

Replace YOUR_CLIENT_ID with the Client ID from your account dashboard. Don't have one yet? Register for a free trial.

The installation script will prompt you for:

1. Domain name (enter: example.com or subdomain.example.com)
- Do NOT include https:// or www prefix
- Examples: mycompany.com, workflow.mycompany.com
2. Admin account creation:
- - Admin username
- - Admin email address
- - Admin password
- - Confirm password
3. The system will then:
- - Authenticate with update server
- - Download and deploy the application
- - Configure environment variables
- - Start Docker containers
- - Wait for all services to initialize

Step 5: Nginx Configuration

Important Configuration Notes:

- Replace yourdomain.com with your actual domain name (same as entered in Step 4)
- Update /opt/zioan-workflow/mediafiles/ path if you used a different installation directory
- Replace YOUR_VPS_IP with your server's public IP address
- Ensure the indentation, syntax, and whitespace are correct
- We recommend copying the configuration below, making only the necessary substitutions in a text editor, and then pasting it into the nginx configuration file

# Create nginx site configuration

nano /etc/nginx/sites-available/zioan-workflow

Add this configuration:

server {
    listen 80;
    server_name yourdomain.com YOUR_VPS_IP;

    location / {
        proxy_pass http://localhost:8011;
        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;
    }

    # WebSocket support
    location /ws/ {
        proxy_pass http://localhost:8011;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
        proxy_read_timeout 86400;
    }

    # Static files - serve directly from container for better performance
    location /static/ {
        proxy_pass http://localhost:8011/static/;
        proxy_set_header Accept-Encoding "";
        proxy_buffering off;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # AI model files - larger files, no compression needed
    location /static/ai-models/ {
        proxy_pass http://localhost:8011/static/ai-models/;
        proxy_set_header Accept-Encoding "";
        proxy_buffering off;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Media files
    location /media/ {
        alias /opt/zioan-workflow/mediafiles/;
        expires 30d;
    }
}

# Enable the site

ln -s /etc/nginx/sites-available/zioan-workflow /etc/nginx/sites-enabled/

# Test configuration

nginx -t

# Restart nginx

systemctl restart nginx

Step 6: Firewall Configuration

# Allow SSH port

ufw allow 22/tcp

# Allow HTTP port

ufw allow 80/tcp

# Allow HTTPS port

ufw allow 443/tcp

# Allow STUN/TURN signaling port (required for video calls)

ufw allow 3479/tcp && ufw allow 3479/udp && ufw allow 5349/tcp

# Allow WebRTC media ports (UDP - for direct connections)

ufw allow 40000:40100/udp

# Allow WebRTC media ports (TCP - fallback for restricted networks)

ufw allow 40000:40100/tcp

# Enable firewall and check status

ufw enable && ufw status

Step 7: Verification and Testing

Test DNS resolution:

# Test DNS resolution (should return Cloudflare IPs)

nslookup yourdomain.com

Test HTTP/HTTPS access:

# Test HTTP access

curl -I http://yourdomain.com

# Test HTTPS access

curl -I https://yourdomain.com

Verify containers are running:

docker ps

Step 8: First Access and Setup

1. Access application: https://yourdomain.com
2. Login credentials: use admin username and password created during installation

Critical Configuration Points

Environment Variables:

- ALLOWED_HOSTS: Must include domain, IP, and localhost
- CSRF_TRUSTED_ORIGINS: Must include both HTTP and HTTPS versions
- Environment changes require: docker compose down && docker compose up -d

Cloudflare Settings:

- Proxy Status: Must be "Proxied" (orange cloud)
- SSL Mode: Full (automatic with Cloudflare)
- Remove conflicts: Delete any existing CNAME records for root domain

Deployment Options Summary

You are viewing the nginx + Cloudflare setup. For the recommended setup with automatic SSL and full video call support, .

Caddy Setup (Recommended)

- Domain points directly to server IP
- Automatic HTTPS via built-in Caddy
- Full video/audio call support
- All features work out of the box

nginx + Cloudflare (Current)

- Requires manual nginx configuration
- SSL via Cloudflare proxy
- Video/audio calls will NOT work with proxy
- Best for DDoS protection needs

Why static IP matters: Video/audio calls use WebRTC which requires UDP ports (40000-40100) to be directly accessible. Cloudflare Tunnel and proxies only handle HTTP/HTTPS (TCP), so media cannot flow through them.

Common Issues and Solutions

400 Bad Request Error:

- Check ALLOWED_HOSTS includes your domain
- Restart entire Docker stack, not just individual containers

Login Issues:

- Ensure HTTPS access (HTTP may have security restrictions)
- IP access may cause CSRF issues - use domain access after initial setup
- Clear browser cookies and cache
- Verify CSRF_TRUSTED_ORIGINS includes domain

Container Startup Issues:

- Check Docker logs: docker logs workflow_app
- Verify client ID authentication
- Ensure sufficient server resources

Video/Audio Call Issues:

- Can't see/hear remote participants: Ensure firewall ports 40000-40100 (UDP), 3479 (STUN/TURN), and 5349 (TURNS) are open
- Using Cloudflare Tunnel: Video/audio calls require direct UDP access. Cloudflare Tunnel only handles HTTP - use a VPS with static IP instead
- Using Cloudflare DNS proxy (orange cloud): Switch to DNS only mode (gray cloud) for video calls to work
- Connection timeouts: Check that ALLOWED_HOSTS in .env includes your domain
- One-way media: Restart the Docker stack: docker compose restart

Need Help?

For installation issues or questions about alternative deployment scenarios, please email us at hello@zioan.com or use our contact form - we'll be happy to assist you with your specific setup requirements.

Ready to get started?

Start Free Trial

Zioan VPS Installation Guide

Important Notice

Installation & Management Command

Choose Your Deployment Method

Why Caddy is Recommended

Prerequisites

Before You Start - Technical Requirements

Required Accounts & Services

Step 1: System Preparation

Step 2: Create Installation Directory

Step 3: Domain DNS Setup

DNS Configuration (Simple)

Step 4: Run Installation Script

Installation Command

Step 5: Firewall Configuration

Step 6: Verification and First Access

Verify containers are running:

Access Your Application

Advanced Setup - For Experienced Users

Prerequisites

Before You Start - Technical Requirements

Required Accounts & Services

Server Requirements by Team Size

Step 1: System Preparation

Step 2: Create Installation Directory

Important Directory Note:

Step 3: Domain and DNS Setup

Cloudflare Configuration

Step 4: Run Installation Script

Installation Command

Step 5: Nginx Configuration

Important Configuration Notes:

Step 6: Firewall Configuration

Step 7: Verification and Testing

Test DNS resolution:

Test HTTP/HTTPS access:

Verify containers are running:

Step 8: First Access and Setup

Critical Configuration Points

Deployment Options Summary

Caddy Setup (Recommended)

nginx + Cloudflare (Current)

Common Issues and Solutions

Need Help?

Ready to get started?

We use cookies

Cookie Preferences

Essential Cookies

Functional Cookies

Analytics Cookies