Alex Blank
3e99e7f197
- Add test_tool_instances_legacy.py with 8 unit tests: - dockerfile definition type builds from template - dockerfile build failure raises HTTP 500 - compose definition type renders template - manifest compiler is NOT called for legacy types - start_instance legacy/compose/dockerfile types all skip manifest flow - start_instance manifest type correctly invokes compiler - Mark T3.2 and T3.3 tasks complete in OpenSpec - Add openspec/docs/tool-workshop-guide.md with user guide covering definition types, manifest creation workflow, base definitions, migration path, and permissions
82 lines
3.1 KiB
Markdown
82 lines
3.1 KiB
Markdown
# Tool Workshop User Guide
|
|
|
|
## Overview
|
|
|
|
The Tool Workshop lets you define and manage tool types — the blueprints for
|
|
containers that run inside Headquarter. Each tool type specifies how to build
|
|
and start a container (Docker image, Compose file, or a declarative manifest).
|
|
|
|
## Definition Types
|
|
|
|
### 1. Compose (Legacy)
|
|
Write a raw Docker Compose template. Variable substitution is supported:
|
|
- `${REPO_PATH}` — path to the mounted repository
|
|
- `${TOOL_PORT}` — dynamically assigned free port
|
|
- `${INSTANCE_NAME}` — generated instance name
|
|
- `${USER_ID}`, `${PROJECT_ID}` — IDs for reference
|
|
|
|
Best for: simple web services, databases, or anything that already has a
|
|
Docker image.
|
|
|
|
### 2. Dockerfile (Legacy)
|
|
Write a raw Dockerfile. Headquarter builds the image and generates a minimal
|
|
Compose file automatically.
|
|
|
|
Best for: custom environments where you need full control over the image build.
|
|
|
|
### 3. Manifest (Declarative) — **Recommended**
|
|
Define your tool with structured JSON instead of raw Docker files:
|
|
- **Base image** — pick a base definition (e.g. `ubuntu-24.04-dev`)
|
|
- **Packages** — declare apt, npm global, pip, and Node.js version
|
|
- **Scripts** — build scripts (run at image build time) and startup scripts
|
|
(run when container starts)
|
|
- **Mounts** — workspace, SSH keys, instance state, git-mounted dotfiles
|
|
- **Runtime** — command, working directory, stdin/tty settings
|
|
- **Live preview** — see generated Dockerfile and Compose as you edit
|
|
|
|
Best for: reproducible, versioned, self-documenting tool definitions.
|
|
|
|
## Creating a Manifest-Based Tool
|
|
|
|
1. Go to **Settings → Tool Workshop**
|
|
2. Click **New Tool Type**
|
|
3. Select **Manifest (Declarative)** as the definition type
|
|
4. Choose a **Base Image** (e.g. `ubuntu-24.04-dev v1`)
|
|
5. Add packages:
|
|
- Apt: `neovim`, `tmux`, `git`
|
|
- NPM global: `@earendil-works/pi-coding-agent`
|
|
- Node.js version: `20`
|
|
6. Add build scripts (e.g. configure git defaults)
|
|
7. Add startup scripts (e.g. fix workspace permissions)
|
|
8. Configure mounts:
|
|
- Workspace → `/workspace` (writable)
|
|
- SSH keys → `/home/user/.ssh` (readonly, mode 0700)
|
|
9. Set runtime: command `/bin/bash`, working dir `/workspace`
|
|
10. Click **Preview** to verify generated Dockerfile and Compose
|
|
11. Save
|
|
|
|
## Base Definitions
|
|
|
|
Base definitions are versioned manifest templates that other tools extend.
|
|
They are marked with the **Base** badge in the list.
|
|
|
|
The default base `ubuntu-24.04-dev` provides:
|
|
- Ubuntu 24.04 base image
|
|
- Common build tools (curl, wget, git, build-essential)
|
|
- A non-root `user` account (uid 1000)
|
|
|
|
## Migration from Legacy
|
|
|
|
Existing tool types using Compose or Dockerfile continue to work unchanged.
|
|
You can migrate a tool type to Manifest by:
|
|
1. Editing the tool type
|
|
2. Switching definition type to **Manifest**
|
|
3. Re-creating the configuration in the manifest editor
|
|
4. Saving (the old template is cleared automatically)
|
|
|
|
## Permissions
|
|
|
|
For manifest-based tools, mount permissions are fixed automatically after the
|
|
container starts. The system runs `chown` and `chmod` via `docker exec` as
|
|
root, then drops back to the configured runtime user.
|