Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 22 additions & 9 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,13 @@ changing architecture.

## Status

Phase 0 approved (2026-10-28). Phase 1 (v0.1) approved and archived (2026-10-28,
`openspec/changes/archive/2026-10-28-phase-1-stacks-and-routing`): `setup`, `up [--wait]`,
`status [--wait]`, `ps`, `logs`, `open`, `down [--volumes]`, `skill`, routing by host and path
through `siding-proxy`, `just smoke-stacks`. Next: Phase 2 (`phase-2-overview-and-budget`,
v0.2), starting with `/opsx:propose`.
Phase 0 approved (2026-10-28). Phase 1 (v0.1) and Phase 2 (v0.2) approved and archived
(2026-10-28, `openspec/changes/archive/2026-10-28-phase-1-stacks-and-routing` and
`…-phase-2-overview-and-budget`). siding today: `setup [--port] [--budget]`, `teardown`,
`up [--wait] [--force]`, `status [--wait]`, `ps`, `logs`, `open`, `down [--volumes]`, `gc`,
`lint`, `ui`, `skill`; routing by host and path through `siding-proxy`; a memory budget;
`just smoke-stacks`, `just build-darwin`. Next: Phase 3 (`phase-3-snapshots-and-queue`, v0.3),
starting with `/opsx:propose`.

## Working agreements

Expand Down Expand Up @@ -63,6 +65,9 @@ v0.2), starting with `/opsx:propose`.
- Removable. Uninstalling siding leaves plain Compose projects that keep running.
- Not an agent manager, not a sandbox for the agent, not Kubernetes, not production, not a
hot-reload tool (Compose `develop.watch` is passed through).
- In a devcontainer, Docker-in-Docker only: no Docker-outside-of-Docker, neither for this
repository's devcontainer nor as a supported setup for users, because the host's Docker socket
is root on the host.

## Dev environment

