What the dashboard shows you, and why

Which projects appear, what the marks on a card mean, and the kinds of project that behave differently from a plain one dqx generated.

If a project you know exists is not on screen, this is the page.

How projects are found

Two sources, and the second exists because the first is not enough.

The first is what a backend already knows: docker compose ls, and the lerd and herd registries. From every directory that turns up, dqx also reads its neighbours, which is how one running project makes a whole tree visible.

The second is a list of where dqx has been, in ~/.local/share/dqx/projects.json. Every command you run inside a project records its directory there.

Without that second list a project is only as findable as its containers: remove them and the directory leaves docker compose ls, and if nothing else in that tree is running the tree stops being looked at. Nine projects with valid configs went missing on this machine that way, with nothing on screen saying so.

dqx remember <path> puts a project on that list on purpose. A remembered directory that stops being a project is dropped the next time the list is read, so this never accumulates.

Making a new tree visible

Run any dqx command once inside one of its projects.

cd ~/somewhere-else/a-project
dqx info

That directory and its neighbours are listed from then on.

To tell dqx about a project by hand from the dashboard: adding a project.

What the marks on a card mean

Always visible, because each changes what you can do:

not adopted	A directory with a stack and no usable dqx config. The buttons run docker compose.
pre-router	Its stack publishes its own ports; dqx serves it through the router with an override that lasts only while it runs.
copy of <project>	Made by dqx clone or dqx agent-env.
temp	Made with --temp, so dqx clone --prune may remove it.
dockers, dockers-new, …	The tree the project is in, shown only when another project shares its client key. Amber while it is running.
mismatch	Beside the database: the config and the running image disagree on its version. The tooltip carries both.
exit 1, stopped	Beside a service dot: it died while the project runs, with its exit code; the tooltip carries its last log line.
6 PRs	Open pull requests of the project's repositories, once fetched. Click for the review tab.
reviewing…	A review of this project is running; click for its tab.
agent	On an environment's line: an agent made it with dqx agent-env.

And in the page's header:

demo data	Started with --demo: a fictional fleet from a file, not this machine.
read only	Started with --read-only: nothing can be started, stopped or written.
Bitbucket: n days left	The token dqx review uses expires within five days. Click to store a new one.

Behind details, because they are true all year:

v4 in green, v1-v3 in purple	The config shape on disk. Purple is work to do: dqx migrate rewrites it as v4.
single / multi	Where the code sits. single means the application repository is the project, with no www/ level; multi is a wrapper with one checkout per site under www/.
docker, ddev, lerd, herd	The backend this project pins with runtime:. Most projects show nothing: they made no such decision.
php 8.3	Per checkout. Hovering names the exact image.
from image	Beside the database: its version was read from the image the stack runs, because the config declares none.

Directories dqx has not adopted

A directory with a docker-compose.yml and no usable dqx config still gets a card, marked not adopted: no .dq/config.yml at all, one dqx cannot read, or one that names no client.

Skipping them was right for the card, which would have had no name and no key, and wrong for the person: one such project sat beside a clone of itself that did have a config, and the clone was the one on screen while the real project was not.

What the card shows is read off the stack. The key comes from the web container's name, so fictive_web is the fictive project; the sites are the checkouts under www/ named after a domain.

Start and stop run docker compose in that directory, because there is no config for dqx up to resolve, and the button says so on hover. check is not offered, for the same reason.

They are still served through the router: the override that serves a stack predating the router reads the stack and nothing else. Without it, starting one while the router runs ends at Bind for 0.0.0.0:443 failed: port is already allocated.

cd ~/projects/that-directory
dqx adopt --write

That makes it a dqx project, and everything on this page starts applying to it.

Projects whose stack predates the router

dqx up layers a compose override that takes the fixed host bindings away, connects the router to the project's own network, and writes a route for the project's domains. The database, redis and mail keep a published port on loopback, derived from the project and the same after every restart, so the tableplus button works here too. The override lives in dqx's own directory and dqx down removes it: the project's committed docker-compose.yml is never touched.

Only the web service joins the router's network. Everything else stays private: compose names a container after its service on every network it joins, and app, db and redis are what most stacks call theirs, so a whole stack on one shared network would let one project's web server resolve app into another project's stack.

What it needs from the stack

A service named web, with a container name. That is 34 of the 35 such stacks here. One without it is refused rather than guessed at, because picking whichever service happened to publish a port would eventually send a domain to a database.

Projects older than v4

dqx reads every config shape it has ever written, v1 to v4, so a project that predates the current one still appears and still starts. That badge is information, not a warning. dqx migrate rewrites the config in the current shape after showing you what changes.

Which backend a project runs on

The dashboard manages docker projects. A project pinning another backend is not shown, and the footer says how many, so a project you know exists never simply vanishes.

Two projects with the same client key

If you keep more than one copy of a project, the cards show which directory each lives in.

Liveness is per client key

Containers are named after the client key, so two copies of one project produce the same container names and only one can run at a time. dqx cannot tell which copy those containers belong to, so both cards show as running. The directory tag turns amber to say so.