Deploy & runGuide

Self-host with Docker Compose

The self-hosted edition is the same product on your infrastructure. A public repository holds a Compose file and an .env.example; every service pulls a published image, so there is nothing to build. Fill in three values, start the stack and create the first account.

12 min read
What you will learn
  • Start a working instance in a few commands
  • Serve it on your own domains over HTTPS
  • Add workers on other machines
  • Upgrade safely and know what to back up

What runs

The stack is a handful of services. The API applies its own database migrations when it starts, and workers need no inbound port — they only reach the database.

ServiceWhat it doesRequired
uiThe web app your users openyes
apiThe HTTP API; applies its migrations on startupyes
workerRuns scripts, flows, SQL and the database workbenchyes
scraper-engineAI Scrapersonly if you use them
lspCompletions and diagnostics in the editorno
postgresThe databaseunless you bring your own
Once the stack is up, each worker checks in and appears on the Workers page with its languages and slots.

Install

  1. Clone the deployment repository

    It holds only deployment files: the Compose file, a Helm chart and the environment template.

  2. Fill in the three required values

    POSTGRES_PASSWORD, DB_CREDENTIALS_KEY and SCRAPER_ENGINE_SECRET have no defaults on purpose — a shipped default would be the same secret on every installation. .env.example gives the command that generates each one.

  3. Load the worker’s AppArmor profile, if your host enforces it

    On Ubuntu, Debian or SUSE, cat /sys/module/apparmor/parameters/enabled prints Y when AppArmor is on. Skipping the profile there stops the worker from starting, with an error naming it.

  4. Start it and create the first account

    Run docker compose up -d and open http://localhost:8080. The first account created on an empty database becomes the instance’s admin.

Shellterminal
git clone https://github.com/talissonjunior16/waiso.git
cd waiso
cp .env.example .env      # fill in the three required values

# Hosts that enforce AppArmor (Ubuntu, Debian, SUSE) — once per host:
sudo install -m 0644 apparmor/waiso-worker /etc/apparmor.d/waiso-worker
sudo apparmor_parser -r -W /etc/apparmor.d/waiso-worker

docker compose up -d

Domains and HTTPS

To serve people on other machines, Waiso needs three hostnames, one per service a browser talks to: the web app (port 8080), the API (3000) and the editor service over WebSocket (3001). Create a DNS record for each, put a reverse proxy in front that terminates TLS, and tell Waiso the addresses.

Caddyfile
waiso.example.com     { reverse_proxy 127.0.0.1:8080 }
api.waiso.example.com { reverse_proxy 127.0.0.1:3000 }
lsp.waiso.example.com { reverse_proxy 127.0.0.1:3001 }

Without the lsp hostname everything works except completions and diagnostics in the code editor.

Scale, upgrade, back up

More workers

Start more workers with the same .env on any machine that can reach the database. Each one appears on the Workers tab. A managed PostgreSQL works too: set DATABASE_URL and remove the bundled postgres service.

Upgrade

Shellterminal
# set WAISO_VERSION in .env first, or leave it unset for this release
docker compose pull && docker compose up -d --remove-orphans

Migrations run automatically when the new API starts. Back up the database first: there is no downgrade path. --remove-orphans retires services a release no longer ships.

Back up two things

  1. The database — everything you have made.
  2. DB_CREDENTIALS_KEY — without it, a restored database holds credentials nobody can decrypt, and the license has to be applied again. Keep it somewhere other than the machine it runs on.

Related topics