Self-hosting overview

Run the SKaaS Community edition with Docker Compose. What starts by profile, how to start the application, the image targets, the settings in .env, the search levels and the embedding options.

By The SKaaS team. Last updated . Markdown version

The Community edition is free, open source under Apache-2.0 and supports multiple organizations. You run it, and you handle upgrades and backups. Everything for it lives in deploy/selfhost/ of the repository.

What does Compose start?

A plain docker compose up -d starts the data tier at Level 0: a one-shot prepare service and MongoDB. Every other service is behind a profile.

What does Compose start?
Service Profile Role
prepare always Writes the replica-set keyfile and the passwords as files into a volume, then exits. It runs again on every start.
mongodb always MongoDB 8.3 as a single-node replica set, with authentication on. The system of record.
mongot search MongoDB Community Search, which provides full-text and vector search.
neo4j graph Neo4j Community, for the graph lens.
skaas app The server: the REST API, the two MCP servers, sign-in and the job runner. One Node process.
web app The web application: the site, the library and the dashboard. It calls the server over the Compose network.
scanner deepscan The deep scan of releases. It polls the server over HTTP and needs no database credentials.
tools tools A one-shot container with mongodump and mongorestore, for backups.

Set COMPOSE_PROFILES in .env to make a choice permanent, for example COMPOSE_PROFILES=search,graph.

How do I start the application?

Run these from deploy/selfhost/ of the repository.

./setup-env.sh
docker compose --profile search --profile app up -d --build --wait

Use --profile app alone for Level 0. The first build takes several minutes. When it ends, the web application answers on http://localhost:8081 and the server on http://localhost:8080. The server serves the REST API, /mcp for reading skills and /mcp-authoring for drafts.

setup-env.sh has generated the secrets that the server needs, among them SKAAS_AUTH_SECRET, SKAAS_ENCRYPTION_KEYS and the token of the scanner. Back up .env, in particular SKAAS_ENCRYPTION_KEYS. The encryption keys seal webhook secrets, release signing keys and model keys, and a value that was sealed with a key that you lost cannot be opened again.

People sign in by an emailed link. The default mail transport, SKAAS_MAIL_TRANSPORT=console, writes each mail to the log of the server, which suits a machine that only you use.

docker compose logs --since 5m skaas | grep -A5 "Your sign-in link"

For anything else, set SKAAS_MAIL_TRANSPORT=http with SKAAS_MAIL_URL, or turn on GitHub or Google sign-in.

At start the server waits for MongoDB, creates its collections and indexes, creates the search indexes when mongot answers, starts its job timers, and then listens. The jobs are the outbox, the upstream sources, retention, scheduled routing tests and usage rollups. Each runs under a lock in the database, so a second replica does not run a job twice. GET /health answers while the process is up. GET /ready answers 200 when the database and, at Level 1, the search indexes are usable. A server whose configuration is wrong prints the names of the variables and no values, and exits with status 78 so that a supervisor does not restart it in a loop.

Which parts have been checked?

The file docs/verification-status.md in the repository records the last run of bash deploy/selfhost/verify.sh --app and what it covered. The script starts a throwaway stack with its own secrets and ports, and removes everything it created. It checks authentication, the roles of each database user, transactions, search at both levels, Neo4j, a dump and a restore, and password rotation. With --app it also builds the server and web images, starts them against that stack, and checks that both become healthy, that the server answers /health and /ready, refuses an anonymous request with 401, serves its OAuth metadata and answers a client of the reading MCP endpoint with a challenge, that the web application answers its front page and the library, and that the server wrote no credential to its log. The restore drill of the end-to-end package, pnpm --filter @skaas/e2e run drill, dumps a database, restores it into a fresh one and checks it. The status file records its last run too.

Not checked: the scanner image has not been built or started, the commercial server image has not been built, the hosted runtime on Cloudflare has not been run, and no real third-party account has been used (GitHub App, sign-in providers, billing, mail, a model provider). The images were built and run on one machine with Docker Desktop. The file docs/verification-status.md in the repository says what each claim of the documentation rests on and which command would check it.

