Installing Isoflow (self-hosted)

# Isoflow self-hosted. Put this file, .env and nginx/default.conf.template in one
# folder, fill in .env, then run: docker compose up -d
# The full guide is at /docs/self-hosted/install-guide on any Isoflow install.

# Docker keeps roughly the last 100 MB of each container's output.
x-logging: &logging
  driver: json-file
  options:
    max-size: 20m
    max-file: "5"

services:
  nginx:
    image: nginx:1.29.8
    logging: *logging
    restart: unless-stopped
    ports:
      - "${HTTP_PORT:-80}:80"
      # To serve HTTPS directly, see "Enabling TLS" in the install guide:
      # - "443:443"
    volumes:
      - ./nginx/default.conf.template:/etc/nginx/templates/default.conf.template:ro
      # - ./certs:/etc/nginx/certs:ro
      # - ./certbot:/var/www/certbot:ro
    depends_on:
      - app

  app:
    # Replace this line with the image line from the download page. To
    # upgrade, change the version and run `docker compose up -d`.
    image: <registry>/isoflow/app:<version>
    logging: *logging
    restart: unless-stopped
    init: true
    env_file: .env
    # With your own Postgres instead of the bundled one, delete this
    # depends_on and the db service below.
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:18.4-alpine
    logging: *logging
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
    volumes:
      - db:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER}\" -d \"$${POSTGRES_DB}\""]
      interval: 5s
      timeout: 5s
      retries: 12

volumes:
  db:

# Isoflow self-hosted configuration. Save this as .env beside
# docker-compose.yml and fill in the required block. Every setting is read at
# start-up: after a change, run `docker compose up -d` again. The boot report
# at the top of `docker compose logs app` shows what is enabled and why.

# ---------------------------------------------------------------------------
# Required
# ---------------------------------------------------------------------------

# Your licence key. Without a valid one Isoflow does not start, and the log
# says whether it is missing, damaged or not issued for this version.
LICENSE_KEY=

# The address your users open, with no path. Sign-in cookies and the links in
# emails are built from it, so it must match the address in the browser
# exactly, or sign-in fails. The boot check refuses a value with a path.
APP_ORIGIN=https://diagrams.example.com

# Signs user sessions; at least 32 characters, or Isoflow does not start.
# Generate one with:
#   openssl rand -base64 32
# Changing it signs everyone out.
AUTH_SECRET=

# The database password. For the bundled database, generate one with:
#   openssl rand -hex 24
# The bundled database takes it on its first start only; to change it later,
# change it in Postgres too.
DB_PASSWORD=

# Your contact address, e.g. [email protected]. Every email Isoflow sends
# comes from it, and users are pointed to it for help. Your mail relay must
# accept it as a sender, or every email fails with "Failed to send email." in
# the log. The boot check refuses a malformed address.
CONTACT_EMAIL=

# Your contact name, e.g. Acme Diagrams: the sender name on every email. The
# boot check refuses <, >, " and line breaks.
CONTACT_NAME=

# Your superusers' email addresses, comma-separated: usually just yours, e.g.
# [email protected], or [email protected],[email protected]. Superusers can open
# the admin dashboard, and are exactly the accounts listed here: change the
# list and restart, and the role follows. On each start Isoflow invites every
# address that is not yet in your workspace, so sign up with it to join. The
# boot check refuses a malformed address.
SUPERUSER_EMAILS=

# ---------------------------------------------------------------------------
# Database
# ---------------------------------------------------------------------------

# These point at the bundled Postgres container. For your own Postgres, set
# them to your server and remove the db service from docker-compose.yml. If
# Isoflow cannot reach the database within 60 seconds, or cannot sign in to it,
# it does not start.

# The Postgres server.
DB_HOST=db

# The Postgres port. Default: 5432.
DB_PORT=5432

# The Postgres user.
DB_USER=isoflow

# The Postgres database.
DB_NAME=isoflow

# ---------------------------------------------------------------------------
# Network
# ---------------------------------------------------------------------------

# The host port nginx publishes, read by docker-compose.yml. If another service
# holds it, the nginx container does not start. Default: 80.
# HTTP_PORT=80

# ---------------------------------------------------------------------------
# Mail
# ---------------------------------------------------------------------------

# Invitations, password resets and email verification are sent by mail, from
# CONTACT_NAME and CONTACT_EMAIL in the required block. With email and password
# sign-in on (the default), Isoflow does not start without mail. With Google
# sign-in only it starts and warns, but members cannot be invited.

