Install

nooks serves the API and the app from the same process, and keeps everything in one SQLite file you can copy. There is no separate database to stand up, no queue, and no mail server.

Run it

docker run -d --name nooks -p 8081:8081 -v nooks-data:/var/lib/nooks ghcr.io/hoshomoh/nooks

That is the whole install — see Docker for the volume, the configuration and the health check, or Docker Compose for a file you check in instead.

From source, if you would rather build it yourself:

Build it once — three steps, chained so they stop at the first failure:

pnpm install && pnpm --filter @nooks/web release && go build -o nooks ./cmd/nooks

Then run it, as often as you like:

./nooks --data ./data

The middle step of the build is the one that is easy to miss. The app is baked into the binary with go:embed and the build output is not committed, so go build on its own produces a binary that serves nothing and says so. It needs Go, Node and pnpm; the versions are in go.mod and .nvmrc. Docker runs exactly these steps for you, which is why the image needs none of them on the machine that runs it.

Open localhost:8081. The first person to arrive creates their account and names the instance. Everybody else asks to join and an admin approves: asking is open to anybody who can reach the instance, and approving is the part that is not.

The first list

A new instance is made with one list on it, in your language, carrying a quantity, a date, a note and one thing already ticked, so the first screen shows what an item can hold rather than being empty and explaining nothing.

That list is also published as a read-only page, so the instance's address answers with something rather than a sign-in form. It was written by nooks rather than by anybody, which is what makes it safe to publish before an admin has decided anything. Contributor names are off, as they are everywhere by default.

The page carries a quiet link for a visitor to ask for an account, which is worth knowing before the instance is reachable from outside.

Delete the list, or unpublish it in Settings → Public list, and the front door goes back to asking who you are.

What it writes

Everything lives under --data: one SQLite file, and nothing else. Copy that directory and you have copied the instance.