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.
1. Validate a config
Section titled “1. Validate a config”Before wiring anything in, you can check a service’s .fghj.yaml against
fghj’s schema on its own:
fghj validate ./.fghj.yamlThis shells out to cue vet under the hood — see
fghj validate.
2. Wire a workspace
Section titled “2. Wire a workspace”fghj wire git@github.com:acme/checkout-service.gitwire 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:
cd ~/code/acme/checkout-servicefghj wire . # or: fghj wire .fghj.yamlSee fghj wire.
3. Open the UI
Section titled “3. Open the UI”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.
4. Pull the rest of the graph
Section titled “4. Pull the rest of the graph”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).
5. Start it
Section titled “5. Start it”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.
6. Open a service over HTTPS
Section titled “6. Open a service over HTTPS”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.
Where next
Section titled “Where next”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.