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
7 changes: 5 additions & 2 deletions .devcontainer/devcontainer.json
Original file line number Diff line number Diff line change
Expand Up @@ -39,10 +39,13 @@
],

// The proxy (Traefik) listens on 8080 of the inner daemon; this forwards it to the host, so
// http://<host>.localhost:8080 reaches a stack from the browser.
// http://<host>.localhost:8080 reaches a stack from the browser. requireLocalPort: when 8080
// is taken on the host, VS Code says so instead of forwarding to another port, which would
// make every address siding prints wrong. To use another port, change both numbers here and
// run siding setup --port with it.
"forwardPorts": [8080],
"portsAttributes": {
"8080": { "label": "siding proxy", "onAutoForward": "silent" }
"8080": { "label": "siding proxy", "onAutoForward": "silent", "requireLocalPort": true }
},

// Worktrees with relative paths work both inside the container and on the host.
Expand Down
14 changes: 8 additions & 6 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Level-1 checks and the Docker smoke test. Both run inside the devcontainer image, so CI uses
# exactly the tool versions pinned in .devcontainer/Dockerfile, and the smoke test runs against
# Level-1 checks and the Docker smoke tests. All run inside the devcontainer image, so CI uses
# exactly the tool versions pinned in .devcontainer/Dockerfile, and the smoke tests run against
# the devcontainer's own Docker daemon, as locally.
#
# `just test` runs on every push. The smoke test runs on pull requests and on main.
# `just test` runs on every push. The smoke tests run on pull requests and on main.
name: ci

on:
Expand Down Expand Up @@ -39,14 +39,16 @@ jobs:
export GOCACHE="$PWD/.cache/go/build" GOMODCACHE="$PWD/.cache/go/mod"
just test

smoke-docker:
smoke:
if: github.event_name == 'pull_request' || github.ref == 'refs/heads/main'
runs-on: ubuntu-24.04-arm
timeout-minutes: 30
steps:
- uses: actions/checkout@v7
- name: just smoke-docker (in the devcontainer)
- name: just smoke-docker and smoke-stacks (in the devcontainer)
uses: devcontainers/ci@v0.3
with:
push: never
runCmd: just smoke-docker
runCmd: |
just smoke-docker
just smoke-stacks
4 changes: 4 additions & 0 deletions .golangci.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
version: "2"

# Also lint the end-to-end tests, which only build with the tag docker (just smoke-stacks).
run:
build-tags: [docker]

linters:
default: standard
enable:
Expand Down
36 changes: 24 additions & 12 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,11 @@ changing architecture.

## Status

Phase 0 done, waiting for approval (2026-10-28): devcontainer with Docker-in-Docker, OpenSpec
with the spec `dev-environment` and the draft changes `phase-1-…` to `phase-5-…` (v0.1–v0.5),
`siding version [--json]`, `just test`, `just smoke-docker`, `hack/nuke.sh`, CI.
Next: Phase 1 (`phase-1-stacks-and-routing`, v0.1).
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`.

## Working agreements

Expand Down Expand Up @@ -52,8 +53,10 @@ Next: Phase 1 (`phase-1-stacks-and-routing`, v0.1).
the last log lines of that service.
- Agent and human see the same thing. Every reading command has `--json`; exit codes are
0 Ready, 1 Failed, 2 TimedOut, 3 NoCapacity.
- Never lose work. Removing a stack or worktree refuses when the branch is unmerged or the
worktree is dirty, unless forced; every destructive command supports `--dry-run`.
- Never lose work. Removing a stack's data (its volumes) or a worktree refuses when the branch
is unmerged or the worktree is dirty, unless forced; removing containers and networks loses
nothing and is not guarded (`siding down` keeps volumes, `down --volumes` is guarded). Every
destructive command supports `--dry-run`.
- Only a human exposes anything to the internet. `siding share` is interactive only and has no
`--yes`.
- Standard building blocks (Docker Compose, Traefik, later Sablier) over custom code.
Expand All @@ -66,18 +69,23 @@ Next: Phase 1 (`phase-1-stacks-and-routing`, v0.1).
All development happens inside the devcontainer. It runs its own Docker daemon
(Docker-in-Docker), which also hosts every stack siding's tests create. Nothing is installed on
the host. Tool versions, Compose included, are pinned in `.devcontainer/Dockerfile`, the Docker engine in
`.devcontainer/devcontainer.json`. The proxy port 8080 is forwarded to the host, so
`http://<host>.localhost:8080` reaches a stack from the browser.
`.devcontainer/devcontainer.json`. The proxy port 8080 is forwarded to the host: run
`bin/siding setup --port 8080` once in the container, and `http://<host>.localhost:8080`
reaches a stack from the browser. The forward requires the host's 8080 (`requireLocalPort`):
when it is taken, VS Code says so instead of moving to another port. Free it, or change the
port in `devcontainer.json` and use the same one with `siding setup --port`.

