> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neobank.proofof.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Local development stack

> Run the deterministic Perflo Neobank sandbox with isolated session and task transport, loopback-only ports, and debug authentication.

# Local development stack

The local stack runs the full platform — API, worker, scheduler, web app, Postgres, isolated
session and task Redis instances, and Vault — against the deterministic `fake` Perflo
adapter. Nothing leaves your machine: the API and web app bind to `127.0.0.1` only, and the
dev environment enables debug authentication so you can sign in without an Auth0 tenant.

The stack is defined in `compose.yaml`.

| Service       | Image                    | Role                                                                          |
| ------------- | ------------------------ | ----------------------------------------------------------------------------- |
| `postgres`    | `postgres:17.9-alpine`   | Primary state store (DB `neobank`, user `neobank`).                           |
| `redis`       | `redis:7.4.9-alpine`     | API sessions and rate limits. Runs with AOF (`--appendonly yes`).             |
| `redis-tasks` | `redis:7.4.9-alpine`     | Celery task broker and result backend. Runs with AOF.                         |
| `vault`       | `hashicorp/vault:1.21.1` | Dev-mode Vault, root token `development-only-token`. Not for secure runtimes. |
| `api`         | builds `apps/api`        | Runs `alembic upgrade head && uvicorn neobank.main:app` on `127.0.0.1:8000`.  |
| `worker`      | builds `apps/api`        | Celery worker (`--concurrency=2`).                                            |
| `scheduler`   | builds `apps/api`        | Celery beat scheduler.                                                        |
| `web`         | builds `apps/web`        | Vite React app served on `127.0.0.1:3000` → container `8080`.                 |

<Warning title="Loopback only">
  The `api` and `web` services publish on `127.0.0.1`, not `0.0.0.0`. The local stack is not reachable from another host without an overlay, and the dev-mode Vault root token (`development-only-token`) must never leave this machine. Do not expose this stack publicly.
</Warning>

## Bring the stack up

<Steps>
  ### Create your `.env`

  `make env` copies `.env.example` to `.env` when `.env` does not already exist.

  ```bash theme={null}
  make env
  ```

  The dev `.env` enables debug authentication (`NEOBANK_DEBUG_AUTH_ENABLED=true`) and selects the `fake` adapter, with empty Perflo provider URLs. Auth0 values are blank because debug auth bypasses Auth0 locally.

  ### Install dependencies

  `make install` syncs the Python and web dependencies:

  ```bash theme={null}
  make install
  ```

  ### Start the stack

  `make up` builds the images and starts every service in the foreground:

  ```bash theme={null}
  make up
  ```

  The API container runs `alembic upgrade head` before starting uvicorn, so the database schema is current on every boot. Once the API health check passes, open `http://localhost:3000`.

  ### Stop the stack

  `make down` stops and removes containers and networks, but keeps the named volumes:

  ```bash theme={null}
  make down
  ```

  To drop the `postgres-data`, `redis-data`, and `redis-tasks-data` volumes as well — for example to force a fresh migration — run Compose directly:

  ```bash theme={null}
  docker compose down --volumes
  ```
</Steps>

## Debug authentication

The development `.env` sets `NEOBANK_DEBUG_AUTH_ENABLED=true`. With debug authentication enabled, the API accepts a debug identity header instead of an Auth0 session. Production rejects this flag.

## What is not here

The default local stack uses `fake`, so it makes no provider calls. Run `make live-up` to use `live` with PostgreSQL, both Redis authorities, local Vault, loopback application origins, explicit debug authentication, and the five reviewed HTTPS Perflo origins. See [Single-server deployment](deploy/dedicated-server) and [Production readiness](get-started/production-readiness).