ZenSailor Documentation

Introduction

ZenSailor allows you to turn any Linux server into a powerful deployment platform similar to Vercel or Heroku. It abstracts away the complexity of Docker, Nginx (Traefik), and SSL management into a clean, single-pane-of-glass dashboard.

Prerequisites

Before installing, ensure your server meets the following requirements:

• OS: Ubuntu 20.04/22.04 LTS (Recommended), Debian 11/12, or CentOS Stream 9.
• Resources: Minimum 2GB RAM (4GB recommended for buildpacks), 2 CPU Cores.
• Software: Docker Engine (v24+) & Docker Compose Plugin (v2+).
• Network: Public IP address with ports 80, 443, and 4222 open.

Installation

We provide a single-line installer script that sets up the Control Plane, Database, NATS, and Traefik router.

SSH into your server and run:

# Download and execute the installer$curl -sfL https://get.zensailor.com | bash

Configuration Prompts

The installer will ask for two critical pieces of information:

• Domain Name: The FQDN where you will access the dashboard (e.g., paas.example.com). Make sure your DNS A record points to your server IP before running this.
• ACME Email: Used by Let's Encrypt for SSL certificate notifications.

Initial Setup

Once the installer completes, wait about 30 seconds for the containers to initialize.

1. Create Admin Account

Navigate to your configured domain (e.g., https://paas.example.com). You will be greeted by the initialization screen.

2. Configure GitHub (Optional but Recommended)

To enable automatic deployments from private repositories:

1. Go to Settings > GitHub App.
2. Click Configure GitHub App.
3. You will be redirected to GitHub to create a new App manifest.
4. Install the App on the organizations/repositories you wish to deploy.

Architecture

ZenSailor uses a modern, microservices-based architecture running entirely on Docker.

• Control Plane: The Next.js dashboard and API server. It manages state and orchestration.
• Agent: Runs on every node (including the main one). It listens for commands via NATS and executes Docker operations.
• NATS: A lightweight messaging system used for communication between the Control Plane and Agents.
• Traefik: The edge router. It automatically discovers running services and routes traffic to them, handling SSL termination.
• PostgreSQL: Stores platform data (users, projects, deployment history).

Structure

Resources in ZenSailor are organized hierarchically to support teams and complex applications.

Organization

The top-level entity. Users belong to organizations. Billing and GitHub connections are managed here.

Project

A logical grouping of an application (e.g., "Marketing Website" or "SaaS Platform").

Environment

Inside a project, you have Environments (e.g., Production, Staging). Each environment is isolated; services in Staging cannot talk to Production services via internal DNS.

Services & Sources

A Service is the actual application container. ZenSailor supports multiple ways to deploy:

Domains & Routing

Exposing your service to the internet is handled via the Domains tab inside a Service.

• Automatic SSL: When you add a domain, ZenSailor configures Traefik to request a certificate from Let's Encrypt.
• Internal DNS: Services can talk to each other using their names. e.g., A backend service can reach a database service at postgres://db-service:5432.

CLI Tool

For power users, ZenSailor offers a robust CLI for scripting and management.

# Install CLI globally$npm install -g zensailor-cli# Login to your instance$zensailor login# Deploy the current directory$zensailor deploy .

Updating

ZenSailor updates are delivered via Docker images. You can trigger an update directly from the dashboard sidebar when a new version is detected.

Alternatively, run the installer script again to force an update:

$curl -sfL https://get.zensailor.com | sh

Repair Tool

If your instance configuration becomes corrupted (e.g., Traefik routing breaks, database connection issues), use the built-in repair tool.

$cd /opt/zensailor$sudo ./fix.sh

This script will: regenerate router configs, fix file permissions, check Docker networking, and restart core services.

Model Context Protocol (MCP)

An MCP server is a lightweight program that implements the Model Context Protocol (MCP), enabling AI agents to securely interact with external systems like APIs, databases, or infrastructure tools.

ZenSailor exposes a secure MCP endpoint that allows you to control your PaaS using natural language from tools like Cursor, Windsurf, or Claude Desktop.

Features

• List Services: Ask your AI "What services are running?" or "Show me failed deployments".
• Restart Services: Command "Restart the Traefik router" or "Redeploy the payment service".
• Documentation: Your AI can read the full ZenSailor docs to answer your questions accurately.

Configuration

Connect your favorite AI code editor or agent using the configuration below. The server creates a secure SSE (Server-Sent Events) tunnel to your ZenSailor instance.

{
  "mcpServers": {
    "zensailor": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-http-client",
        "https://your-domain.com/api/mcp?token=YOUR_API_TOKEN"
      ]
    }
  }
}

Uninstalling

$cd /opt/zensailor$sudo ./uninstall.sh