Everyday workflows

You’ll be able to do a normal day’s work with doze: bring a stack up, reach its services from your code, read what they print, change the config, and stop.

Every step works in the app and in a terminal; the app runs the same commands. The examples use Larder, a made-up grocery service from doze-examples.

Start the stack

In the app

The Library. Each stack has a switch; the … menu holds the rest.

1. Open doze. From Applications, or type doze in a terminal.
2. Flip the stack’s switch on. It starts what was started last time, or everything the first time.
3. For something else, open the … menu: Start everything, or, while the stack is down, Choose what starts… to tick the apps you will work on. What they need comes too.

In a terminal

doze up                     # asks whether to start the same set as last time
doze up --last              # the same set, without asking
doze up --all               # everything, without asking
doze up storefront gateway  # these two and what they need

doze up returns when every service it started is ready. Add -f to follow the logs after; Ctrl+C stops following, not the stack.

Services you did not start are not off. Most sleep until something connects, then wake. See Sleep and wake.

See what is running

In the app

A stack's page. 1–4 switch between Tiles, List, Map and Grid.

1. Open the stack from the Library (⏎ on its row).
2. Read the states. Each service is awake, dozing (running, nobody connected, counting down to sleep), waking, asleep, crashing (it exited and a restart is due), failed, or off (you switched it off). A task is done, failed or not run.
3. Press ⏎ on a service to open it: why it is awake, its memory and CPU, and its recent wakes.

In a terminal

doze status          # one table: state, address, connections, memory, CPU
doze status -w       # the same, redrawn as things change
doze status --graph  # who waits on whom

Connect from your code and your tools

An app block gets its connection strings from its own env, so an app doze runs needs nothing more. For a program you start yourself, such as a test runner or psql:

In the app

Inside a service. Copy beside each line; y copies the address.

1. Open the service.
2. Press Copy on the line you want, or y for the address. A module’s Connect card also shows the same URL for Node, Python, Go, a shell, .env and psql.

In a terminal

psql "$(doze url postgres)"        # one service's connection line
eval "$(doze env)"                 # export DATABASE_URL, REDIS_URL, … into this shell
doze env --dotenv > .env           # the same as KEY=value lines
doze run --env -- go test ./...    # run one command with those variables set

doze url and doze env read the config, so the stack need not be up; connecting is what wakes a service. doze run without --env adds nothing to the command’s environment.

Read the logs

In the app

A service's Logs tab. All logs of the stack are one key away.

1. Open the service and press l for its Logs tab.
2. For the whole stack, press L on the stack’s page, or ⌘L.

In a terminal

doze logs gateway              # the newest run
doze logs gateway --run -1     # the run before it: what it said before it died
doze logs gateway --since 10m  # the last ten minutes
doze logs -f gateway orders    # follow two services
doze logs                      # every service, merged by time

Logs are kept on disk per run, so this works for a service that is asleep or crashed, and with the stack down. -f needs the stack up.

Run a task

Tasks such as migrations run by themselves before the apps that list them in after, and again when their inputs change. To run one now:

In the app

1. Open the stack and pick the task under Tasks in the sidebar.
2. Press Run (or ⏎). The output appears on the page; the runs are kept beside it.

In a terminal

doze task migrate-catalog  # run it now, whatever its state
doze task                  # every task and how it last ran

Keep one awake, put one aside

In the app

1. Pin a service awake: open it and press Pin awake (p). It stays up with nobody connected until you unpin it or the stack stops.
2. Put one to sleep now: Sleep (s). Its data stays.
3. Take one out of this run: flip its row’s switch off. Nothing wakes it, not even a connection, until you switch it on again.

In a terminal

doze pin postgres        # keep it awake; doze pin postgres --off to undo
doze sleep postgres      # sleep now; the next connection wakes it
doze wake postgres       # wake now, with what it needs
doze off storefront      # stop it and keep it stopped
doze on storefront       # back in the run; wakes on its next connection
doze restart gateway     # stop and start again

Change doze.hcl

1. Edit the file. doze lint checks it without touching anything, and doze fmt lays it out.
2. A running stack keeps the file it started with. The app says so on the stack’s page (“doze.hcl changed 2m ago, after the stack read it”), and a file that does not load is shown with its line.
3. To apply it, restart the stack: Restart larder in the … menu, or doze down then doze up.

When you only changed structure inside a module (a new role, bucket, queue or topic), doze sync applies it to the running stack. doze sync --dry-run shows what it would do first; sync also drops structure you removed.

Start a service’s data again

doze reset postgres

reset stops the service and deletes its data; the next wake sets it up fresh from the config. It asks first and cannot be undone.

Stop for the day

In the app

1. Flip the stack’s switch off on the Library. Every service stops, and so does the stack’s background daemon.
2. Close the window if you like. The bat stays in the menu bar; quitting the app leaves stacks running.

In a terminal

doze down

Next time, doze up offers what you had running.

When something is wrong

doze doctor checks the machine setup and the config and says what to fix. In the app the same report is under Settings › Machine. See Troubleshooting, and the CLI reference for every command and flag.