Skip to content

Quickstart

This walks through wiring a repo into a running fghjd, then starting it. It assumes fghjd is already running (see Installation) and that the repo you’re pointing at has an .fghj.yaml — see .fghj.yaml if you’re setting one up for the first time.

Before wiring anything in, you can check a service’s .fghj.yaml against fghj’s schema on its own:

Terminal window
fghj validate ./.fghj.yaml

This shells out to cue vet under the hood — see fghj validate.

Terminal window
fghj wire git@github.com:acme/checkout-service.git

wire clones the entry repo (if it isn’t already checked out alongside your current directory), asks fghjd to resolve its full dependency graph, and registers the workspace so it shows up in the UI. If the repo — or any of its dependencies — declares Git-over-SSH dependencies, fghj wire is what captures your SSH agent socket so the root-owned daemon can clone them on your behalf; see Persistence & workspace store for why that hand-off exists.

Already have the repo checked out? Skip the URL and name it instead — the folder it sits in becomes the workspace:

Terminal window
cd ~/code/acme/checkout-service
fghj wire . # or: fghj wire .fghj.yaml

See fghj wire.

fghjd serves a small web UI at https://fghj.internal/ (scoped to the workspace you just wired, or pick it from the workspace switcher if you have more than one). Three tabs:

  • Repos — the full dependency graph, as declared, regardless of what’s actually running.
  • Actual — the same graph overlaid with live container status, plus controls to start/stop runs.
  • Config — reserved for environment/DNS/cert inspection; not built out yet.

See UI architecture for the full tour.

A freshly wired workspace only has the entry repo on disk — every dependency it declares shows up as a not-yet-downloaded node. Click Download all on the Repos tab, or from the CLI’s perspective, the daemon walks the graph, clones anything missing, re-resolves, and repeats until nothing new turns up (a repo’s own dependencies aren’t known until it’s cloned).

From the Actual tab, pick a flow and press Switch to flow: it brings up that flow’s nodes and stops anything else that’s running. To start a single node instead, click it and press Start — the first start creates the workspace’s one environment either way. Switching again after pulling more of the graph only starts what’s new or changed. See Run lifecycle & registry.

Once a service’s container is running, click its node for its resolved domain and open it directly. For a service named checkout in a repo checked out as checkout-service, inside a workspace directory called acme, that’s checkout.checkout-service.acme.fghj.internal — the service name, the repo folder, then the workspace. The certificate is issued on the fly by fghj’s local CA and is already trusted: on macOS your first fghj wire asked you to trust it, and on Linux fghjd put it in the system store and your browsers itself. No -k, no self-signed warning. See Local CA & TLS proxy for how that works, and Node identity & domains for exactly how that domain was derived.

The tutorial does the same with an example app and keeps going: two stores next to your service, migrations that gate it, a second repo, flows, and attaching a debugger to a running container.

If something didn’t come up the way this page describes, run fghj doctor — it checks everything fghj needs from your machine and names the one thing that’s missing.