From eff49a174e76b712b6d45ba85a839ff473654af2 Mon Sep 17 00:00:00 2001 From: Preetam Dwivedi Date: Wed, 26 Aug 2026 09:53:28 -0700 Subject: [PATCH] Add docs/DEV_SETUP.md: local setup guide with platform caveats ## Summary ### Why? Setting up walgit on a fresh machine took a full debugging session: cargo not on PATH after rustup, Node 24 + pnpm/corepack unstated, protoc discovered mid-build, and a corporate agent holding port 9000 made the documented `just dev-store` unreachable on macOS with no actionable error. The README lists tools by name but not versions or per-platform installs, and never mentions just or a container runtime. ### What? - `docs/DEV_SETUP.md`: prerequisites table (exact versions, macOS + Linux install), build, `just dev-local`, git CA pinning for the self-signed origin, the test tiers, and the macOS port-9000 check with the `WALGIT__STORE__S3__ENDPOINT` workaround. - README "Running it" and the AGENTS.md doc map link to it (one home per fact). The hermeticity fix itself (pinned toolchain / dev-store preflight) is tracked in the issue filed alongside this change. ## Issue Part of https://github.com/tobi/walgit/issues/11 --- AGENTS.md | 1 + README.md | 1 + docs/DEV_SETUP.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 104 insertions(+) create mode 100644 docs/DEV_SETUP.md diff --git a/AGENTS.md b/AGENTS.md index 12e1b56..37e791b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,6 +37,7 @@ machines whose "disk" is 20 GiB of tmpfs, next to a long tail of small repositor | `web/sdk/README.md` | Users of `repos.js`. | | `web/README.md` | Frontend engineers changing the React SPA, Vite build, SDK adapter, static assets, loading states. | | `walgit.example.toml` | Every config key with its default and a comment. Change it with the code. | +| `docs/DEV_SETUP.md` | Local dev setup: prerequisites per platform, build, `just dev-local`, tests, platform caveats (macOS port 9000). | | `walgit.standalone.toml` | The one-machine shape: `walgit-server --config walgit.standalone.toml` → `https://walgit.localhost:8080/`. | | `deploy/nginx.conf.example` | An optional nginx in front; documents the `X-Accel-Redirect` byte-offload contract. | | `Containerfile`, `flake.nix` | An OCI image; a Nix package, image and devshell. | diff --git a/README.md b/README.md index 049bc60..bf9ffae 100644 --- a/README.md +++ b/README.md @@ -126,6 +126,7 @@ open https://walgit.localhost:8080/ ``` * `walgit.standalone.toml` — the one-machine shape (self-signed TLS, rustfs, every role). Start here. +* `docs/DEV_SETUP.md` — full local setup (prerequisites, build, `just dev-local`, tests, the macOS port-9000 caveat). * `walgit.example.toml` — every key with its default and a comment. * `Containerfile`, `flake.nix` — an OCI image and a Nix package/devshell. * `deploy/nginx.conf.example` — an optional nginx in front: public TLS, one `auth_request` per credential, and diff --git a/docs/DEV_SETUP.md b/docs/DEV_SETUP.md new file mode 100644 index 0000000..09d214a --- /dev/null +++ b/docs/DEV_SETUP.md @@ -0,0 +1,102 @@ +# Local development setup + +One-time setup to build, run and test walgit on your machine. If anything here is +wrong or incomplete for your platform, that is a bug — the build should be hermetic +(tracked as an open issue). + +## Prerequisites + +| Tool | Version | Install (macOS) | Install (Linux) | +|---|---|---|---| +| Rust | per `rust-toolchain.toml` | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` (rustup reads the toolchain file) | same | +| git | ≥ 2.46 | `brew install git` | distro package | +| just | any recent | `brew install just` | `cargo install just` or distro package | +| protoc | any recent | `brew install protobuf` | `apt install protobuf-compiler` | +| Node | 24 | `brew install node@24` or nvm | nvm | +| pnpm | via corepack | `corepack enable && corepack prepare pnpm@latest --activate` | same | +| container runtime | podman **or** docker | `brew install podman && podman machine init && podman machine start` | docker or podman | + +Notes: + +- **PATH**: after installing rustup, open a new shell or `source ~/.cargo/env` so + `cargo` is on `PATH`. The repo's `rust-toolchain.toml` pins the exact Rust version; + rustup installs it automatically on the first `cargo` invocation. +- **corepack**: Node ≥ 16 ships corepack but it may need `corepack enable` once so the + `pnpm` shim appears. The web build runs `pnpm` via `just web-build`. +- **macOS `timeout`**: `just` recipes prefer GNU `timeout` (or `gtimeout` from + `brew install coreutils`) but run without it — slower, still correct. + +## Build + +```sh +just web-build # web/dist (React SPA + SDK), embedded into the binary +cargo build --release -p walgit-cli +``` + +The release binary is `target/release/walgit-server` (and `target/release/walgit`). + +## Run (one box, everything local) + +```sh +just dev-local +``` + +This is self-contained: + +1. starts **rustfs** (S3-compatible store) in a container if nothing answers on + `127.0.0.1:9000`, and creates the `walgit-test` bucket; +2. builds the SPA if `web/dist` is missing; +3. builds and runs `walgit-server --config walgit.standalone.toml`. + +Then open **https://walgit.localhost:8080/** (self-signed TLS: accept the browser +warning once, or trust the CA the server publishes at `/services/public/ca.pem`). + +Auth is `mode = "none"` on loopback: everyone is `anon` with write. A push to a new +name creates the repository: + +```sh +git -c http.sslCAInfo=<(curl -sk https://walgit.localhost:8080/services/public/ca.pem) \ + push https://walgit.localhost:8080/acme/app.git main +``` + +or fetch the CA once and configure git: + +```sh +curl -sk https://walgit.localhost:8080/services/public/ca.pem -o ~/.walgit-ca.pem +git config --global http."https://walgit.localhost:8080".sslCAInfo ~/.walgit-ca.pem +``` + +### macOS caveat: port 9000 already bound + +Some corporate agents (e.g. Zscaler) bind `0.0.0.0:9000` on macOS, which makes the +documented rustfs port unreachable even though nothing shows in `lsof` for your user. +Check first: + +```sh +nc -z 127.0.0.1 9000 && echo "9000 taken" || echo "9000 free" +``` + +If taken, run rustfs on another port — either a container with a different published +port or a native binary — and override the endpoint via env (no config edit needed): + +```sh +export WALGIT__STORE__S3__ENDPOINT=http://127.0.0.1:19100 +``` + +Any S3-compatible store works (`walgit.example.toml` lists the keys; MinIO, R2, Ceph…). + +## Test + +```sh +just test # fast tier, < 1 min: unit + quick integration, in-memory store +just e2e # real git against the server (~20 s) +just warnings # zero rustc warnings across all targets +just ci # all of the above (what CI runs) +just test-s3 # store contract against local rustfs (needs the dev store running) +``` + +## Stop + +```sh +just dev-store-stop # stop the rustfs container +```