BulletJournal-Controller is the multi-project control plane for managed BulletJournal runtimes.

It provides:

• authenticated access for multiple users
• project registration and on-disk provisioning
• environment generation from controller-owned pyproject.toml and uv.lock
• serialized jobs for create/start/stop/install/export/import workflows
• Docker-backed runtime isolation, one container per project
• authenticated reverse proxying under /p/{project_id}/...
• zip export and import for managed projects

The controller now expects a locally built runtime image rather than a hard-coded remote registry image.

• built-in defaults live under src/bulletjournal_controller/defaults/
• each instance gets its own editable runtime config scaffold under instance_root/config/runtime/
• deploy keys and other private assets live in that instance-local runtime config directory, not in the repo

Example instance-local runtime config layout:

instance_root/config/runtime/
|- .env
|- runtime.json
|- default-dependencies.txt
|- runtime/
|  `- Dockerfile
|- ssh/
|  |- config
|  |- known_hosts
|  `- id_ed25519
`- private-assets/

Minimal runtime.json:

{
  "schema_version": 1,
  "runtime_image_name": "bulletjournal-runtime:local",
  "runtime_dockerfile": "runtime/Dockerfile",
  "runtime_build_context": ".",
  "default_dependencies_file": "default-dependencies.txt",
  "env_file": ".env",
  "ssh_dir": "ssh",
  "private_assets_dir": "private-assets",
  "local_bulletjournal_source": "/absolute/path/to/BulletJournal"
}

The controller reads this directory each time it needs runtime defaults, so edits there take effect for newly created projects without restarting the controller.

The controller mounts ssh_dir read-only at /home/bulletjournal/.ssh for installer and runtime containers and runs those containers as the same uid/gid as the host controller process, so private GitHub dependencies can be resolved without root-owned SSH material.

If env_file is configured, the controller passes it to Docker with --env-file for both install jobs and runtime containers, so the variables are available to Marimo sessions and orchestrated runs.

The repository mirrors the structure used by BulletJournal:

src/bulletjournal_controller/
  api/
  cli/
  domain/
  runtime/
  services/
  storage/
  _web/
tests/
web/
docs/

1. Create and activate a Python 3.11+ environment.
2. Install the package in editable mode:

pip install -e .[dev]

3. Create an instance root:

bulletjournal-controller init-instance ./instance

4. Set required secrets:

export BULLETJOURNAL_SESSION_SECRET="change-me"
export BULLETJOURNAL_COOKIE_SECURE=false

5. Create an initial user:

bulletjournal-controller create-user ./instance --username admin --display-name Admin

For automation, you can also provide a precomputed Argon2 hash instead of a plaintext password:

bulletjournal-controller create-user ./instance --username admin --display-name Admin --password-hash '$argon2id$...'

Or read the hash from standard input and update an existing user in place during password rotation:

printf '%s' '$argon2id$...' | bulletjournal-controller create-user ./instance --username admin --display-name Admin --password-hash-stdin --update

6. Build the local runtime image:

bulletjournal-controller build-runtime ./instance

7. Start the server:

bulletjournal-controller start ./instance

• project runtime containers are now namespaced by instance id, reducing cross-instance naming conflicts
• deleting a project attempts to remove its managed container even if controller metadata says the project is stopped
• you can remove all controller-managed containers for one instance with:

bulletjournal-controller cleanup-instance ./instance

This implementation establishes the MVP controller structure and core workflows described in REQS_BULLETJOURNAL_CONTROLLER.md:

• instance root initialization and validation
• SQLite metadata schema and repositories
• Argon2id-based authentication and cookie sessions
• project metadata APIs and environment generation
• background job queue with restart recovery
• Docker adapter and installer command construction
• zip export and import services
• minimal bundled web shell and separate web/ workspace scaffold

• docs/ARCHITECTURE.md
• docs/API.md
• docs/INSTANCE_FORMAT.md
• docs/PROJECT_ENVIRONMENT.md
• docs/OPERATIONS.md
• docs/TROUBLESHOOTING.md
• docs/SECURITY.md