spinup — project plan¶
spinup is the successor to DulsaraNethmin/My-Scripts: an installable CLI that starts local
development services (databases, queues, GUIs, dev tooling) with one command, on macOS, Linux and
Windows, using Docker Compose under the hood.
The goal in one line:
brew install DulsaraNethmin/tap/spinup # or curl | sh, or scoop
spin up postgres # → Postgres 16 + pgAdmin, running in ~10 s
No cloning, no editing YAML, no remembering ports and passwords.
1. Where we're starting from (audit of My-Scripts)¶
Ten folders of Compose files and helper scripts, a README covering two of them, and several things that don't work.
Bugs that break for anyone who tries the scripts¶
| Where | Problem |
|---|---|
mysql/*.sh, mssql/*.sh, postgres/postgres-start.sh, pytorch/*.sh |
cd ./docker-compose.yml — cd into a file; the script errors or runs compose in whatever directory the user is in. |
mysql/mysql-stop.sh |
docker-compose down -v deletes the data volume on every stop. |
mysql/docker-compose.yml |
phpMyAdmin password 11111111 ≠ MySQL root root, so the GUI can't log in. MYSQL_ROOT isn't a real env var. --default-authentication-plugin is removed in MySQL 8.4+. |
mysql/mysql-run.bat |
Hard-codes C:\Users\Nethmin\Documents\scripts\…. |
nginx-proxy-manager/docker-compsoe.yml |
Misspelled filename and a pasted GNU nano 7.2 … header line → invalid YAML. |
postgres/docker-compose.yaml |
pgAdmin on host port 80: collides with nginx and needs root. |
pytorch/docker-compose.yaml |
runtime: nvidia is mandatory → fails on every machine without the NVIDIA toolkit. Jupyter with no token on 0.0.0.0. Unused workspace volume. |
redis/docker-compose.yaml |
No data volume; redisinsight:1.13.0 is the discontinued v1; redis/Dockerfile is unused. |
mssql/docker-compose.yml |
SA_PASSWORD deprecated (→ MSSQL_SA_PASSWORD); 2019 image; no healthcheck. |
nginxServer/run_server.sh |
Depends on a personal Docker Hub image instead of building the adjacent Dockerfile. |
docker-setup.sh |
Ubuntu-only, installs the EOL docker-compose v1 binary, runs a full apt-get upgrade. |
all *.sh |
Use docker-compose (v1, EOL 2023) rather than docker compose. |
Things that shouldn't be in a public repo¶
terraform/.terraform/** (a 20 MB Windows provider .exe), terraform/terraform.tfstate +
.backup, mysql.zip, mysql/run_mysql.desktop. .gitignore covers only *.sql in two folders.
Consistency problems¶
Mixed yml/yaml, five different start/stop script naming schemes, camelCase vs kebab-case
folders, hard-coded credentials and ports that differ per stack, obsolete version: keys,
:latest tags, no healthchecks, no docs beyond MySQL-on-Windows.
The Compose files themselves are the valuable part — they become the built-in stack catalog of
spinup. Everything else (start/stop scripts, .bat, .desktop, setup script) is replaced by
the CLI.
2. Architecture¶
┌─────────────────────────────┐
│ spinup (single Go binary) │
│ │
│ cmd/ cobra commands │
│ internal/ │
│ catalog/ embedded stacks (go:embed) + ~/.spinup/stacks overrides
│ compose/ wrapper over `docker compose` (exec, not SDK)
│ docker/ daemon/version/GPU/port checks
│ config/ ~/.spinup/config.yaml, per-stack .env
│ ui/ tables, colours, spinners (lipgloss)
└──────────────┬──────────────┘
│ shells out to
docker compose -p spinup-<stack> -f <stack>/compose.yaml --env-file ~/.spinup/env/<stack>.env
Key decisions:
- Go, Cobra for commands, Charm's lipgloss/bubbles for output. Single static binary, ~10 MB, no runtime deps beyond Docker itself.
- Shell out to
docker composerather than using the Docker SDK. Users get the exact behaviour they'd get by hand,spinupstays small, and every stack is still a plaincompose.yamlanyone can copy and use without the tool. - Stacks are embedded with
go:embed stacks/**. On firstup, the stack's files are materialised into~/.spinup/stacks/<name>/(so users can see and tweak them) and a~/.spinup/env/<name>.envis created from the stack's.env.example. - User overrides: anything in
~/.spinup/stacks/<name>/wins over the embedded copy;spin new <name>scaffolds a user stack there;spin reset <name>restores the embedded version. - Compose project naming:
spinup-<stack>, sodocker psand Docker Desktop show where containers came from and stacks never collide with the user's own projects. - Data lives in named Docker volumes prefixed
spinup-<stack>_…; nothing is written into the install location or the repo. - Windows is first-class: native binary, no WSL required (Docker Desktop provides
docker compose). Path handling andopenuse OS-specific code.
3. Command surface¶
spin up <stack>... [--gui] [--gpu] [--build] [--port name=1234]
spin down <stack>... stop, keep data
spin restart <stack>...
spin destroy <stack>... [-y] stop AND delete volumes (confirms)
spin list all stacks: name, description, status, ports
spin ps [stack] containers with health, ports, uptime
spin logs <stack> [-f] [service]
spin shell <stack> [service] exec into the primary container
spin cli <stack> open the native client (psql / mysql / mongosh / redis-cli)
spin open <stack> open the stack's GUI URL in the browser
spin env <stack> [--edit] show or edit ports/credentials for the stack
spin url <stack> print the connection string (postgres://user:pass@localhost:5432/db)
spin info <stack> README of the stack: what it is, ports, creds, gotchas
spin doctor docker daemon, compose v2, port collisions, disk, GPU
spin new <name> scaffold a user stack in ~/.spinup/stacks/<name>
spin reset <name> restore a built-in stack to its embedded version
spin update self-update the binary (GitHub Releases)
spin completion <shell> bash/zsh/fish/powershell completions
spin version
Behavioural rules:
upis idempotent and never removes anything;destroyis the only command that deletes volumes and it asks first (skip with-y).--guiand--gpumap to Compose profiles in the stack (gui,gpu). Whether GUIs are on by default is a config option (spinup config set gui true).--portoverrides a host port for this invocation without editing the env file; a persistent change goes throughspin env <stack> --edit.- Anything after
--is passed straight todocker compose, so power users are never blocked. - Output is colourised with
NO_COLORrespected;--jsononlist/psfor scripting. - Exit codes: 0 ok, 1 usage, 2 docker not available, 3 stack not found, 4 compose failed.
- After
up, print a compact card: services, host ports, GUI URL + login, and the connection string — the info people otherwise go digging for.
4. Stack format¶
Each stack is a folder with three files; the CLI is fully generic and never needs editing to add one.
stacks/postgres/
├── compose.yaml # Compose v2, no version: key, env-driven, profiles for gui/gpu
├── .env.example # every tunable with its default, one comment each
├── spinup.yaml # metadata read by the CLI
└── README.md # shown by `spin info postgres`
spinup.yaml:
name: postgres
description: PostgreSQL 16 with pgAdmin
category: database # database | messaging | storage | tooling | ml | web
primary: postgres # service used by shell/cli/logs default
cli: psql -U ${POSTGRES_USER} ${POSTGRES_DB}
gui:
service: pgadmin
url: http://localhost:${PGADMIN_PORT}
login: ${PGADMIN_EMAIL} / ${PGADMIN_PASSWORD}
url: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:${POSTGRES_PORT}/${POSTGRES_DB}
ports:
- name: POSTGRES_PORT
default: 5432
- name: PGADMIN_PORT
default: 8080
profiles: [gui]
# Optional, for a stack whose services all sit behind profiles (stacks/pytorch,
# where the CPU and GPU services share ports so neither can start by default):
default_profiles: [cpu] # what `up` selects when the user selects nothing
gpu: # what `up --gpu` swaps in
profile: gpu
service: jupyter-gpu
name, description, category, primary, url and at least one port are required;
name must match the directory. The exception is a stack that declares worker: true —
a scheduler or background job that binds no host port at all (stacks/jobzkraper), where
url and ports fall away and cli becomes required instead: with nothing to connect
to, spin cli <stack> -- … is the only way in. A gui whose service is a separate container must be
behind the gui profile — that is what makes it optional. A gui served by the primary
service itself (nginx, Nginx Proxy Manager, JupyterLab) has nothing to gate and declares
no profile. internal/catalog and scripts/lint-stacks.sh enforce the same rules, and
unknown keys are an error rather than being ignored.
Compose conventions (applied to every stack):
- Services named after the product; images pinned to a major tag (
postgres:16,redis:7-alpine,mongo:7), never:latest. - Every port/password/db name from env with inline defaults:
"${POSTGRES_PORT:-5432}:5432". - Named volumes for data;
healthcheckon the primary service;depends_on: condition: service_healthyfor GUIs;restart: unless-stopped. - GUIs on non-colliding 8xxx ports so many stacks run side by side (port table in README).
- Optional
init/mounted to the image'sdocker-entrypoint-initdb.dfor seed data. README.mdper stack: purpose, ports, creds, GUI, seeding, gotchas.
5. Repo layout¶
spinup/
├── main.go
├── cmd/ # one file per command
├── internal/{catalog,compose,docker,config,ui}/
├── stacks/ # the catalog (embedded at build time)
│ ├── postgres/ mysql/ mariadb/ mssql/ mongodb/ redis/
│ ├── opensearch/ clickhouse/ neo4j/ couchdb/
│ ├── rabbitmq/ kafka/ nats/ minio/ mailpit/ localstack/
│ ├── portainer/ traefik/ monitoring/ keycloak/ vault/ adminer/
│ ├── nginx-static/ nginx-proxy-manager/
│ ├── qdrant/ chroma/ pgvector/ weaviate/
│ └── pytorch/
├── install.sh # curl | sh installer (detects OS/arch, fetches latest release)
├── install.ps1 # Windows equivalent
├── .goreleaser.yaml # binaries, checksums, Homebrew tap, Scoop bucket, winget manifest
├── .github/workflows/
│ ├── ci.yml # go vet/test, golangci-lint, `docker compose config` for every stack,
│ │ # and a smoke matrix that `up`s the light stacks and waits for healthy
│ └── release.yml # on tag → GoReleaser
├── docs/ # optional later: mkdocs site with one page per stack
├── setup/ # docker-ubuntu.sh, docker-fedora.sh, docker-macos.sh (from docker-setup.sh)
├── CONTRIBUTING.md README.md LICENSE CHANGELOG.md
└── Makefile # build / test / lint / snapshot-release
Two small repos of your own that GoReleaser commits into (it does not create
them): DulsaraNethmin/homebrew-tap and DulsaraNethmin/scoop-bucket. Homebrew
gets a cask, not a formula — GoReleaser deprecated formula generation, and
casks are macOS-only, so Linux is served by the archives and install.sh.
docs/RELEASING.md has the one-time setup.
6. Phased roadmap¶
Phase 0 — Repo hygiene + rename (½ day)¶
- Rename
My-Scripts→spinupon GitHub (old links redirect); set description + topics (docker,docker-compose,local-development,cli,devtools,golang). - Delete
mysql.zip,terraform/.terraform/,*.tfstate*,run_mysql.desktop,redis/Dockerfile, all.bat/.shstart-stop scripts (superseded by the CLI). Purge the 20 MB binary from history withgit filter-repo(one-time force push, noted in README). - Real
.gitignore,.editorconfig,CHANGELOG.mdstarted.
Phase 1 — Catalog v1: standardize the existing stacks (1 day)¶
- Move to
stacks/<name>/, kebab-case,compose.yaml, addspinup.yaml,.env.example,README.md; apply §4 conventions; fix every bug in §1. - Image updates:
mysql:8.4,postgres:16,mongo:7(+ mongo-express),redis:7-alpine+redis/redisinsight:2,mcr.microsoft.com/mssql/server:2022-latest, pytorch GPU behind agpuprofile with Jupyter token enabled. - nginx-static builds locally from its Dockerfile; nginx-proxy-manager fixed and documented.
- CI job:
docker compose configon every stack.
Phase 2 — CLI core (2 days)¶
- Go module, Cobra skeleton,
internal/packages,go:embedofstacks/. - Commands:
up,down,restart,destroy,list,ps,logs,env,doctor,version. - Materialise-on-first-use into
~/.spinup/, env-file handling, project naming, profiles. - Unit tests for catalog parsing and env merging; integration test that ups
redisin CI.
Phase 3 — Distribution (1 day)¶
- GoReleaser: darwin/linux/windows × amd64/arm64, checksums, cosign signatures.
- Homebrew tap + Scoop bucket auto-updated by the release workflow; winget manifest PR script.
install.sh/install.ps1;spin updateself-updater; shell completions.- First tagged release
v1.1.0with the Phase-1 catalog (§7.6 explains the number). README hero switches to the install one-liner.
Phase 4 — CLI polish (1 day)¶
shell,cli,open,url,info,new,reset,completion,--json,--port.- Post-
upsummary card;doctorchecks port collisions, GPU runtime, Compose version.
Phase 5 — Catalog v2: new stacks (2–3 days, one PR each)¶
Order by usefulness-per-effort: mailpit, minio, adminer, rabbitmq, mariadb, nats,
portainer, couchdb, neo4j, clickhouse, localstack, vault, traefik, kafka
(KRaft + kafka-ui), opensearch (+ Dashboards), monitoring (Prometheus + Grafana +
node-exporter + cAdvisor with a provisioned Docker dashboard), keycloak (Postgres-backed).
Each new stack must pass docker compose config, come up healthy in the CI smoke matrix, and
ship a README before merging.
Phase 6 — Docs & community (1 day)¶
- README: install one-liner, 30-second demo GIF (
vhs), stack table, platform notes, FAQ. CONTRIBUTING.mdwith the stack checklist; issue templates ("request a stack", "bug").- Optional:
docs/mkdocs site on GitHub Pages, one page per stack, auto-generated fromspinup.yaml+ README.
7. Decisions still open¶
- Rename timing — rename the GitHub repo in Phase 0 (recommended; redirects keep your pinned link working) or wait until v0.1.0 ships.
- GUIs on by default? Plan says on (
guiprofile enabled unless--no-gui), because the GUI is half the reason to use a stack; flip to opt-in if you'd rather keepuplean. - Elasticsearch vs OpenSearch — plan uses OpenSearch (Apache-2.0, no licence env var).
- Traefik integration — opt-in shared
spinupnetwork sohttp://pgadmin.localhostworks when traefik is running; stacks join it only ifspinup config set traefik true. - Go module path —
github.com/DulsaraNethmin/spinup(public repo name must match). Settled in task 2.1: the module isgithub.com/DulsaraNethmin/spinup. - First release number — the repo already carries a
v1.0.0tag from its My-Scripts days, sogit describereportsv1.0.0-N-g<sha>and a v0.1.0 release would sort below a tag that is already published. Settled in task 3.1: the old tag stays where it is and spinup's releases start atv1.1.0. Nothing to delete, no link to break; the cost is that 1.x arrives before the command surface is finished, so Phases 4–5 land as minor versions.