DEV Community

flisk
flisk

Posted on

Flisk.sh 101: One service.json, Then a Health URL

#flisk #goose #docker #tutorial

Part 4 of Goose lang and Flisk.sh 101. Use the Go backend. Do not pass --language goose.

Flisk turns service.json into a local Docker and Tilt stack. You own the manifest. The CLI owns .autogenerated/, including the Dockerfiles it writes beside the service. Editing those to "add Goose" is how the next flisk up deletes your work.

Install

Node.js 22.12 or newer.

node -v
npm install -g @flisk-sh/flisk
flisk --version
flisk --help
Enter fullscreen mode Exit fullscreen mode

If the site says flisk and the binary on your PATH is tdk, use the binary --help shows. Older docs still say tdk. The env overrides are still TDK_HTTP_PORT, TDK_HTTPS_PORT, TDK_POSTGRES_PORT, and TDK_BIND_ADDRESS.

Docker and Tilt are required to start a stack. They are not required for the dry run below. Start Docker before flisk up.

Project, then one service

From ~/src/goose-flisk-101:

git init
flisk project --yes
flisk resource --help
flisk resource orders-api --type backend --language go --stack shop
Enter fullscreen mode Exit fullscreen mode

Confirm --yes in --help before you add it. The CI notes for 1.3.86 used an interactive yes on flisk resource orders-api --type backend --stack shop. --language go is the 101 choice because the generated process is a long-running HTTP server. The default, if you omit --language, is Bun and Hono. That is also fine. Goose is not on that list.

Then:

flisk doctor --no-ping
flisk config verify
flisk up shop --dry-run
Enter fullscreen mode Exit fullscreen mode

--no-ping skips live URL checks. config verify fails when a generated file does not match what this CLI would write. --dry-run prints services and health URLs and starts nothing.

Read the URL it prints. Do not memorize a hostname from a blog. A checked example, Flisk 1.3.86, scaffolded orders-api in stack shop, was:

http://api.localhost:8080/api/orders/health
Enter fullscreen mode Exit fullscreen mode

Your port and host can differ. If port 80 is free you may see a *.localhost URL with no port. The route segment in that example is orders, from the resource name, not the stack name.

Ports, before you boot

Default host ports are 80 and 443. Postgres on the host side is 15432. Flisk does not claim 5432. If 80 is taken:

TDK_HTTP_PORT=18777 flisk up shop --dry-run
Enter fullscreen mode Exit fullscreen mode

If that port is also taken, doctor says so. Pick another free port. Dev ports bind to 127.0.0.1 unless you set TDK_BIND_ADDRESS. Leave that unset on a laptop.

Boot, once 

flisk up shop
Enter fullscreen mode Exit fullscreen mode

Wait until the log prints a health URL, then curl that URL. A 200 means the generated process is listening. It does not mean ./total ran. The Go service does not know that file exists.

Tilt is the inner loop after the first boot. flisk up shop is the command. There is no local Kubernetes cluster in this tutorial.

Stop with the command --help lists for shutdown. Do not docker rm the generated containers by hand and then wonder why verify drifted.

Files you may edit

Path Who owns it
service.json you
Go source the scaffold wrote under the resource you, after the first generate
.autogenerated/ the CLI
generated Dockerfiles the CLI
hello.goose, total.goose, ./total you, on the host

flisk doctor will also complain if a backend has no /health route. The Go scaffold has one. If you delete it, put it back or set healthCheckPath in service.json to the path you actually serve. An unknown JSON key is kept and ignored. A typo does not become a feature.

Next: call ./total from the host, and do not hide that binary inside the generated image.

Top comments (0)