# smtp for your mail relay or provider, mailgun for Mailgun's API, or none.
# Fill in the settings for the one you choose. Default: none.
MAIL_PROVIDER=smtp

# Your mail relay. If it cannot be reached, emails fail with "Failed to send
# email." in the log. Required with MAIL_PROVIDER=smtp.
SMTP_HOST=

# Port 465 uses TLS from the start; any other port switches to TLS (STARTTLS)
# when the relay offers it. If the relay's certificate comes from your own
# certificate authority, mount the CA file into the app container and set
# NODE_EXTRA_CA_CERTS to its path. Default: 587.
# SMTP_PORT=587

# Set it and SMTP_PASSWORD together, or leave both unset for a relay that
# accepts this host without a login, often on port 25. One without the other
# stops the start; wrong credentials make every email fail.
# SMTP_USER=
# SMTP_PASSWORD=

# Your Mailgun sending domain. Required with MAIL_PROVIDER=mailgun.
# MAILGUN_DOMAIN=

# Your Mailgun API key. A wrong one makes every email fail.
# Required with MAIL_PROVIDER=mailgun.
# MAILGUN_API_KEY=

# https://api.mailgun.net, or https://api.eu.mailgun.net for the EU region. The
# wrong region makes every email fail. Required with MAIL_PROVIDER=mailgun.
# MAILGUN_API_BASE=

# ---------------------------------------------------------------------------
# Sign in with Google (optional)
# ---------------------------------------------------------------------------

# Set it and GOOGLE_OAUTH_CLIENT_SECRET to offer "Sign in with Google"; with
# only one, Google stays off and the boot report warns. The redirect URI to
# register with Google is printed in the boot report:
# <APP_ORIGIN>/api/auth/callback/google
# GOOGLE_OAUTH_CLIENT_ID=
# GOOGLE_OAUTH_CLIENT_SECRET=

# false makes Google the only way to sign in: the email and password form,
# sign-up and password reset are removed. The boot check refuses false unless
# both Google settings are set. Users who already signed up with an email and
# password cannot then sign in at all, so set it before anyone signs up.
# Default: true.
# ENABLE_EMAIL_PASSWORD_AUTH=true

# ---------------------------------------------------------------------------
# Logging (optional)
# ---------------------------------------------------------------------------

# container writes logs to the container output, with fields holding passwords,
# tokens, keys or email addresses redacted. sentry sends server and browser
# errors to your own Sentry project. Default: container.
# LOGGING_PROVIDER=container

# Your Sentry project's DSN. It is sent to your users' browsers. Set
# without LOGGING_PROVIDER=sentry, it is ignored with a warning.
# Required with LOGGING_PROVIDER=sentry.
# SENTRY_DSN=

# ---------------------------------------------------------------------------
# Analytics (optional)
# ---------------------------------------------------------------------------

# A Google Analytics 4 measurement ID (G-…) to track page views in your users'
# browsers, which then load Google's tag. Left out, there are no analytics.
# Isoflow shows no cookie-consent banner, so your users' consent is up to you.
# The boot check refuses anything but a G- ID.
# GOOGLE_ANALYTICS_ID=

# ---------------------------------------------------------------------------
# Diagram workers (optional tuning)
# ---------------------------------------------------------------------------

# Diagram operations run in a pool of worker threads inside the app container.

# pool, or none to run them on the main thread; the settings below are then
# ignored with a warning. Default: pool.
# WORKERS_PROVIDER=pool

# Threads in the pool, at least 1. More than the host's CPU cores warns, and
# adds memory, not speed. Default: 2.
# WORKERS_POOL_SIZE=2

# How long one operation may wait for a free thread before the user is told the
# server is busy, in milliseconds; at least 1000. Default: 15000.
# WORKERS_QUEUE_TIMEOUT_MS=15000

# How long one operation may run before it is stopped, in milliseconds; at
# least 1000. Very large diagrams need longer. Default: 15000.
# WORKERS_RUN_TIMEOUT_MS=15000

# Operations that may wait per thread before new ones are refused; at least 1.
# Default: 50.
# WORKERS_QUEUE_PER_WORKER=50

# Memory limit per thread, in megabytes; at least 256. Default: 512.
# WORKERS_MAX_HEAP_MB=512

# Isoflow's single origin: /api, /assets and the MCP discovery paths go to the
# api, everything else to the web app. Plain HTTP on port 80 by default, for a
# proxy or load balancer in front that terminates TLS. To serve HTTPS from here
# instead, see "Enabling TLS" in the install guide.