CI runs `just test` on every push and `just smoke-docker` on pull requests and on `main`, both
inside the devcontainer image.
CI runs `just test` on every push and `just smoke-docker` and `just smoke-stacks` on pull
requests and on `main`, all inside the devcontainer image.

| Command | Run from | Purpose |
|---|---|---|
| `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 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 |
| `openspec validate --all --strict` | devcontainer | check specs and active changes (part of `just test`) |
| `openspec list` / `openspec list --specs` / `openspec view` | devcontainer | active changes, specs, dashboard |
| `/opsx:explore`, `/opsx:propose`, `/opsx:apply`, `/opsx:archive` | Claude Code | the change workflow; skills in `.claude/skills/`, regenerated by `openspec update` |
Expand All @@ -94,7 +102,9 @@ inside the devcontainer image.
with `prune`. New host objects go into that spec, `hack/nuke.sh` and (for volumes)
`devcontainer.json` together, in one change.
- Tests create stacks only as Compose projects with the prefix `siding-test-` and remove them by
their exact name. The smoke test's proxy listens on 18080, never on 8080.
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
developer's `siding-proxy` is never touched.
- No real secrets in the repo, in golden files or in logs; golden files may contain obvious
fakes such as `not-a-real-token`. `.env` values never appear in `--json` output.
- A worktree created with relative paths sets `extensions.relativeWorktrees` in `.git/config`,
Expand All @@ -108,7 +118,9 @@ 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), `dev.siding.agent` (optional). Service labels: `dev.siding.route`,
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`.
- Compose project `<repo>-<branch-slug>`, host `<repo>.<branch-slug>.localhost`, proxy
`siding-proxy` on the network `siding`, override `.siding/override.yml`.
Expand Down
83 changes: 80 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,78 @@
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.** Nothing here is usable yet: `siding version` is the only command. The plan is
> in [openspec/changes/](openspec/changes) (one change per phase), what siding does today in
> [openspec/specs/](openspec/specs).
> **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
> 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).

## Using siding

siding needs Docker with Compose 2.24 or later, and git. Your compose file stays as it is.

### Once per machine: the proxy

```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
```

Every stack is reached through this one proxy at `http://<repo>.<branch>.localhost`. Browsers
and curl resolve `*.localhost` to your machine by themselves; for other tools add the host to
`/etc/hosts`. Running `siding setup` again changes nothing unless the port differs.

### In a worktree: start the stack

```sh
siding up # e.g. shop on feature/login: http://shop.feature-login.localhost/
siding up -- --build web # arguments after -- go to docker compose up
siding up --wait # and wait for the verdict, like siding status --wait
```

`up` runs your compose file as the Compose project `<repo>-<branch>` with one more file,
`.siding/override.yml`. That file resets every published port, so branches never fight over
ports, and puts siding's labels and routes on the services. `.siding/` ignores itself in git.

- A service labelled `dev.siding.route: "/"` is the stack's root, `dev.siding.route: "/api"`
answers under that path (the path is passed on unchanged), `dev.siding.route: "false"`
hides a service.
- Every service with one container port (from `ports` or `expose`) also answers at
`http://<service>.<repo>.<branch>.localhost`. With several ports, `dev.siding.port: "3000"`
names the HTTP one.
- Published ports are gone, also a database's. Reach it with
`docker compose -p <repo>-<branch> exec db psql …`.

### Does it run?

```sh
siding status # Ready, Starting, Failed or TimedOut, per service
siding status --wait # until Ready or Failed, at most --timeout (3m)
siding ps # every stack on this machine: state, address, memory
```

`Ready` means every service with a healthcheck is healthy and every service with a route
answers through the proxy. A failure names the service, the reason, a hint and its last log
lines. Exit codes: 0 Ready, 1 Failed, 2 TimedOut or still starting. Every command prints one
JSON document with `--json`, for scripts and agents.