What are the image targets?

The Compose file pulls these official images and does not redistribute them. Tags are pinned, so a newer tag changes nothing until you edit the file.

What are the image targets?
Image Tag Used by
mongodb/mongodb-community-server 8.3.17-ubi9-slim prepare, mongodb
mongodb/mongodb-community-server 8.3.17-ubi9 tools
mongodb/mongodb-community-search 1.70.6 mongot
neo4j 2026.10.2-community neo4j

Three images are built from the repository and tagged with SKAAS_VERSION, which is local by default. Build any of them from the repository root, or let docker compose --profile app build do it.

What are the image targets?
Built image Dockerfile What it is
skaas-selfhost/server deploy/selfhost/Dockerfile, target server The open edition of the server, bundled into one file. It runs as a user that is not root, with a read-only root file system.
skaas-selfhost/web deploy/selfhost/Dockerfile, target web The web application.
skaas-selfhost/scanner deploy/selfhost/scanner/Dockerfile The deep scan worker, with its two scanners. It has its own hardening, which deploy/selfhost/scanner/README.md describes.

The commercial edition is a fourth target of the same Dockerfile, server-commercial, which adds the licensed features as a second file that the server loads. Build it only from a checkout that has ee/, set SKAAS_SERVER_TARGET=server-commercial and SKAAS_EDITION_MODULE=/app/edition.mjs, and add the PADDLE_* variables of the root .env.example if you use billing. The open image never contains licensed code.

MongoDB Community Server and Search are licensed under the SSPL and Neo4j Community under the GPLv3. SKaaS talks to them over the network and links neither. If you plan to offer the stack to others as a service, read the licences first.

Which settings go in .env?

Run ./setup-env.sh once. It copies .env.example to .env and fills every empty secret with a strong random value. Run it again and it fills only what is still empty.

Which settings go in .env?
Variable Meaning
MONGODB_ADMIN_PASSWORD, MONGODB_APP_PASSWORD, MONGODB_READONLY_PASSWORD, MONGOT_PASSWORD Generated. One for each database user.
MONGODB_KEYFILE Generated. The shared secret of the replica set. Do not change it after the first start.
NEO4J_PASSWORD, SKAAS_AUTH_SECRET Generated. Used with the graph and app profiles.
SKAAS_WEB_PROXY_SECRET Generated. Shared by the web and API to prove the visitor's address for session limits. Never sent to a browser.
SKAAS_ENCRYPTION_KEYS Generated as primary:<key>. Seals the secrets that the server must read back. Back it up.
SKAAS_SCANNER_TOKEN Generated. The scanner presents it. setup-env.sh also writes it to ./secrets/scanner-token.
COMPOSE_PROFILES Profiles that a plain up starts. Empty means Level 0.
SKAAS_BIND_ADDRESS Address that published ports bind to. Default 127.0.0.1.
SKAAS_MONGODB_PORT, SKAAS_NEO4J_HTTP_PORT, SKAAS_NEO4J_BOLT_PORT, SKAAS_HTTP_PORT, SKAAS_WEB_PORT Host ports. Defaults 27017, 7474, 7687, 8080 and 8081.
SKAAS_BASE_URL, SKAAS_API_URL The address where people reach the web application, and the address of the server. Defaults http://localhost:8081 and http://localhost:8080.
SKAAS_MAIL_TRANSPORT, SKAAS_MAIL_URL, SKAAS_MAIL_FROM How sign-in mail leaves. console (the default) writes it to the log, http posts it to your endpoint.
SKAAS_VERSION Tag of the images built from the repository. Default local.
SKAAS_EMBEDDING_PROVIDER, SKAAS_EMBEDDING_BASE_URL, SKAAS_EMBEDDING_API_KEY, SKAAS_EMBEDDING_MODEL Embeddings. See below.
SKAAS_BACKUP_DIR Where the tools profile writes dumps. Default ./backups.

