How it works · underneath

How environments and templates work

An environment is a thing that runs on your box: a directory, and the containers Docker runs from it. An environment template (a template, for short) is a frozen copy of an environment, kept by your account. This page is what happens underneath, for when you want to know.

An environment is a directory

Each environment is a directory on the box's data disk, seen in the workbench as ~/environments/<name>:

bettik.json: Which service is the app and its port, the secrets to mint, and what it requires of its owner.
compose.yaml: A Docker Compose project: the app container, plus any services beside it, such as Postgres.
seed: Runs once, at install.
update: Brings a copy current: pull, migrate, reinstall.
start: Runs the processes, in the foreground. When it exits, it is started again.
stop: Optional: a graceful stop.
.env: Written by Bettik on every start: _BETTIK_ENVIRONMENT (the name), the address, the ports, DATABASE_URL, and the secrets it minted.
projects/: The code, one repository per directory.

The database's files live in the directory too. Nothing about an environment is anywhere else, which is what makes the rest of this page possible. The environment directory has every file in full.

How it runs

Each environment is its own Compose project on its own Docker network. Its containers reach each other by name — <environment>-db — and the environment's directory is mounted at /bundle inside them, so an edit in the workbench is seen at once. The workbench is on every environment's network; environments cannot see each other. Memory comes from the box's shared pool: a stopped environment uses none.

Its address, <environment>.<box>.<handle>.bettik.dev, reaches the box through its tunnel. The box's gate checks who you are — private by default, until share_environment makes it public — and forwards the request to the app's port. Names and addresses has the rest.

Clone

A clone is a copy-on-write (reflink) copy of the whole directory: data and node_modules included, in seconds, whatever the size. The environment is paused for the instant of the copy, so the database is consistent, and carries on. The two share the disk they have in common until they diverge.

Save

Saving makes an environment the next saved environment of its template. The environment is stopped, so its data is still, its directory is copied copy-on-write, and it starts again. From that copy, Bettik streams one compressed archive into private storage. The passwords Bettik minted for the environment are kept beside the archive, not inside it.

A template is that archive, plus a record saying its name, version, kind, size, what it was made from, and who can see it. Versions are numbered, and never change once made.

Install

The template is fetched onto the box, where it stays cached out of sight, and copied into a new environment directory. The environment gets a fresh name and its own ports. Then seed runs, with the old secrets available as OLD_* so the data it carries stays readable, then update, and it starts.