Skip to content

Latest commit

 

History

History
529 lines (372 loc) · 21.9 KB

SETUP_GUIDE.md

File metadata and controls

529 lines (372 loc) · 21.9 KB

CodingBooth — Setting Up a Booth

This guide is for the person who owns a project's .booth/: you choose what goes into the booth — tools, ports, credentials, hooks — and keep it working as the project changes.

Everyone else on the project only needs Developing in a Booth.

It follows the job in order. Each section says what the task is, gives the quick way to do it, and links to the detailed document.

AI agents helping a user set up a booth should read AGENT_SETUP.md.


Table of Contents

  1. The one rule: generated vs yours
  2. Start
  3. Choose the tools
  4. Wire up the runtime
  5. Beyond the catalog
  6. Risky options
  7. Profiles
  8. Change it later
  9. Prove it works
  10. Commit and hand off
  11. Share an image, and migrate

0. The one rule: generated vs yours

booth config writes the booth's configuration from a selection of templates and flags. Some files under .booth/ are its output; the rest are yours. Keep the two apart:

Files Who writes them How to change them
Boothfile, config.toml, .generated booth config Re-run booth config with different flags
setups/, startups/ (without a # Generated by: header), home/, home-seed/, shared/, console.json, templates/ You Edit them by hand — a reconfigure copies them, never regenerates them. The exception: a script your own template writes into setups/ is rewritten from the template each time, so edit it there
./booth, .booth/tools/codingbooth.lock booth install booth install <version>

.generated holds a fingerprint of what booth config last wrote. That is how it can tell its own output from your edits later. An edit it can turn back into flags (a new --env, a changed port, a bumped version pin) is read back and kept. Anything else, such as a hand-added run line, makes the file protected: booth config will not overwrite it without --overwrite (which keeps your copy as .bak) or --beside (which writes its version as .new for you to merge).

So: reach for a flag, not an editor.

More: booth config → What gets generated · Hand-written files


1. Start

Install CodingBooth in the project

curl -fsSL https://codingbooth.io/install.sh | bash     # first time on this machine
cd my-project
booth install                                           # puts ./booth and the lock file here

Docker must work without sudo (rootful Docker Engine on Linux, Docker Desktop on macOS and Windows).

More: booth install

Pick a starting point

Start from Command When
Nothing, choosing as you go booth config (terminal UI), booth config --web (browser) Most projects
Nothing, in one command booth config --no-tui --select 'go+linter/python:3.13+uv' You know what you want, or are scripting
A shipped example booth example list, then booth example try <name> <folder> A known stack (Spring Boot, Django, React, …) to copy from
A published showcase booth showcase list, then booth showcase import <handle>/<slug> <folder> Someone has shared a booth for this kind of project

Run booth config from inside the project folder. The command it records in the files' header then has no absolute path in it.

More: booth config → Modes · Config TUI · Config web UI · booth example · booth showcase

Choose a variant

The variant decides what opening the booth gives you:

Variant Opens to
base (default) A browser terminal (the Console UI)
codeserver VS Code in the browser
notebook JupyterLab
xfce, kde, lxqt, wayland A full Linux desktop in the browser
booth config --no-tui --select go --variant codeserver

Everyone can still run ./booth -- bash or ./booth -- <command> without the UI, whatever the variant.

More: Variants


2. Choose the tools

Find templates

booth template list                  # everything selectable (--full adds secondary ones)
booth template search postgres       # by name, description or tag
booth template show python           # params, extensions, what it requires
booth template show python+uv --detail   # also what it writes

The categories are languages, tools, IDEs, frameworks, AI tools, desktops, middlewares, education and VM sizing.

The selection syntax

Syntax Means Example
/ next template go/python/claude-code
+ add an extension to the template before it python+uv+kernel, java+maven+lombok
: set a parameter (usually the version) python:3.13, java:21,temurin
booth config --no-tui --dryrun --select 'java:21+maven/claude-code+credential+auto-accept'

--dryrun prints what would be written and touches nothing. Use it before every real run.

More: booth config → Selection DSL · Recipes (saved selections)

Pin versions, and decide how reproducible it must be

A :version becomes an arg NAME=VALUE line in the Boothfile, and it survives later reconfigures. Pinning tool versions is the first of three tiers:

  1. Pin versions — the same tool versions on every rebuild (convenient, not exact).
  2. Freeze the resolution — lock files, plus an apt snapshot date (--apt-snapshot) so system packages resolve the same way.
  3. Store the image — build once, push it, and run that image (section 10). This is the only real guarantee.

More: Reproducibility


3. Wire up the runtime

All of these are flags on the same booth config command, so they all end up in the generated files.

Ports

booth config --no-tui --select go --expose 8080              # host 8080 → container 8080
booth config --no-tui --select go --expose '+80:8080'        # host = booth port + 80
booth config --no-tui --select 'cloudbeaver+expose'          # a service template publishes its own port

The +offset form follows the booth port, so two booths of the project never fight over a port. Servers inside must listen on 0.0.0.0.

More: booth config → Ports · booth expose

Environment variables and secrets

booth config --no-tui --select go --env TZ=UTC --env LOG_LEVEL=debug

Values that are secret, or differ per person, go in .booth/.env instead. It is gitignored, and each developer keeps their own.

More: Variable expansion

Mounts

booth config --no-tui --select go --mount '~/datasets:/home/coder/datasets'

A mount whose host path does not exist is skipped with a notice, so it is safe to list paths that only some machines have. To have booth create a missing host folder instead, add :create (--mount '~/.cache/mytool:/home/coder/.cache/mytool:create').

Credentials

Prefer the credential templates to hand-written mounts. Each one copies a host login into the booth's home at start, read-only:

Select Brings in
git-credential ~/.gitconfig
openssh+agent your host ssh-agent: git over SSH signs with its keys, no key file enters the booth (native engine on Linux)
openssh+keys only the keys in one folder you choose (default ~/.ssh/booth) — e.g. a deploy key
openssh+credential all of ~/.ssh, every private key included — the you-are-on-your-own mode, for code you trust
gh+token GitHub CLI login, from the host GH_TOKEN (GH_TOKEN=$(gh auth token) booth …); git uses it too, an SSH remote included when the booth has no ssh
envfolio+seed chosen items of your host's EnvFolio store, still encrypted, and the store key (passphrase-protected), so folio in the booth opens the secrets itself (envfolio+seed:"gh @app1 --secrets" — the arguments you give folio exec)
envfolio+store-host your host's whole EnvFolio store and gpg keyring, live and writable — every private key included
gnupg+keys chosen GPG keys (passphrase-protected) and your public keyring: gnupg+keys:"me@example.com"
claude-code+credential, codex+credential, gemini-cli+credential, … that AI tool's login

Bring in only what the project needs. Every credential in the booth is reachable by whatever code runs there.

More: booth home → Credential seeding · Security → Convenience mounts

Caches and shared state

Folder For Committed?
.booth/cache/ Per-machine state that should survive restarts: package caches, tool settings, logins Never — the booth refuses to start if it is tracked
.booth/shared/ Team state that belongs in git (shared run configs, fixtures) Yes

Many templates come with a cache extension already: java+maven+m2 reuses the host's ~/.m2, rust+cargo-cache reuses Cargo's, claude-code+settings-cache keeps Claude Code's settings.

More: Local cache · Shared state

Dotfiles

Folder Copied into ~ at start Use for
.booth/home/ Overwrites what is there Settings the team must share (.editorconfig, a team .gitconfig section)
.booth/home-seed/ Only if missing Defaults people may change

More: booth home

Startup hooks

A script in .booth/startups/ named *--startup.sh runs as coder every time the booth starts (order 50 unless the name starts with NN-). Use it to start a background service or prepare data. Keep it idempotent: it runs on every boot.

# .booth/startups/dev-server--startup.sh
nohup just dev-server > /tmp/dev-server.log 2>&1 &

Don't copy the # Generated by: header from a generated hook into yours. A reconfigure removes the hooks that carry it.

More: booth config → Startup scripts

A command menu

Every booth has just. A Justfile at the project root (just run, just test, just build) is the first thing a developer, or an AI agent, should find when they open the booth.

Console layout, idle shutdown, other settings

  • .booth/console.json sets the Console UI's starting panes and Web view tabs.
  • Any other config.toml key has --set, e.g. shut down idle booths after 30 minutes:
booth config --no-tui --select go --set idle-time=1800

More: Console layout · booth idle · booth config → Setting config values


4. Beyond the catalog

Extra packages

Each package manager has a template that takes a list:

booth config --no-tui --select 'go/apt-pkg:htop,jq'
booth config --no-tui --select 'nodejs+npm-pkg:"typescript","tsx"'
booth config --no-tui --select 'python+uv-pkg:"httpx"'

There are apt-pkg and brew-pkg, plus per-language extensions: pip-pkg, uv-pkg, conda-pkg, npm-pkg, yarn-pkg, bun-pkg, go-pkg, cargo-pkg, gem-pkg, hex-pkg, cabal-pkg, dotnet-pkg, luarocks-pkg and pecl-pkg; code-ext-pkg and jetbrains-plugin-pkg handle IDE extensions.

More: booth config → Package management templates

A setup script of your own

When a tool needs more than a package — env vars, a config file, a background service — write .booth/setups/<name>--setup.sh. It runs as root at image build. Give it a # cb-template: header and it becomes a template you can select like any other:

#!/bin/bash
# cb-template: DB seed
# cb-disc:     Load fixture data into Postgres
# cb-band:     90
# cb-param:    SEED_SET default=small suggests=small,full
set -Eeuo pipefail
SEED_SET="${1:-small}"
...
booth config --no-tui --overwrite --add-select db-seed:full

Don't type a setup <name> line into the Boothfile instead. It builds, but the Boothfile becomes hand-written. A script named after a built-in setup replaces it, so pick a new name unless that is the point.

More: A setup that is its own template · Setup script conventions · Customization

A template of your own

When one setup line is not enough — a package and a script, run-args, a port — write a project template. It is a single file, .booth/templates/<name>.toml: no directory, no meta.toml, and no display keys. This one installs libc++1 and runs a script carried inline:

[segments]
"Boothfile--45" = """
install apt libc++1
setup native-libs
"""

[files.setups]
"native-libs--setup.sh" = """
#!/usr/bin/env bash
set -Eeuo pipefail
ldconfig
"""
booth config --no-tui --overwrite --add-select native-libs

Every project template lists under This project in the TUI, named after its file unless you give it a display-name. booth config writes the inline script to .booth/setups/native-libs--setup.sh each time, so edit the script in the .toml, not the copy. A project template with the name of a built-in replaces it, with a warning. An extension of it is .booth/templates/<name>--<ext>--extension.toml.

More: Project-local templates · Template schema

Raw Docker

A .booth/Dockerfile with no Boothfile still works: booth builds from it. You give up booth config, the TUI and the catalog. Use it only if you need something a Boothfile cannot express.


5. Risky options

Some settings let code inside the booth reach the host. ./booth warns about them, and asks before starting the most powerful ones:

Option Lets the booth Asks first?
Docker-in-Docker (dind template, --dind) Run containers (privileged — effectively host root) Yes, every run (--dind-allowed with no terminal)
--privileged, --cap-add, host namespaces, engine socket mounts Act as root on the host Yes (--privileged-allowed with no terminal)
--device (e.g. /dev/kvm) Use a host device Some devices are exempt
Writable mounts of ~ or system paths Change host files Warns
--public Be reached from other machines (with a password) —

booth print-security-warning lists what a booth would trigger without starting it. To limit what the booth can reach on the network, there is --egress (it is not a boundary in a DinD booth).

Turn these on only for code you trust.

More: Security · Security checklist · Egress


6. Profiles

When the project needs the booth in more than one shape (day-to-day, a deploy run, tracing), keep one base and add only the differences:

.booth/config.toml           # always applied
.booth/dev--config.toml      # only with --profile dev
.booth/.dev--env             # that profile's secrets

The generated .booth/.gitignore already ignores .*--env. Booth refuses to start with a profile env file that git would commit, so keep that rule if you write the file yourself.

./booth --profile dev

More: booth profiles


7. Change it later

Line 2 of the Boothfile records the command that produced it:

# Configured by: booth config --no-tui --overwrite --select go+linter --expose +-1910:8090

That recorded command is the baseline. A later booth config starts from it:

You pass Result
Nothing for a setting Keeps the recorded value
--add-select X, --add-env, --add-expose, --add-mount Adds one entry, keeps the rest
--remove-select X (a template, or X+ext for an extension), --remove-env KEY, --remove-expose PORT, --remove-mount PATH Drops one entry
--select …, --env …, --expose …, --mount … Replaces that whole list
booth config --no-tui --overwrite --add-select docker          # add a template
booth config --no-tui --overwrite --add-select go+vscode-ext   # add an extension to go
booth config --no-tui --overwrite --remove-select python       # drop one
booth config                                                   # or open the TUI on the current booth

Version pins survive a reconfigure unless you set them again explicitly.

More: booth config → Reconfiguring · Adding or removing one entry


8. Prove it works

"It generated" is not "it works". Before you commit:

  1. Start it and use every tool. Run ./booth, then compile something, run the tests, gh auth status, open the exposed port. A credential that is mounted but not picked up only shows up when you use it.

  2. Check the round trip. Re-run booth config with no flags and confirm nothing changed:

    git add .booth && booth config --no-tui --overwrite && git diff --exit-code .booth

    No diff means the header fully describes the booth: the next person to open it in the TUI gets exactly these files.

Not covered yet: there is no single booth verify command that does both.


9. Commit and hand off

What to commit

Commit Keep out of git (the generated .booth/.gitignore does this)
./booth .booth/.env, .booth/.<profile>--env, .booth/.booth.password
.booth/Boothfile, config.toml, .generated .booth/cache/
.booth/tools/codingbooth.lock .booth/.tmp/
setups/, startups/, home/, home-seed/, shared/, console.json, templates/ *.bak, *.new, downloaded binaries

Without .generated, the next booth config cannot tell your later edits from its own output.

Tell the team

Something like this in the project README is enough:

## Development environment

This project runs in a [CodingBooth](https://codingbooth.io). With Docker installed:

    ./booth

See [Developing in a Booth](https://github.com/NawaMan/CodingBooth/blob/main/docs/USER_GUIDE.md).

Move the project to a new CodingBooth version

booth install <version>                  # updates the project's lock file
booth config --no-tui --overwrite        # regenerate against that release's templates

Prove it again (section 8), then commit the lock and the .booth/ changes together.

More: booth install


10. Share an image, and migrate

Build once, run everywhere

For a booth that must be identical on every machine and in CI, build the image once and push it:

./booth build --push ghcr.io/myteam --name my-env --tag v1.0
./booth --image ghcr.io/myteam/my-env:v1.0

More: booth build · Reproducibility → Store the image

Coming from a Dockerfile or a dev container

An existing .booth/Dockerfile runs as it is. To move to booth config, read the Dockerfile and find a template for each tool it installs (booth template search <tool>). Use package templates for the plain package installs and a # cb-template: setup script or a project template for the rest. Check the result with --dryrun.

Not covered yet: there is no importer for devcontainer.json. Map it by hand the same way: features become templates, forwardPorts become --expose, containerEnv becomes --env, mounts become --mount, and postStartCommand becomes a startup hook.