The Compose file passes these optional variables to the server as well. Each is empty unless you set it in .env, and the root .env.example explains each one.

Set SKAAS_MANIFEST_EXPORT_ENABLED=true for daily, content-free release inventories. The default SKAAS_MANIFEST_EXPORT_FS_ROOT=/data/manifests lives on skaas-data, separate from MongoDB. Back up that volume separately. A different container path needs its own durable mount. These inventories supplement a full database and blob backup. The restore runbook describes how to check them against restored releases and file bytes. When upgrading an existing .env, rerun ./setup-env.sh to fill missing secrets without replacing existing values.

  • SKAAS_WEB_ORIGINS: more origins that may call the API from a browser, separated by commas.
  • SKAAS_AUTH_PATH: the path of the authentication handler, /auth by default. The web application passes the same path through, so set it once.
  • SKAAS_LOG_SALT: a secret that is mixed into the hash of an organization identifier in log lines.
  • SKAAS_SEARCH_SIMILARITY: the similarity function of the vector index, cosine, dotProduct (the default) or euclidean.
  • SKAAS_EMBEDDING_SIMILARITY_THRESHOLD: the silence threshold of the embedding space. See How search works.
  • SKAAS_OIDC_AUDIENCE, SKAAS_OIDC_ISSUER, SKAAS_OIDC_JWKS_URI: the audience, the issuer and the key set for publishing from GitHub Actions. The audience defaults to the API address, and the issuer and the key set to GitHub Actions on github.com.
  • SKAAS_MCP_URL, SKAAS_AUTHORING_MCP_URL: the addresses of the read and the authoring MCP servers. By default they are {api}/mcp and {api}/mcp-authoring.

The web application reads SKAAS_WEB_BILLING, on or off. The Compose file passes it to the web service, with a default of off. Set it to on only where billing is configured.

Keep .env private and out of version control: it holds every database password. Published ports bind to 127.0.0.1 unless you change SKAAS_BIND_ADDRESS. Connections to MongoDB are not encrypted, so set it to 0.0.0.0 only behind a firewall or a reverse proxy that you control.

The data tier creates four database users, all in the admin database. skaas_admin has the root role and is for you, for backups and maintenance, and the application never gets it. skaas_app is the application's user: it holds readWrite on the application database, which includes creating and dropping its search indexes, and the role skaasSchema, which the init script creates and which allows collMod on the application database and nothing else. The server needs that one action because it sets the validator of every collection at each start, and readWrite does not include it. dbAdmin would include it, together with dropping the database and bypassing validators, which the application must not do. skaas_ro holds read on the application database, and the server uses it for reads when SKAAS_MONGODB_READ_URI is set. mongot_sync holds searchCoordinator and is for mongot only. If you run the server against a MongoDB of your own, give its user readWrite and a role with collMod on the application database.

The Compose file passes the server only the variables that it lists, and never the administrator password. The deployment also reads settings for the GitHub App (GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_WEBHOOK_SECRET) and for the operator credentials of the public library (SKAAS_OPERATOR_CREDENTIALS). The .env.example files list each one. When the server runs behind a reverse proxy, publish the two addresses on your own host names, set SKAAS_BASE_URL and SKAAS_API_URL to them, and let the proxy overwrite X-Forwarded-For, or name another header in SKAAS_TRUSTED_CLIENT_ADDRESS_HEADERS.

Which search level will I get?

Level 0 runs with MongoDB only: exact matching and in-process keyword ranking. Level 1 adds mongot for full keyword and vector search. Pick the level by choosing whether to run mongot, with docker compose --profile search up -d. You can move from Level 0 to Level 1 at any time without restarting MongoDB. The server creates the lexical index (skills_text_v3) and the vector index (skills_vec_v2) at start when mongot answers, so there is nothing to create by hand, and a restart after a restore creates them again. After an upgrade from a version that used the older lexical index skills_text_v2, the start builds the new index, waits up to two minutes for it, and then drops the old one. Until the new index answers, search says that its lexical channel is degraded. If mongot does not answer when the server starts, the server logs a warning and runs at Level 0, and you restart it once mongot is healthy. GET /ready says when the indexes are usable. The skills_status MCP tool reports which channels are ready.

