Admin guide

• Provider choose Stripe or Paddle in Setup.
• Credentials save publishable, secret, and webhook values in encrypted storage.
• Plan pricing enter monthly, yearly, or one-time provider price IDs on the plan resource.
• Role assignment map each plan to the correct post-subscription role.
• Free tier handling mark the fallback plan if unsubscribed users should keep some access.
• Delivery policy use the plan resource to map provisioning servers, external databases, and external storage pools to each offer.

Provisioning is driver-based and job-driven. Initial deploy, suspend, resume, restart, redeploy, and domain sync are all tracked lifecycle jobs.

• Driver selection persists as provisioning_driver on the tenant.
• Server placement persists as provisioning_server_id so later health, backup, and lifecycle actions use the same host.
• Dependency placement persists selected external database and storage backends so restarts and redeploys keep using the same infrastructure choices.
• Provisioning jobs are the audit trail for all tracked runtime actions.

• Docker and Compose must already be installed on the provisioning host and available to the configured deploy user.
• Caddy must already be installed if you enable reverse-proxy management for that server. SaaSForge writes per-tenant site files and reloads Caddy, but it does not install or bootstrap Caddy for you.
• A writable runtime root must exist for compose files, env files, logs, backups, and tenant data.
• A shared Docker network must be available or creatable by the deploy user for tenant containers.
• DNS must point tenant domains at the provisioning host or fronting load balancer before HTTPS traffic can succeed.
• Firewall and ports must allow public HTTP/HTTPS traffic to the reverse proxy and local container traffic on the allocated host ports.

1. Prepare the host with Docker, Docker Compose, Caddy, and a deploy user that can write the runtime directories and reload Caddy.
2. Point DNS for any tenant or base-domain records at that host or its fronting proxy/load balancer.
3. Create a provisioning server in admin with the SSH connection, root path, Docker command names, network, and optional Caddy paths.
4. Assign the server to plans so new tenants can be placed onto that host automatically.
5. Run a real provisioning test and confirm the tenant compose files, Caddy site file, Caddy reload, HTTPS response, and n8n launch URL all succeed.

• Creates tenant runtime files such as the compose file, env file, log path, backup path, and tenant data path under the configured runtime root.
• Creates or updates a tenant-specific Caddy site file that contains the tenant's exact domain list and reverse proxies traffic to that tenant's allocated host port.
• Starts, stops, restarts, or redeploys the tenant container with the configured Docker and Compose commands.
• Reloads Caddy after writing or removing a tenant site file when reverse proxy management is enabled.
• Updates n8n runtime URLs so the primary tenant domain becomes the editor base URL and webhook base URL.

• It does not install Docker or Docker Compose on the provisioning host.
• It does not install or bootstrap Caddy on the provisioning host.
• It does not create DNS records with Cloudflare, Route53, or any other DNS provider.
• It does not create a wildcard or catch-all Caddy listener that asks the central app whether a domain is allowed.
• It does not manage operating-system firewall rules or cloud load balancer listeners for you.

Treat provisioning hosts as pre-built runtime targets. SaaSForge expects the server to be ready for deployments before you save it in admin.

#!/usr/bin/env bash
set -euo pipefail

DEPLOY_USER="${1:-deploy}"
HOSTNAME="$(hostname -f)"

