# Installation

This page gets the framework and the canonical example running locally. The
canonical example is the best first app to study because it uses the real Iwf
build pipeline.

## 1. Enter The Development Shell

From the repository root:

```sh
nix develop
```

Use the Nix shell when possible. It gives you the Idris toolchain and the local
PostgreSQL setup expected by the checks.

## 2. Build The Framework

Still from the repository root:

```sh
pack typecheck iwf
```

`iwf` is a library package. Applications provide their own executable.

## 3. Run The Canonical App

The canonical app lives in `examples/canonical`. It is a RealWorld-style app
with HTML pages, JSON routes, authentication, generated schema rows, TypedSQL,
IDRX views, OpenAPI docs, jobs, mail previews, uploads, Stripe payloads, i18n,
and Auto Refresh.

```sh
cd examples/canonical
devenv up
```

`devenv up` starts PostgreSQL, the canonical server, and the local watchers used
by the example. On repeat runs it starts the last successful server quickly and
rebuilds in the background.

Useful commands inside `examples/canonical`:

```sh
iwf-build
iwf-test
iwf-ensure-db
iwf-kill-orphans
./build/exec/canonical-demo serve
./build/exec/canonical-demo openapi
```

## 4. Run The Main Check

From the repository root:

```sh
iwf check
```

`iwf check` runs the normal repository and canonical app verification sequence:
IDRX checks, generated-code checks, TypedSQL surface checks, framework specs,
compile fixtures, canonical schema/typegen/build checks, canonical HTTP
end-to-end checks, and OpenAPI checks.

TypedSQL is PostgreSQL-backed, so this command needs `DATABASE_URL` or
`IWF_DATABASE_URL`. The canonical app's development setup exports this for you.

To see the sequence without running it:

```sh
iwf check --dry-run
```

For a smaller loop, run focused acceptance groups:

```sh
tests/scripts/acceptance shell htmx-fragments typed-forms typedsql-postgres auto-refresh-races
```

## 5. Editor Setup

Starter apps generated by `iwf new` include the app build and check scripts
used by `iwf build` and `iwf check`. The build path installs the local
framework into `.iwf/idris2` and sets the Idris package path for the app build.

The canonical example's Nix/devenv setup provides the same package-path
environment for that app.

## Next

Create a small app with [Your First Project](your-first-project.md).