MongoDB's release notes call Community Search generally available, and the README inside the mongot image still says preview. The two disagree, so decide before you rely on Level 1 in production.

Which embedding providers can I use?

Any OpenAI-compatible endpoint, such as Ollama, LiteLLM or vLLM. Voyage with your key. Atlas automated embedding if you run on Atlas and accept its preview status. Or none: the response then reports that the semantic channel is disabled. One deployment uses one embedding space. Changing it means a new index and a backfill.

The settings are SKAAS_EMBEDDING_PROVIDER (none, hash, openai-compatible or voyage), SKAAS_EMBEDDING_BASE_URL, SKAAS_EMBEDDING_API_KEY, SKAAS_EMBEDDING_MODEL, SKAAS_EMBEDDING_DIMENSIONS and SKAAS_EMBEDDING_SIMILARITY_THRESHOLD. The hash provider hashes words and carries no meaning. It exists for tests, so do not run it in production. The last variable is the cosine similarity at which a query and a skill match by meaning alone, which decides when search stays silent. It belongs to an embedding space and to a corpus, so see How search works for the values that the retrieval evaluation measured and how to choose your own.

How do I back up, rotate and upgrade?

The deploy/selfhost/README.md file explains each step with the commands. The runbooks in docs/runbooks/ of the repository cover the cases that need care: restore into a scratch database and check it, rotate the database credentials, rotate the encryption keys, a stuck outbox and a missing search index. Two points to know first. A dump holds documents and ordinary indexes but not search indexes, so recreate them after every restore. And a backup is not proven until you read data back from a restore.

What is different from Cloud?

Cloud has many organizations, plans and hosted operations. Features in the ee/ directory, such as single sign-on, directory provisioning, custom roles, approvals and the read audit trail, need a commercial license. The auditor rules, the deep scan, routing tests, the updater, search analytics, the GitHub mirror, the dashboard and the CLI are in the Community edition. See Commercial features for the list.

Get the source

Clone the repository whose address you were given, for example by the person who runs this deployment or by the page that sent you here. This site links to the repository from its pages once its address is set in the site configuration, and until then it sends every link to the repository here.

The self-hosted server trusts no client-address header by default. Behind a proxy, set SKAAS_TRUSTED_CLIENT_ADDRESS_HEADERS=x-forwarded-for:1. The suffix is the number of trusted proxies, from 1 to 10. The server reads from the right and uses the connection address if the chain is shorter.

Administration and public listings

Community supports multiple organizations. Organization Settings includes a host denylist and an owner-only deletion danger zone. Keys can be rotated with a bounded overlap, and repositories can import a public HTTPS source once into reviewable drafts. See the docs/organization-operations.md guide in the checkout and the guides for blocked hosts, key rotation, deletion and imports.

Set SKAAS_HUMAN_CHECK_SECRET on the API and SKAAS_HUMAN_CHECK_SITE_KEY on the web for the email sign-up human check. The site's public key must match the private verifier secret. For a public catalog, configure SKAAS_OPERATOR_CREDENTIALS on the API and open /operator on the web host; the operator guide covers claims and approval. Normal organization roles do not grant operator access.

SKAAS_WEB_PROXY_SECRET proves forwarded visitor addresses when set to the same random value on the API and web. SKAAS_MANIFEST_EXPORT_ENABLED enables the daily release inventory, and SKAAS_MANIFEST_EXPORT_FS_ROOT selects an independent durable filesystem archive where needed. The inventory contains manifests and hashes, not skill text or account backups. The checkout's docs/self-hosted-settings.env.example lists these settings. Pass web-only variables into the web container explicitly; a variable present only in a Compose environment file does not reach a container automatically.