Expand All @@ -83,6 +88,7 @@ requests and on `main`, all inside the devcontainer image.
| `just test` | devcontainer | level-1 checks, as in CI: gofmt, vet, `go test -race`, golangci-lint, `openspec validate --all --strict` |
| `just golden` | devcontainer | rewrite golden files after an intended change |
| `just build` | devcontainer | build a static `bin/siding` (linux) |
| `just build-darwin` | devcontainer | build `bin/siding-darwin-arm64` and `-amd64`, to try siding on the Mac against Docker Desktop (product use, not development) |
| `just smoke-docker` | devcontainer | inner daemon: compose project with two services and healthchecks, `ports: !reset []`, Traefik on `siding` routing `demo.main.localhost` at `/` and `/api` |
| `just smoke-stacks` | devcontainer | inner daemon: siding's own commands end to end (`internal/e2e`, build tag `docker`): setup, `up --wait`, routing, a Failed verdict with log tail, `ps`, `down`, the guard of `down --volumes`; also checks golden overrides with `docker compose config` |
| `bin/siding setup --port 8080` | devcontainer | the real `siding-proxy` on the forwarded port, to try siding by hand |
Expand All @@ -101,6 +107,10 @@ requests and on `main`, all inside the devcontainer image.
(devcontainer, its images and volumes). Delete them by exact name — never by prefix, never
with `prune`. New host objects go into that spec, `hack/nuke.sh` and (for volumes)
`devcontainer.json` together, in one change.
- Running siding on the host (e.g. `bin/siding-darwin-arm64` from `just build-darwin`) is use
of the product, not development: what it creates there (`siding-proxy`, the network
`siding`, the user's stacks, `~/.siding`) is not development footprint. `hack/nuke.sh` never
removes it; siding's own commands and `docker compose -p siding down` do.
- Tests create stacks only as Compose projects with the prefix `siding-test-` and remove them by
their exact name. The smoke tests' proxies listen on 18080, never on 8080; the end-to-end
tests run their own proxy `siding-test-e2e-proxy` on the network `siding-test-e2e`, so a
Expand All @@ -118,10 +128,13 @@ requests and on `main`, all inside the devcontainer image.
- Module `github.com/tweinmann/siding`, binary `siding`, API version `siding.dev/v1alpha1`.
- Labels on every container, network and volume siding creates or adopts: `dev.siding.repo`,
`dev.siding.branch`, `dev.siding.worktree` (absolute path), `dev.siding.machine` (stable
machine id); on containers also `dev.siding.agent` (optional; never on networks or volumes,
whose labels must not change between two `up`s). Service labels: `dev.siding.route`
(`/`, `/<path>`, `false`), `dev.siding.port` (the HTTP port of a service with several),
`dev.siding.seed` (`volume|script|none`). Volume label `dev.siding.shared`.
machine id); on containers also `dev.siding.gitdir` (the repository's common git directory)
and `dev.siding.agent` (optional), never on networks or volumes, whose labels must not change
between two `up`s. Service labels: `dev.siding.route` (`/`, `/<path>`, `false`),
`dev.siding.port` (the HTTP port of a service with several), `dev.siding.seed`
(`volume|script|none`). Volume label `dev.siding.shared`. On `siding-proxy`:
`dev.siding.budget` (the memory budget in bytes) and `dev.siding.host-alias` (what
`host.docker.internal` resolves to in the proxy).
- Compose project `<repo>-<branch-slug>`, host `<repo>.<branch-slug>.localhost`, proxy
`siding-proxy` on the network `siding`, override `.siding/override.yml`.
- Docker state is read through the Docker Engine API (Go SDK); lifecycle operations invoke
Expand Down
81 changes: 79 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,9 @@
siding gives every git worktree its own Docker Compose stack, at its own `*.localhost` address,
and tells you and your coding agents whether it actually runs and what it costs.

> **Pre-alpha (v0.1).** Stacks per worktree, routing through one local proxy and the verdict
> of `siding status` work; expect rough edges and changes before v1. There are no releases
> **Pre-alpha (v0.2).** Stacks per worktree, routing through one local proxy, the verdict of
> `siding status`, the overview `siding ui`, a memory budget, `gc` and `lint` work; expect
> rough edges and changes before v1. There are no releases
> yet: build it from source (see below). The plan is in [openspec/changes/](openspec/changes)
> (one change per phase), what siding does today in [openspec/specs/](openspec/specs).

Expand All @@ -17,6 +18,7 @@ siding needs Docker with Compose 2.24 or later, and git. Your compose file stays
```sh
siding setup # Traefik as siding-proxy on 127.0.0.1:80
siding setup --port 8080 # if port 80 is taken, or inside siding's devcontainer
siding teardown # remove the proxy again; stacks keep running, --dry-run lists it
```

Every stack is reached through this one proxy at `http://<repo>.<branch>.localhost`. Browsers
Expand Down Expand Up @@ -57,6 +59,51 @@ answers through the proxy. A failure names the service, the reason, a hint and i
lines. Exit codes: 0 Ready, 1 Failed, 2 TimedOut or still starting. Every command prints one
JSON document with `--json`, for scripts and agents.

### Before the first up: lint

```sh
siding lint # exits 1 when it finds an error; --json for a LintReport
```

`lint` checks the compose file siding would use and never changes it.

| Rule | Severity | Finds |
|---|---|---|
| `ContainerName` | error | a fixed `container_name`: a second stack cannot start |
| `FixedNetworkName` | error | an own network with a fixed `name`, shared by every stack |
| `FixedVolumeName` | error (info with `dev.siding.shared`) | an own volume with a fixed `name`, so every stack shares its data |
| `InvalidRoute`, `AmbiguousPort` | error | route labels `siding up` would refuse |
| `HostPath` | warning | a bind mount of a path outside the worktree, shared by every stack |
| `NetworkMode` | warning | `network_mode`: siding cannot route the service |
| `NoHealthcheck` | warning | no healthcheck and no route: Ready only means it started |
| `PublishedPort` | info | published ports, which siding resets |
| `NoRoot` | info | HTTP services, but none at `/` |

### Memory budget

```sh
siding setup --budget 12g # memory for all stacks together; "default" is 75 % of Docker's
siding up --force # start even if the stack does not fit
```

Before `up` starts a stack, siding adds the memory the other stacks use now to what this
stack will need: per service its `mem_limit` (or `deploy.resources.limits.memory`), or
256 MiB without a limit. If that exceeds the budget, `up` refuses with exit code 3 and says
how much is missing. Setting `mem_limit` on big services makes the estimate right. `siding ps`
shows the total against the budget.

### Overview

```sh
siding ui # http://siding.localhost while it runs; Ctrl-C stops it
```

The page lists every stack with its address and memory, the total against the budget, and what
`siding gc` would remove. It refreshes itself and is read-only; `/api/stacks` and `/api/gc`
return the documents of `siding ps --json` and `siding gc --dry-run --json`. It listens on this
machine only, and nothing of it keeps running after Ctrl-C. After upgrading siding, run
`siding setup` once, so the proxy knows the route.

### Logs, address, and taking it down

```sh
Expand All @@ -67,6 +114,35 @@ siding down --volumes # also the data; refused while the branch is unmerg
# worktree dirty, unless --force; --dry-run lists it first
```

### After a merge: gc

```sh
siding gc --dry-run # what can go, and what stays and why
siding gc # asks, then removes; --yes for scripts
```

`gc` removes the stacks of merged branches whose worktree is clean, with their volumes, and
the containers of stacks whose worktree you deleted (their volumes only if the branch is
merged). A branch counts as merged when the default branch has moved past it, or when its
upstream branch is gone, as after a squash-merged pull request and `git fetch --prune`. `gc`
never deletes worktrees or branches, and never the stack of the default branch or of a branch
without commits of its own.

### In a devcontainer

siding works inside a devcontainer that runs its own Docker daemon (Docker-in-Docker), as this
repository's does. Then:

- `siding ps`, `siding ui` and the budget see the stacks of that container, not the whole
machine; for one view of everything, run siding on the machine itself;
- forward the proxy's port (`forwardPorts` with `requireLocalPort`) and run
`siding setup --port` with it; each devcontainer needs its own port;
- the container has its own image cache.

Mounting the host's Docker socket into the devcontainer (Docker-outside-of-Docker) is not
supported: it gives everything in the container root on the host, the opposite of why agents
run in devcontainers, and bind mounts break unless the paths match inside and out.

### For coding agents

`siding skill` prints a Claude Code skill that tells an agent to run `siding up --wait --json`
Expand All @@ -90,6 +166,7 @@ on your machine and siding's tests never touch your Docker containers.
| `just test` | formatting, vet, unit tests with `-race`, golangci-lint, OpenSpec validation (as in CI) |
| `just golden` | rewrite golden files after an intended output change |
| `just build` | build `bin/siding` |
| `just build-darwin` | build `bin/siding-darwin-arm64` and `-amd64`, to run siding on your Mac |
| `just smoke-docker` | Compose, `ports: !reset []` and Traefik routing against the container's own daemon |
| `just smoke-stacks` | siding's own commands end to end against the container's own daemon |

Expand Down
34 changes: 22 additions & 12 deletions cmd/siding/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import (
"github.com/tweinmann/siding/internal/compose"
"github.com/tweinmann/siding/internal/docker"
"github.com/tweinmann/siding/internal/git"
"github.com/tweinmann/siding/internal/overview"
"github.com/tweinmann/siding/internal/probe"
"github.com/tweinmann/siding/internal/proxy"
"github.com/tweinmann/siding/internal/stack"
Expand All @@ -34,20 +35,29 @@ func main() {
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
opts := cli.Options{
Build: cli.CurrentBuild(version),
Dir: dir,
Home: home,
Getenv: os.Getenv,
OSMachineID: stack.OSMachineID,
Git: git.Client{},
Compose: &compose.CLI{},
Docker: &docker.Client{},
Probe: probe.HTTP{Header: stack.ServiceHeader},
Browser: cli.SystemBrowser{Getenv: os.Getenv},
Clock: cli.SystemClock{},
Proxy: proxy.Default(),
Build: cli.CurrentBuild(version),
Dir: dir,
Home: home,
Getenv: os.Getenv,
OSMachineID: stack.OSMachineID,
Stdin: os.Stdin,
IsLocalAddress: overview.IsLocalAddress,
IsTerminal: stdinIsTerminal,
Git: git.Client{},
Compose: &compose.CLI{},
Docker: &docker.Client{},
Probe: probe.HTTP{Header: stack.ServiceHeader},
Browser: cli.SystemBrowser{Getenv: os.Getenv},
Clock: cli.SystemClock{},
Proxy: proxy.Default(),
}
code := cli.Execute(ctx, cli.New(opts), os.Args[1:], os.Stdout, os.Stderr)
stop()
os.Exit(code)
}

// stdinIsTerminal reports whether stdin is a terminal, i.e. a human can answer a question.
func stdinIsTerminal() bool {
fi, err := os.Stdin.Stat()
return err == nil && fi.Mode()&os.ModeCharDevice != 0
}
74 changes: 74 additions & 0 deletions internal/budget/budget.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
// Package budget decides whether another stack fits into the memory the machine has for siding.
// Everything here is a pure function; the numbers come from Docker and the compose config.
package budget

import (
"fmt"
"strconv"
"strings"

"github.com/tweinmann/siding/internal/compose"
)

const (
// ServiceDefault is the estimate of a service without a memory limit. It is a guess, until
// siding learns real peaks (v0.3).
ServiceDefault int64 = 256 << 20
// DefaultShare is the part of Docker's memory that is the budget when none is set.
DefaultShare = 0.75
)

// Default is the budget without a label: 75 % of the memory the Docker daemon reports.
func Default(dockerMemory int64) int64 {
return int64(float64(dockerMemory) * DefaultShare)
}

// ParseSize reads a size as bytes or with the binary suffix k, m or g: 512m, 12g, 1073741824.
func ParseSize(s string) (int64, error) {
s = strings.ToLower(strings.TrimSpace(s))
shift := 0
switch {
case strings.HasSuffix(s, "k"):
shift = 10
case strings.HasSuffix(s, "m"):
shift = 20
case strings.HasSuffix(s, "g"):
shift = 30
}
if shift > 0 {
s = s[:len(s)-1]
}
n, err := strconv.ParseInt(s, 10, 64)
if err != nil || n <= 0 || n > (1<<62)>>shift {
return 0, fmt.Errorf("not a size: use bytes or a number with k, m or g, such as 512m or 12g")
}
return n << shift, nil
}

// Estimate is the memory a project will need: per service and replica its memory limit, or
// ServiceDefault without one.
func Estimate(p *compose.Project) int64 {
var sum int64
for _, s := range p.Services {
per := s.MemoryLimit
if per <= 0 {
per = ServiceDefault
}
replicas := s.Replicas
if replicas < 1 {
replicas = 1
}
sum += per * int64(replicas)
}
return sum
}

// Check is the outcome of fitting a stack into the budget.
type Check struct {
Budget int64
Used int64 // memory of every other stack
Estimate int64 // of this stack
}

// Fits reports whether the stack fits.
func (c Check) Fits() bool { return c.Used+c.Estimate <= c.Budget }
53 changes: 53 additions & 0 deletions internal/budget/budget_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
package budget

import (
"testing"

"github.com/tweinmann/siding/internal/compose"
)

const mib = 1 << 20

func TestParseSize(t *testing.T) {
t.Parallel()
for _, tt := range []struct {
in string
want int64
}{
{"512m", 512 * mib}, {"12g", 12 << 30}, {"12G", 12 << 30}, {"64k", 64 << 10}, {"1073741824", 1 << 30}, {" 2g ", 2 << 30},
{"", 0}, {"0", 0}, {"-1g", 0}, {"12gb", 0}, {"lots", 0}, {"99999999999g", 0},
} {
got, err := ParseSize(tt.in)
if (tt.want == 0) != (err != nil) || got != tt.want {
t.Errorf("ParseSize(%q) = %d, %v; want %d", tt.in, got, err, tt.want)
}
}
}

func TestEstimate(t *testing.T) {
t.Parallel()
p := &compose.Project{Services: map[string]compose.Service{
"db": {MemoryLimit: 1024 * mib, Replicas: 1},
"web": {Replicas: 1},
"api": {MemoryLimit: 512 * mib, Replicas: 1},
"worker": {MemoryLimit: 100 * mib, Replicas: 3},
"old": {}, // a project parsed before replicas existed counts once
}}
want := int64(1024+256+512+300+256) * mib
if got := Estimate(p); got != want {
t.Errorf("Estimate = %d MiB, want %d MiB", got/mib, want/mib)
}
}

func TestCheck(t *testing.T) {
t.Parallel()
if !(Check{Budget: 4096 * mib, Used: 3000 * mib, Estimate: 1096 * mib}).Fits() {
t.Error("exactly the budget must fit")
}
if (Check{Budget: 4096 * mib, Used: 3584 * mib, Estimate: 768 * mib}).Fits() {
t.Error("over the budget must not fit")
}
if got := Default(16 << 30); got != 12<<30 {
t.Errorf("Default(16 GiB) = %d", got)
}
}
Loading
Loading