# Setup and Installation

> Install dependencies, configure local settings, start the database and app, and verify your installation.

*Canonical: https://makerkit.dev/docs/void-cloudflare/installation/setup*

---

Run setup from the repository root after [cloning the kit](./clone-repository).

## Run Setup

```bash
node scripts/setup.mjs
```

If pnpm is already available, you can use the equivalent command:

```bash
pnpm kit:setup
```

The setup entry point checks Node.js, enables pnpm when possible, installs workspace dependencies when they are missing, and builds the kit's command tools through the install hook. The setup journey then:

1. Creates `apps/web/.env` from `apps/web/env.example` and generates a random `BETTER_AUTH_SECRET`. On later runs it fills missing settings, preserves configured values, and replaces an empty or example auth secret.
2. Starts the local PGlite database in the background on port 54323.
3. Applies database migrations.
4. Starts the app in the background at [http://localhost:5173](http://localhost:5173).
5. Asks whether to add demo accounts if the database has no accounts. Demo data requires your explicit confirmation; setup skips it once accounts exist.

Let setup create the settings file: copying `env.example` yourself leaves its auth secret empty. You can rerun setup to finish an interrupted installation.

## Verify Your Installation

Open [http://localhost:5173](http://localhost:5173). Without demo data, [create your first account](http://localhost:5173/auth/sign-up).

If you accepted demo data, [sign in](http://localhost:5173/auth/sign-in) with `user1@makerkit.dev` and password `testingpassword`. Demo users run from `user1@makerkit.dev` through `user5@makerkit.dev`; these credentials are for local development.

Verification links and codes go to Void's development email inbox. Open `.makerkit/processes/app.log` locally and follow the link after **Email inbox**. That link contains an access key; keep it private. Complete any email verification the sign-up flow requests, then confirm you can reach the app after signing in.

Check setup status at any time:

```bash
pnpm kit:doctor
```

The doctor reports what is ready and what still needs attention without changing your project. Follow the next command it returns for the area you are setting up.

## Daily Development

Setup leaves the app and database running in the background. Stop them with:

```bash
pnpm kit:stop
```

Run `pnpm kit:setup` to start them again. To run both services in the foreground instead, stop the managed processes, then start the database in one terminal:

```bash
pnpm db:start
```

Keep that terminal open. In a second terminal at the repository root, start the app:

```bash
pnpm dev
```

Press Ctrl+C to stop the foreground app; `pnpm db:stop` stops the database. Existing local data persists between restarts.

| Command | Purpose |
| --- | --- |
| `pnpm check` | Check formatting, lint, and types without changing files |
| `pnpm test:unit` | Run unit tests |
| `pnpm test:e2e` | Run Playwright browser tests |
| `pnpm build` | Build the workspace |

## Troubleshooting

- **Node version rejected:** use `nvm install` and `nvm use`, or select a version allowed by `package.json` in your version manager.
- **pnpm cannot be enabled:** follow the bootstrap error's pnpm installation instructions, then rerun setup.
- **Dependency installation failed:** resolve the error printed by `pnpm install`, then rerun setup.
- **App or database failed to start:** check `.makerkit/processes/app.log` or `.makerkit/processes/database.log`. If another process occupies port 5173 or 54323, stop that process or follow the kit command's recovery instructions, then rerun setup.
- **Sign-up email missing:** use the development inbox link in the app log; local emails do not arrive in your personal mailbox.

## Next Steps

Continue with [Configuration](../configuration/overview) to choose account modes, navigation, feature flags, and theme. Configure payment testing through [Billing](../billing/overview). Follow [Deployment](../deployment/overview) when you are ready to deploy to your Cloudflare account.
