Skip to content

BOOTH_PERSIST_HOME.md

Latest commit

 

History

History
178 lines (117 loc) · 5.61 KB

BOOTH_PERSIST_HOME.md

File metadata and controls

178 lines (117 loc) · 5.61 KB

Persist Home Directory (Experimental)

This feature is experimental. It works for common use cases but has not been exhaustively tested. Please report issues at https://github.com/NawaMan/CodingBooth/issues

Keep your IDE settings, browser history, and home directory state across booth sessions.

By default, /home/coder is rebuilt from scratch each time a container starts. With --persist-home, a Docker named volume stores the home directory so that everything survives across exits, restarts, and rebuilds.

./booth --persist-home --name myproject
# ... work, install VS Code extensions, customize settings ...
# exit and re-run:
./booth --persist-home --name myproject
# extensions and settings are still there

Back to README

Table of Contents

Overview

--persist-home creates a Docker named volume (cb-home-<container-name>) and mounts it at /home/coder. The project code directory (/home/coder/code) is still bind-mounted from the host as usual, overlaying on top of the volume.

This means:

  • Project files are always from your host (as before)
  • Everything else in /home/coder (IDE settings, shell history, app configs) persists in the volume
  • The volume is invisible to git (it lives in Docker's storage, not in the project tree)

Enabling Persist Home

CLI flag:

./booth --persist-home

Config file (.booth/config.toml):

persist-home = true

Environment variable:

CB_PERSIST_HOME=true ./booth

How It Works

First run

  1. A Docker volume cb-home-<container-name> is created
  2. The volume is mounted at /home/coder
  3. Home directory seeding runs normally (all 4 layers: project seed, project override, image seed, image override)
  4. A marker file (.cb-home-seeded) is written to track that seeding has been done

Subsequent runs

  1. The existing volume is reused (already has your files)
  2. Seed layers (no-clobber) are skipped — your customizations are preserved
  3. Override layers still apply — team-enforced configs are updated
  4. The chown fixup is fast because most files already have the correct ownership

On restart (booth--restart)

The volume survives. booth--restart removes and recreates the container, but Docker named volumes are not removed by docker rm. Your home directory state carries over.

Volume Management

Volume naming

Volumes are named cb-home-<container-name>. For example, a booth named my-project gets a volume called cb-home-my-project.

Listing volumes

docker volume ls --filter label=cb.managed=true

Cleanup

Volumes are automatically removed when you remove the booth:

./booth remove my-project  # removes both container and home volume
./booth prune              # removes stopped containers and their home volumes

To manually remove a volume:

docker volume rm cb-home-my-project

Listing volumes

booth home-volume-list

Shows all persisted home volumes with their parent container names.

Export and import

You can back up a home volume to a tar file and restore it later. Note that home volumes can be large (1–3GB for VS Code users, 5GB+ with desktop browser profiles), so this may be slow.

Export:

booth home-volume-export my-project home-backup.tar.gz

Import:

booth home-volume-import my-project home-backup.tar.gz

This is useful for backing up before a risky change, migrating to a different container name, or sharing a pre-configured home across machines.

Exit warning

When a persist-home container exits (but not on restart), a notice is printed:

Info: Home volume "cb-home-my-project" persists on disk.
      To reclaim space: docker volume rm cb-home-my-project
      Or: codingbooth remove my-project

Use Cases

  • VS Code settings and extensions — Extensions installed via the UI persist across sessions
  • Browser history — Desktop variant browser state (bookmarks, history, cookies) survives
  • Application configs — OpenOffice, JetBrains IDEs, and other app settings persist
  • Shell customizations — Changes to .bashrc, .zshrc, tool configs beyond what seeding provides
  • Package manager caches — pip, npm, cargo caches in home directory are retained

Interaction with Other Features

--keep-alive

Both features work together. --keep-alive preserves the entire container state (including system directories like /tmp, installed packages). --persist-home preserves only the home directory but works even without --keep-alive — the container is removed on exit but the home volume survives.

Feature Scope Survives exit? Survives remove?
--keep-alive Entire container Yes (stopped) No
--persist-home /home/coder only Yes (volume) No (volume removed too)

.booth/cache/

Cache mounts overlay on top of the persist-home volume for their specific paths. If you have both --persist-home and .booth/cache/home/coder/.bash_history, the cache mount takes precedence for .bash_history.

Home seeding (.booth/home-seed/, .booth/home/)

  • First run: All seeding layers run normally
  • Subsequent runs: Seed (no-clobber) layers are skipped; override layers always apply
  • Without persist-home: No change to current behavior — all layers run every time