# Setup

## Requirements

- Node.js 24 or compatible current LTS.
- pnpm. In this Windows environment use `npx pnpm@latest ...` if pnpm is not installed globally.
- Docker Desktop or another Docker Compose compatible runtime.

## Environment

Create `.env.local` from `.env.example` and fill only local development values.

Never commit real secrets. Do not put `OPENAI_API_KEY` in a `NEXT_PUBLIC_*` variable.

## Local Services

```bash
docker compose up -d
```

Services:

- PostgreSQL: `localhost:5432`
- Mailpit UI: `http://localhost:8025`
- Mailpit SMTP: `localhost:1025`

## Install

```bash
npx pnpm@latest install
```

If pnpm asks to approve dependency build scripts:

```bash
npx pnpm@latest approve-builds --all
```

## Database

```bash
npx pnpm@latest db:generate
npx pnpm@latest db:migrate
npx pnpm@latest db:seed
```

The initial administrator command will be added during the authentication phase.

## Development

```bash
npx pnpm@latest dev
```

## Quality Commands

```bash
npx pnpm@latest lint
npx pnpm@latest typecheck
npx pnpm@latest test
npx pnpm@latest test:e2e
npx pnpm@latest build
```

## Backup And Restore

Development backup:

```bash
docker compose exec postgres pg_dump -U alya alya_paros > backups/alya_paros.sql
```

Development restore:

```bash
docker compose exec -T postgres psql -U alya alya_paros < backups/alya_paros.sql
```

Production backups must be automated outside the app process, encrypted at rest, and periodically restore-tested.

## Deployment Notes

- Use a Node.js hosting target that supports Next.js App Router and server-side routes.
- Provide PostgreSQL as a managed or self-hosted production database.
- Set all secrets as environment variables.
- Store uploaded media outside the repository, with a documented backup process.
- Run migrations before serving a new release.
- Keep admin routes, booking tokens, and generated asset review pages out of search indexes.

## Troubleshooting

- If `pnpm` is not recognized, use `npx pnpm@latest`.
- If `npm` is blocked by PowerShell execution policy, use `npm.cmd` or `npx.cmd`.
- If Docker is not available, install Docker Desktop and rerun `docker compose up -d`.
- If image generation fails, verify `OPENAI_API_KEY` exists only in server-side environment variables and that the account has access to `gpt-image-2`.