komodo-server¶

komodo-server is Komodo Core with its database. Core is the part of Komodo that holds the web interface and decides what runs where, and Periphery is the agent on each host that carries it out. Core deploys every stack in the fleet, this one included, and every host's Periphery connects to it.

It runs on one host, km01. See Komodo (km01) for the build.

What it runs¶

ferretdb
postgres
postgres-backup
komodo

Service	Does
`ferretdb`	Stands between Core and Postgres. Core expects a MongoDB database, so FerretDB speaks MongoDB's protocol to it and stores what it is given in Postgres
`postgres`	Postgres with the DocumentDB extension. Holds every Komodo resource, Variable, and Secret
`postgres-backup`	Dumps the database each day, and keeps 7 daily, 4 weekly, and 6 monthly dumps
`komodo`	Komodo Core: the web interface and the API, on port 9120

The project is komodo, so the containers are named komodo- and the service, such as komodo-postgres. Core's container is komodo-komodo.

FerretDB, Postgres, and the backup container sit on a network marked internal. Core joins that network and proxy, and publishes port 9120 on the host.

Values it reads¶

Key	Reads	Kind	Described under
`POSTGRES_USER`, `KOMODO_DB_USERNAME`	`KOMODO_DB_USERNAME`	Secret	Komodo's database
`POSTGRES_PASSWORD`, `KOMODO_DB_PASSWORD`	`KOMODO_DB_PASSWORD`	Secret	Komodo's database

It also reads the 19 operational defaults, as every stack does.

Each Secret feeds two keys. Postgres is created with the pair, and FerretDB and Core log in with it. Postgres takes the pair on the first start of an empty data folder, so the Secrets have to hold what that first start used. See Stage the values.

What the host needs¶

The project is komodo, so the stack's folders sit under /opt/docker/volumes/komodo and /opt/docker/logs/komodo. Both are mode 0750, owned by the admin account with group 101000.

Folder	Owner	Mode
`/opt/docker/volumes/komodo/ferretdb-data`	`101000:101000`	Default
`/opt/docker/volumes/komodo/postgres-data`	`100000:100000`	Default
`/opt/docker/volumes/komodo/postgres-backup-data`	`100000:100000`	Default
`/opt/docker/volumes/komodo/komodo-keys`	`101000:101000`	Default
`/opt/docker/volumes/komodo/komodo-backups`	`101000:101000`	Default
`/opt/docker/volumes/komodo/komodo-sync`	`101000:101000`	Default
`/opt/docker/volumes/komodo/komodo-cache`	`101000:101000`	Default
`/opt/docker/volumes/komodo/komodo-secrets`	`101000:101000`	`0700`

These seed files come from fleet-stacks. Each is written only when nothing is at its path, so a copy already on the host is never replaced.

File	Copied from	Owner	Mode
`/opt/docker/volumes/komodo/komodo-secrets/core.config.toml`	`containers/komodo/config/core.config.toml.example`	`101000:101000`	`0600`

Port	Allowed from	Comment
`9120/tcp`	Anywhere	Komodo Core

The host's NixOS configuration creates the folders and the seed files, and opens the ports, when the host is deployed. It reads them from the host's file in the private repo, nixos/hosts/<host>.json, which nixos-sync.yml writes from the stack's setup.yaml. See Host layout.

The stack also needs a Traefik on the same host for the routes below. Port 9120 works without one.

Port 9120 is open to any address because every Periphery in the fleet dials it, and so does each run.

core.config.toml is Core's config file, mounted read-only. The copy the run makes is upstream's default, unchanged.

Hostnames¶

Traefik routes four names to Core. With the host km01, the sub-domain home., and the domain myah-mitchell.com, they are:

Hostname	Comes from
`komodo.myah-mitchell.com`	`KOMODO_HOSTNAME` on the domain
`komodo.home.myah-mitchell.com`	`KOMODO_HOSTNAME` on the sub-domain
`komodo.km01.home.myah-mitchell.com`	`KOMODO_HOSTNAME` on the host

The fourth is the project name on the host, which here is the same as the third.

The route uses the chain-no-auth chain in both modes. Core has its own sign-in, and the API has to answer clients that cannot follow a redirect to Authentik.

The direct address, http://172.16.7.101:9120, does not go through Traefik. It is the one in komodo_core_address.

Verify¶

In Komodo, the komodo-server Stack shows as running with four services.

On the host, list the Stack's containers. Komodo names the Compose project after the Stack, not after PROJECT_NAME:

docker compose -p komodo-server ps

komodo-ferretdb, komodo-postgres, and komodo-postgres-backup show healthy in the STATUS column. komodo-komodo has no health check, so it shows Up and nothing more. A Core that answers on port 9120 is the check for it.

Data worth keeping¶

Folder under `/opt/docker/volumes/komodo`	Holds
`komodo-keys`	Core's keypair, which every Periphery trusts
`postgres-data`	The live database
`postgres-backup-data`	The dumps
`komodo-secrets`	`core.config.toml`

All four are on the persistent disk, so they survive a rebuild of the VM. See What to keep safe for what losing each one costs.

komodo-cache holds clones of repos, which Core makes again when they are missing.