map $http_upgrade $connection_upgrade {
    websocket upgrade;
    default   "";
}

# Behind a proxy, pass on the scheme it reports; otherwise the one nginx saw.
map $http_x_forwarded_proto $forwarded_proto {
    default $http_x_forwarded_proto;
    ""      $scheme;
}

server {
    listen 80 default_server;
    # For HTTPS, replace the listen line above with these three, and uncomment
    # the redirect server at the end of this file:
    # listen 443 ssl default_server;
    # ssl_certificate     /etc/nginx/certs/fullchain.pem;
    # ssl_certificate_key /etc/nginx/certs/privkey.pem;
    server_name _;

    large_client_header_buffers 4 32k;
    client_header_buffer_size 32k;
    # Each edit sends the whole diagram, and Isoflow accepts up to 2 MB; a
    # lower value here stops large diagrams from being edited or saved.
    client_max_body_size 2m;

    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 $forwarded_proto;

    # Let's Encrypt HTTP-01 challenges, answered from a mounted folder.
    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    # OAuth discovery for the MCP server, answered by the api when MCP is on.
    location /.well-known/ {
        proxy_pass http://app:4000;
    }

    location /assets {
        proxy_pass http://app:4000;
    }

    location /api {
        proxy_pass http://app:4000/api;
    }

    location / {
        proxy_pass http://app:3000;

        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection $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 $forwarded_proto;
    }
}

# With HTTPS enabled above, plain HTTP only answers Let's Encrypt and redirects.
# server {
#     listen 80 default_server;
#     server_name _;
#
#     location /.well-known/acme-challenge/ {
#         root /var/www/certbot;
#     }
#
#     location / {
#         return 301 https://$host$request_uri;
#     }
# }

docker compose up -d

Isoflow Diagramming Platform · v4.1.0
  edition       self-hosted
  licence       Acme Ltd · valid until 2027-10-03 · id 3f9c2a7e-…
  origin        https://diagrams.example.com
  database      db:5432/isoflow
  storage       local
  mail          smtp · mail.example.com:587 (STARTTLS if offered, auth: isoflow)
  billing       none
  sign-in       email/password · google
                google redirect URI → https://diagrams.example.com/api/auth/callback/google
  superusers    [email protected]
  workers       pool · 2 threads, 15s to wait, 15s to run
  logging       container (stdout/stderr)
  icon gen      disabled

  workspace     Acme Ltd · created 2026-10-11 · invite-only
  superusers    [email protected] · invited; sign up as this address to join

Isoflow cannot start. Fix the following and restart:
  LICENSE_KEY  is malformed; check it was copied whole, with no line breaks
  AUTH_SECRET  must be at least 32 characters; generate one with: openssl rand -base64 32

mkdir -p certbot letsencrypt certs
docker run --rm \
  -v "$PWD/certbot:/var/www/certbot" \
  -v "$PWD/letsencrypt:/etc/letsencrypt" \
  certbot/certbot certonly --webroot -w /var/www/certbot \
  -d diagrams.example.com --email [email protected] --agree-tos --no-eff-email
cp -L letsencrypt/live/diagrams.example.com/fullchain.pem certs/
cp -L letsencrypt/live/diagrams.example.com/privkey.pem certs/

docker run --rm \
  -v "$PWD/certbot:/var/www/certbot" \
  -v "$PWD/letsencrypt:/etc/letsencrypt" \
  certbot/certbot renew --webroot -w /var/www/certbot
cp -L letsencrypt/live/diagrams.example.com/fullchain.pem certs/
cp -L letsencrypt/live/diagrams.example.com/privkey.pem certs/
docker compose exec nginx nginx -s reload

docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom' > isoflow-$(date +%F).dump

docker compose stop app
docker compose exec -T db sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists --no-owner' < isoflow-2026-10-10.dump
docker compose start app

# On a machine that can reach the registry, after docker login:
docker pull <registry>/isoflow/app:<version>
docker save -o isoflow-images.tar <registry>/isoflow/app:<version> postgres:18.4-alpine nginx:1.29.8

# Copy isoflow-images.tar to the Isoflow host, then:
docker load -i isoflow-images.tar

docker compose down       # stops and removes the containers; keeps your database
docker compose down -v    # also deletes the database volume, permanently

docker compose ps                  # is each container running?
docker compose logs app            # application logs, including the boot report
docker compose logs nginx          # requests and proxy errors
curl http://localhost/api/health   # answers {"status":"ok", ...} when healthy