_has_cmd() { command -v "$1" || return 1; }
_deb_installed() { dpkg -s "$1" || return 1; }
_install_if_missing() {
    local missing=()
    for pkg in "$@"; do
        _deb_installed "$pkg" || missing+=("$pkg")
    done
    [[ ${#missing[@]} -eq 0 ]] || sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq "${missing[@]}"
}

echo "=== 1. System updates ==="
sudo apt-get update -qq
sudo apt-get upgrade -y -qq
_install_if_missing curl ufw unattended-upgrades

if ! swapon --show | grep -q .; then
    sudo fallocate -l 1G /swapfile
    sudo chmod 600 /swapfile
    sudo mkswap /swapfile
    sudo swapon /swapfile
    echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
fi

echo "=== 2. Docker ==="
if ! _has_cmd docker; then
    for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do
        sudo apt-get remove -y "$pkg" || true
    done
    curl -fsSL https://get.docker.com | sudo bash
fi
_install_if_missing docker-compose-plugin

echo "=== 3. Docker daemon config ==="
sudo mkdir -p /etc/docker
printf '%s\n' '{"log-driver":"json-file","log-opts":{"max-size":"10m","max-file":"3"},"live-restore":true,"storage-driver":"overlay2"}' \
    | sudo tee /etc/docker/daemon.json
if _has_cmd dockerd; then
    sudo systemctl restart docker
fi

echo "=== 4. Caddy ==="
if ! _has_cmd caddy; then
    _install_if_missing debian-keyring debian-archive-keyring apt-transport-https
    sudo mkdir -p /usr/share/keyrings
    if [[ ! -f /usr/share/keyrings/caddy-stable-archive-keyring.gpg ]]; then
        curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
            | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
    fi
    if [[ ! -f /etc/apt/sources.list.d/caddy-stable.list ]]; then
        curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
            | sudo tee /etc/apt/sources.list.d/caddy-stable.list
    fi
    sudo apt-get update -qq
    _install_if_missing caddy
fi

echo "=== 5. Deploy user & runtime dirs ==="
sudo id -u "$DEPLOY_USER" || sudo useradd -m -s /bin/bash "$DEPLOY_USER"
sudo usermod -aG docker "$DEPLOY_USER"
sudo mkdir -p /var/lib/saasforge/runtime
sudo chown -R "$DEPLOY_USER":"$DEPLOY_USER" /var/lib/saasforge/runtime
sudo mkdir -p /etc/caddy/sites-enabled/saasforge

echo "=== 6. Kernel tuning ==="
printf 'fs.file-max = 100000\nvm.max_map_count = 262144\nnet.core.somaxconn = 1024\n' \
    | sudo tee /etc/sysctl.d/99-saasforge.conf
sudo sysctl --system

echo "=== 7. Firewall ==="
if sudo ufw status | grep -q 'Status: active'; then
    for port in ssh 80/tcp 443/tcp; do
        sudo ufw status | grep -q "$port" || sudo ufw allow "$port"
    done
else
    _install_if_missing ufw
    sudo ufw --force reset
    sudo ufw default deny incoming
    sudo ufw default allow outgoing
    sudo ufw allow ssh
    sudo ufw allow 80/tcp
    sudo ufw allow 443/tcp
    sudo ufw --force enable
fi

echo "=== 8. Enable services ==="
sudo systemctl enable --now docker

# Write a minimal Caddyfile so caddy can start
if ! caddy validate --config /etc/caddy/Caddyfile; then
    printf ':80 {\n    respond "SaaSForge provisioning host"\n}\n\nimport /etc/caddy/sites-enabled/saasforge/*\n' \
        | sudo tee /etc/caddy/Caddyfile
fi
cd /etc/caddy && caddy start
echo "Caddy started in /etc/caddy/"

# unattended-upgrades is a timer, not a service
sudo systemctl enable unattended-upgrades || true
sudo systemctl start unattended-upgrades || true

echo "=== 9. Verification ==="
echo -n "Docker: "; sudo -u "$DEPLOY_USER" docker version --format '{{.Server.Version}}'
echo -n "Compose: "; sudo -u "$DEPLOY_USER" docker compose version --short
echo -n "Caddy: "; caddy version
echo -n "UFW: "; sudo ufw status | head -1

echo ""
echo "Host $HOSTNAME ready. Add it as a Provisioning Server in admin.
  Host     : $HOSTNAME
  Port     : 22
  Username : $DEPLOY_USER"

# Example /etc/caddy/Caddyfile excerpt
{
    email admin@example.com

    on_demand_tls {
        ask https://app.example.com/saasforge/caddy/on-demand-tls
    }
}

import /etc/caddy/sites-enabled/saasforge/*

When SAASFORGE_CADDY_ON_DEMAND_TLS_ASK_URL is configured, SaaSForge-generated site files switch to tls { on_demand } and expect the main Caddy config to expose the matching ask URL above.

• Fallback behavior remains local SQLite plus local filesystem storage when no external resource is assigned.
• Tenant overrides can explicitly pin a tenant to a specific database or storage backend.
• Plan mappings let you keep infrastructure placement policy on the product offer instead of per-tenant manual edits.

• Tenant edit page is for ownership, plan changes, infrastructure overrides, and primary record maintenance.
• Tenant instance page is for day-two operations such as health review, uptime visibility, backup creation, restart, and redeploy.
• Provisioning feedback allows readiness callbacks to close a running lifecycle job after the runtime reports back.
• Runtime metadata stores base URL, launch URL, host port, latest failure details, and dependency selections.

This is one of the most important parts of setup. If the scheduler is not running, new tenants stay queued, template installs wait, health checks stop, backups stop, and scheduled account actions do not run.

* * * * * cd /path/to/n8forge && /usr/bin/php artisan schedule:run >> /dev/null 2>&1

Backups and restore

Automated backups capture the full n8n data directory, including the SQLite database, credentials, and workflow files.

• Scope: The entire /home/node/.n8n directory is tar'd, so the SQLite database is always included.
• Schedule: saasforge:run-backups runs daily. Retention is configurable via SAASFORGE_BACKUPS_MAX_PER_TENANT (default 7).
• Manual backup: From the instance edit page at Automation → Managed Instances → Edit → Backup.
• Restore: From the instance view page (Automation → Managed Instances → {instance} → View), scroll to the Backups section and click Restore on a succeeded backup. The container stops, the data directory is replaced, and the container restarts.
• Restore status is shown as a badge on the backup card. All restore operations are logged to the activity log.
• SSH driver: Backup files are downloaded locally, then uploaded back to the remote server during restore. Both Docker and SSH drivers are supported.

Activity log

A unified activity log at SaaS → Activity Log shows all platform operations in reverse chronological order.

Filter by action type or time period (today, yesterday, last 7/30 days). Error details are shown inline. Logs older than the configured retention period are cleaned automatically.