Quickstart

Get started

One happy path: from nothing to a todo app served from inside Postgres, then to a deploy.

Prerequisites

Docker (runs the bundled Postgres 17 + extension image)
Rust toolchain, for cargo install

1 · Install the CLI

cargo install pg-web

2 · Scaffold and run

pg-web init my-app --template todo
cd my-app

pg-web up             # start Postgres (with the web server inside)
pg-web migrate apply  # create the app's tables
pg-web push           # load routes, templates, assets

open http://localhost:8080

You now have a working HTMX todo app — handlers in pages/**.sql, templates in pages/**.html, shared chrome in components/.

3 · Develop with live reload

pg-web dev

Watches your files, pushes on save, reloads the browser. Edit a template and watch the page change; break a handler and get a real error page with the SQL context.

4 · Deploy it

The app is one compose stack (the image) plus Caddy for TLS. Point [deploy.prod] in pgweb.toml at your box and:

pg-web push --target prod

Deploy docs — VPS setup, Caddy, backups — live in Docs → Deploy.

Where next

Tutorial

Build the todo app yourself, file by file.

Guide

Routes, handlers, templates, assets, settings.

How it works

The architecture, and why it holds up.