Deploying vow-web-server

Decision tree

1. Install toolchain — Install Vow
2. Install vow-serve globally — vpm add vow-serve -g
3. Pick a path:
   • Local dev → vds (live reload)
   • Production daemon → vow-serve start
   • Single VPS → vow-serve init systemd
   • Container → vow-serve init docker
   • TLS → reverse proxy + loopback bind

Install vow-serve (once)

vpm add vow-serve -g
# ergonomic alias:
vow add vow-serve -g

This links vow-serve, vs, and vds into ~/.vow/global/bin/. Add that directory to your PATH if needed.

Monorepo / offline:

vpm add vow-serve --path ../vow-frameworks/vow-serve -g

Per-project setup

cd my-api
vow-serve init          # vow.serve.toml, vow.grants.toml, Dockerfile, systemd unit

vow.serve.toml

[app]
main = "src/main.vow"
name = "my-api"
port = 8787

[bind]
mode = "loopback"   # loopback | public

[process]
release = true
health_path = "/health"

bind.mode	Grant	Address
loopback	--grant net::8787	127.0.0.1
public	--grant net:*:8787	0.0.0.0

Extra grants live in vow.grants.toml (fs, db, …). Net bind is merged from vow.serve.toml.

Dev — vds

vds
# or: vds src/main.vow -- --grant net:

Foreground watch + rebuild. Not registered in the global process list.

Prod — vow-serve (PM2-style)

vow-serve start
vow-serve list
vow-serve status my-api
vow-serve logs my-api -f
vow-serve restart my-api
vow-serve stop my-api
vow-serve delete my-api

Global registry: ~/.vow/serve/apps/. Logs: ~/.vow/serve/logs/.

Note

Add a /health route returning JSON (e.g. {“ok”:true}) for automatic health checks on start.

VPS (systemd)

vow-serve init systemd
sudo cp my-api.service /etc/systemd/system/
sudo systemctl enable --now my-api

Docker

vow-serve init docker
docker build -t my-api .
docker run --rm -p 8787:8787 my-api

Reverse proxy (TLS)

Bind loopback only (bind.mode = "loopback"), put nginx or Caddy in front. See Net grants.

Troubleshooting

Issue	Fix
vow-serve: command not found	vpm add vow-serve -g; add ~/.vow/global/bin to PATH
Health check timeout	Ensure /health route exists; check grants and port
Grant denied	Review vow.grants.toml and bind mode
Port in use	Change [app].port or stop the other process

See also

• vow-serve package
• vpm global install
• Deploying to serverless (short-lived vs long-running)