Getting started

This guide gets you from zero to a running Shaperail service with browser docs, OpenAPI output, health checks, and a working local Postgres plus Redis setup.

What you need

Required:

Rust 1.85+
Docker with Compose support

Optional:

sqlx-cli if you plan to create new migrations with shaperail migrate
psql and redis-cli if you want to inspect services manually

Check your workstation with:

shaperail doctor

Install the CLI

Cargo is the canonical install path:

cargo install shaperail-cli

If you prefer a release binary on macOS or Linux:

curl -fsSL https://shaperail.io/install.sh | sh

Scaffold a project

shaperail init my-app
cd my-app

The scaffold includes:

resources/posts.yaml as a starter resource
migrations/ with an initial SQL migration
docker-compose.yml for Postgres and Redis
.env wired to that compose file
a generated app shell that serves docs, health checks, and metrics

Boot local services

docker compose up -d

This is the intended local path. A Shaperail user should not have to create a database manually before the first run.

Run the app

shaperail serve

Verify the generated surfaces:

http://localhost:3000/docs
http://localhost:3000/openapi.json
http://localhost:3000/health
http://localhost:3000/health/ready

Make your first change

Open resources/posts.yaml and change the schema or endpoint contract first. Avoid editing generated Rust files by hand.

Useful commands while iterating:

shaperail validate resources/posts.yaml
shaperail routes
shaperail export openapi --output openapi.json

Load seed data

If you have fixture files in a seeds/ directory, load them after migration:

shaperail seed

Each YAML file maps to a table by filename (e.g., seeds/users.yaml inserts into users). All inserts run in a single transaction.

When the schema changes

If you add or remove fields, create a migration and then run the app again:

shaperail migrate
shaperail serve

shaperail serve applies the SQL files that already exist in migrations/.

Troubleshooting

Problem	What to check
App cannot connect to Postgres or Redis	Run `docker compose ps` and confirm both services are healthy
Port `3000`, `5432`, or `6379` is busy	Change the host-side port in `docker-compose.yml` and update `.env` to match
`shaperail migrate` fails	Install `sqlx-cli` and confirm `DATABASE_URL` points at the same local Postgres service
Docs page loads but API calls fail	Confirm `.env`, Docker ports, and `DATABASE_URL` are aligned