Skip to main content
Rootset runs from three versioned images: rootset-api (API and migration commands), rootset-worker (background jobs) and rootset-web (UI). They share the same release version. You do not need Node.js, pnpm, GitHub Packages credentials or a local source build to run published images.
Rootset 0.2.3 is available with public API, worker and UI images for Linux AMD64 and ARM64. Use the installation files attached to your chosen release.

​
Requirements

  • Docker Engine and Docker Compose 2.23.1 or later, which supports the inline configuration used for bundled PostgreSQL.
  • PostgreSQL 18: your own database or the optional bundled PostgreSQL service.
  • An existing private S3-compatible bucket for export artifacts.
  • SMTP for verification, invitations and account recovery. Set the port and TLS mode to match your provider. ROOTSET_SMTP_SECURE=true uses implicit TLS; false uses SMTP/STARTTLS, commonly on port 587.
  • Separate UI and API HTTPS origins for an internet-facing installation.
The supplied memory caps allow 4 GiB for bundled PostgreSQL, 1 GiB for the API, 2 GiB for the worker and 1 GiB for the UI. Allow additional host headroom. With external PostgreSQL, its capacity is separate.

​
1. Download the release installation files

Choose a published version from GitHub Releases. Replace 0.2.3 below with that version.
The downloaded Compose file pins the API, worker and UI images to that release version; migrations use the same API image. Keep .env for your installation settings. To select another compatible release, download its Compose file.

​
2. Configure your services

Edit .env, replacing every placeholder. Generate the application secret and encryption key separately with openssl rand -hex 32. Retain both across restarts. Set the configuration values for PostgreSQL, S3 and SMTP. For your own PostgreSQL instance, set ROOTSET_DATABASE_URL to one ordinary database owner with permission to create schemas and the pgcrypto extension. Do not use a superuser or BYPASSRLS role. API, worker and migrations share this URL. For an existing released installation, follow Releases and upgrades. Unreleased prelaunch schemas remain unsupported. For bundled PostgreSQL, use the local-db profile, set POSTGRES_PASSWORD, and set ROOTSET_DATABASE_URL=postgres://rootset:<same-password>@postgres:5432/rootset. The bundled service creates the ordinary rootset owner for you. Use a URL-safe password such as the hex output of openssl rand -hex 32.

​
3. Pull and start

The one-shot migration service must succeed before the API and worker start. The worker processes exports and other jobs, and must remain running alongside the API.

​
4. Claim the installation

For a local preview, open http://localhost:4300. Enter the configured ROOTSET_SECRET privately to claim setup and create the first Admin and single workspace. The first administrator is verified automatically. Use Create database to begin.

​
Public origins

Terminate HTTPS at your reverse proxy. Set ROOTSET_WEB_URL=https://rootset.example.com and ROOTSET_API_URL=https://rootset-api.example.com. Route those origins to ports 4300 and 4310 respectively. The UI reads the API origin at runtime. Authentication, REST, MCP and downloads use the API directly. Same-parent domains keep browser cookie access straightforward; test sign-in when deploying across unrelated sites. The Compose file binds ports to loopback by default. If your reverse proxy runs in a container, connect it to the Compose network or deliberately configure a reachable bind address. Do not expose PostgreSQL publicly. See security and troubleshooting.