### Logs, address, and taking it down

```sh
siding logs -f api # docker compose logs of the stack
siding open # the stack's address in the browser; siding open api for a service
siding down # remove containers and networks; volumes and data stay
siding down --volumes # also the data; refused while the branch is unmerged or the
# worktree dirty, unless --force; --dry-run lists it first
```

### For coding agents

`siding skill` prints a Claude Code skill that tells an agent to run `siding up --wait --json`
after a change and to act on the verdict. siding writes no file itself; install it with

```sh
mkdir -p .claude/skills/siding && siding skill > .claude/skills/siding/SKILL.md
```

## Developing siding

Expand All @@ -22,6 +91,14 @@ on your machine and siding's tests never touch your Docker containers.
| `just golden` | rewrite golden files after an intended output change |
| `just build` | build `bin/siding` |
| `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 |

To try siding by hand: `just build`, then `bin/siding setup --port 8080` (the port the
devcontainer forwards), and `bin/siding up --wait` in a project; its address,
`http://<repo>.<branch>.localhost:8080`, opens in the browser on your machine. Port 8080
must be free on your machine: VS Code reports it when it is not, rather than forwarding to
another port. Then free it, or change the port in `.devcontainer/devcontainer.json` and pass
the same one to `siding setup --port`.

To remove everything siding development left on your Docker host, run `hack/nuke.sh` in a
terminal on the host (`--dry-run` lists it first).
Expand Down
39 changes: 38 additions & 1 deletion cmd/siding/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,51 @@
package main

import (
"context"
"fmt"
"os"
"os/signal"
"syscall"

"github.com/tweinmann/siding/internal/cli"
"github.com/tweinmann/siding/internal/compose"
"github.com/tweinmann/siding/internal/docker"
"github.com/tweinmann/siding/internal/git"
"github.com/tweinmann/siding/internal/probe"
"github.com/tweinmann/siding/internal/proxy"
"github.com/tweinmann/siding/internal/stack"
)

// version is set at build time with -ldflags "-X main.version=<tag>".
var version = "dev"

func main() {
os.Exit(cli.Execute(cli.New(cli.Options{Build: cli.CurrentBuild(version)}), os.Args[1:], os.Stdout, os.Stderr))
dir, err := os.Getwd()
if err != nil {
fmt.Fprintf(os.Stderr, "error: %v\n", err)
os.Exit(1)
}
home, err := os.UserHomeDir()
if err != nil {
fmt.Fprintf(os.Stderr, "error: %v\n", err)
os.Exit(1)
}
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(),
}
code := cli.Execute(ctx, cli.New(opts), os.Args[1:], os.Stdout, os.Stderr)
stop()
os.Exit(code)
}
24 changes: 23 additions & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,31 @@ module github.com/tweinmann/siding

go 1.27.3

require github.com/spf13/cobra v1.10.2
require (
github.com/containerd/errdefs v1.0.0
github.com/moby/moby/api v1.56.1
github.com/moby/moby/client v0.6.2
github.com/spf13/cobra v1.10.2
)

require (
github.com/Microsoft/go-winio v0.6.2 // indirect
github.com/containerd/errdefs/pkg v0.3.0 // indirect
github.com/distribution/reference v0.6.0 // indirect
github.com/docker/go-connections v0.8.2 // indirect
github.com/docker/go-units v0.5.0 // indirect
github.com/felixge/httpsnoop v1.0.4 // indirect
github.com/go-logr/logr v1.4.2 // indirect
github.com/go-logr/stdr v1.2.2 // indirect
github.com/inconshreveable/mousetrap v1.1.0 // indirect
github.com/moby/docker-image-spec v1.3.1 // indirect
github.com/opencontainers/go-digest v1.0.0 // indirect
github.com/opencontainers/image-spec v1.1.1 // indirect
github.com/spf13/pflag v1.0.9 // indirect
go.opentelemetry.io/auto/sdk v1.1.0 // indirect
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.60.0 // indirect
go.opentelemetry.io/otel v1.35.0 // indirect
go.opentelemetry.io/otel/metric v1.35.0 // indirect
go.opentelemetry.io/otel/trace v1.35.0 // indirect
golang.org/x/sys v0.33.0 // indirect
)
Loading
Loading