Repository navigation
Run your first app
# Register: morrow flags (like -w) go BEFORE the app name;
# everything after the executable is passed to your app unchanged.
sudo morrow create -w /srv/api api /usr/bin/python3 main.py --port 8080
sudo morrow start api # starts it in the background, detached from your terminal
morrow list # name, status, PID (no sudo needed)
morrow status api
morrow detail api # full config; add --json for scripts
sudo morrow logs api -n 100 # last 100 lines; -f to follow
sudo morrow restart api
sudo morrow stop api
sudo morrow delete api # add -f to stop it first if it is runningChange the command or working directory later with update:
sudo morrow update -w /srv/api-v2 api /usr/bin/python3 main.py --port 9090
sudo morrow update -w "" api /usr/bin/python3 main.py # -w "" clears the working directoryWorking directory (-w). Apps that read relative paths (config.yml, .env, a Python venv) need it. Without -w, the app inherits the directory you ran morrow start from, which changes from run to run.
Logs. Each app's stdout and stderr go to <logs>/<app>.log, rotated at 10 MB (3 old files kept, gzipped, 28 days). A small relay process per app does this; it also marks the app stopped when it exits.
Stopping. morrow stop sends SIGTERM to the app and its child processes, waits up to 10 seconds for it to exit (--timeout 30s to change), then kills it, and returns only once it is gone. restart does the same before starting it again, so the old process never overlaps the new one. On Windows, console apps cannot be asked to exit, so they are terminated right away.
Crashes. Each app runs as the child of a small supervisor (its log relay), which sees the real exit code, or the signal that killed it. morrow detail shows it as Last Exit. What happens next is the app's restart policy:
--restart |
When the app exits without morrow stop
|
|---|---|
no (default) |
it is recorded as exited and stays down |
on-failure |
it is restarted after a non-zero exit code or a signal; exit code 0 means "done" |
unless-stopped |
it is restarted after any exit |
sudo morrow create --restart on-failure api /srv/api/server # or: sudo morrow update --restart on-failure ...
sudo morrow update --max-restarts 10 api /srv/api/server # default 5Restarts wait 1s, 2s, 4s, ... (at most a minute) and give up after --max-restarts restarts in a row; an app that ran for at least a minute before exiting starts counting from zero again. While it waits the status is restarting, and morrow stop cancels the restart. Each restart re-reads the app's variables, so a rotated secret takes effect, and keeps the start -e values. Every decision is written to the app's log, e.g. [morrow] exited unexpectedly after 3s (exit code 1); restarting in 2s (attempt 2/5).
Running as a dedicated account. On a system install apps run as root/Administrator unless you say otherwise. Run each app as its own unprivileged account, so a compromised app cannot read the master key, other apps' data or anything root owns:
sudo useradd --system --no-create-home svc-api # once
sudo morrow create --user svc-api -w /srv/api api /srv/api/server
sudo morrow update --user "" api /srv/api/server # back to rootThe supervisor stays root (it writes the logs and decrypts the app's secured variables, which the app still receives), and only the app runs as svc-api, with that account's HOME/USER. The account needs read access to the executable and the working directory.
On Windows, starting a process as another account needs its password. Pass it through an environment variable, so it never appears on the command line; Morrow stores it encrypted with the master key:
$env:SVC_PW = '...'; morrow create --user svc-api --password-env SVC_PW api C:\srv\api\server.exe; Remove-Item Env:SVC_PWThe account must be allowed to log on as a batch job or locally. morrow detail shows the account but never the password. If you change the account's password, run morrow update --user ... --password-env ... again.
Alerts. Hooks run a command or call a webhook when an app exits unexpectedly:
sudo morrow hook add api --on crash,giveup --webhook https://hooks.slack.com/services/T000/B000/XXXX
sudo morrow hook add api --on giveup --exec 'logger -t morrow "$MORROW_APP_NAME gave up (exit $MORROW_EXIT_CODE)"'
morrow hook list api # targets are shown only to administrators
sudo morrow hook test api <id> # fire it now with a sample event
sudo morrow hook remove api <id>Events: crash (non-zero exit or a signal), exit (exit code 0), giveup (the restart policy stopped). Commands get MORROW_EVENT, MORROW_APP_NAME, MORROW_EXIT_CODE, MORROW_EXIT_SIGNAL, MORROW_RESTART_COUNT, MORROW_EVENT_TIME and MORROW_HOST; webhooks receive the same fields as a JSON POST. Hooks run as the supervisor (root/Administrator on a system install) with a timeout, and are stored encrypted with the master key, since commands and URLs often hold tokens. The app's log records whether each hook ran, naming only the webhook's host.
Reboots. Run this once on a server:
sudo morrow startup # Windows: from an Administrator terminal
morrow startup --status # is it installed, and which apps start at bootAt every boot it starts the apps you started and did not stop yourself: morrow start/restart adds an app to that list, morrow stop removes it, while crashes, automatic restarts and uninstall leave it alone.
-
Linux: a systemd unit,
morrow.service, which also stops the apps gracefully when the machine shuts down. Restarting or stopping the unit by hand never stops apps; only a real shutdown does. -
Windows: a scheduled task,
Morrow\Startup, that runs as SYSTEM shortly after startup. Apps it starts run in the services session, so they keep running when users log off. Apps you start yourself from an Administrator terminal run in your session and may stop when you log off; a reboot (orschtasks /Run /TN Morrow\Startupafter stopping them) moves them to SYSTEM. -
sudo morrow startup --removeuninstalls the hook without stopping anything.
← Pick an install mode · Environment variables and secrets →
Generated from doc/tutorial.md. Edit it there; wiki edits are overwritten on the next sync.