> ## Documentation Index
> Fetch the complete documentation index at: https://help.pixwel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Run the full Pixwel stack locally — one-click with GitHub Codespaces, or with Docker Compose and the pixwel CLI.

There are two ways to bring up the stack: **GitHub Codespaces** (one-click, everything provisioned for you) or a **local Docker** setup driven by the `pixwel` CLI. Both run the same containers — API, MongoDB, Redis, ElasticSearch, ElasticMQ, and the background workers.

## Codespaces (one-click)

Everything is preconfigured in `.devcontainer/`, so a Codespace boots the whole stack with no manual setup.

<Steps>
  <Step title="Open the Codespace">
    Open the repo as a Codespace **in VS Code desktop** (avoid the in-browser version). It requests an 8-CPU / 16 GB machine.
  </Step>

  <Step title="Wait for provisioning">
    The dev container builds and runs `./install.sh` automatically (the `postCreateCommand`). This mounts the Docker socket and sets up the workspace at `/workspaces/platform`.
  </Step>

  <Step title="Start the stack">
    Run `cd director; npm start`. A **dashboard** opens with links to each running service.
  </Step>
</Steps>

The dev container ships the PHP debug, Intelephense, GitLens, and Docker VS Code extensions, so debugging works out of the box.

## Local Docker setup

### Prerequisites

* [Docker](https://docs.docker.com/desktop/)
* [Node.js](https://nodejs.org/en/download)
* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), configured with credentials
* **Linux only:** raise the ElasticSearch mmap limit — `sysctl -w vm.max_map_count=262144` (persist it in `/etc/sysctl.conf`)

### Install

<Steps>
  <Step title="Clone and link the CLI">
    ```bash theme={null}
    git clone git@github.com:Pixwel/platform.git
    cd platform
    (cd cli; pnpm i; npm link)   # installs the `pixwel` CLI
    pixwel path                  # point the CLI at this checkout
    ```
  </Step>

  <Step title="Add the environment file">
    Obtain `development.env` and place it inside `docker/`, then export your GitHub packages token:

    ```bash theme={null}
    export NPM_TOKEN=xxx
    ```
  </Step>

  <Step title="Run the installer">
    ```bash theme={null}
    ./install.sh
    ```
  </Step>

  <Step title="Bring the stack up">
    ```bash theme={null}
    pixwel up
    ```

    The API is served at `http://localhost:8080`.
  </Step>
</Steps>

### Load data

The stack starts empty. To seed it from a database dump:

```bash theme={null}
# unzip a dump (e.g. staging.zip) into util/dump first
cd utils && ./mongo-restore-local-from-dump.sh
```

## What's in the stack

`pixwel up` runs `docker-compose.yml` (the app image is `ghcr.io/pixwel/platform`). The dev **override** (`docker-compose.override.yml`) exposes service ports for local access:

| Service           | Purpose                                                                                    | Local port  |
| ----------------- | ------------------------------------------------------------------------------------------ | ----------- |
| **app**           | The PHP API (and web)                                                                      | `8080` → 80 |
| **mongo**         | Primary database                                                                           | `27017`     |
| **redis**         | Cache + queues                                                                             | `6379`      |
| **elasticsearch** | Search index                                                                               | `9200`      |
| **elasticmq**     | Local SQS-compatible queue                                                                 | `9324`      |
| **workers**       | Background jobs — email sending, embargo expiry, notifications, feedback, and integrations | —           |

Other compose files layer on top: `docker-compose.minio.yml` (local S3-compatible storage), `docker-compose.debug.yml`, and `docker-compose.override.yml`. Dockerfiles live under `docker/` (`docker/app/Dockerfile`, `Dockerfile-dev`, `docker/Dockerfile-ui`, `docker/mongo/`, `docker/elasticmq/`).

## Common commands

| Command                             | Does                                                                     |
| ----------------------------------- | ------------------------------------------------------------------------ |
| `pixwel up`                         | Start the full stack (recommended).                                      |
| `pixwel stop` / `pixwel down`       | Stop / tear down the stack.                                              |
| `pixwel bash`                       | Shell inside the API container.                                          |
| `pixwel logs`                       | Tail application logs.                                                   |
| `pixwel dlogs`                      | Tail Docker logs.                                                        |
| `pixwel debug`                      | Run the API with **xdebug** enabled (slower). See [Xdebug](/api/xdebug). |
| `pixwel kahlan [--debug] [--watch]` | Run the API specs ([Kahlan](/api/testing)).                              |
| `pixwel li3 <cmd>`                  | Run Lithium console commands (e.g. `pixwel li3 index-rebuild`).          |
| `pixwel migrate`                    | Run database migrations.                                                 |
| `pixwel karma`                      | Run the UI 2.x tests.                                                    |

## Running the UI

The frontend runs outside Docker:

```bash theme={null}
# Current app (3.x) — Webpack, pnpm
cd ui/3x
pnpm start            # points at staging
pnpm start:dev        # points at your local API

# Legacy app (2.x) — Gulp
cd ui/2x
npx gulp serve        # points at staging
npx gulp serve --dev  # points at your local API
```

<Tip>
  `director` ties it together: `cd director; npm start` runs the API services and the UI concurrently and opens a dashboard of links — the same entry point Codespaces uses.
</Tip>

## See also

* [Architecture](/architecture) — how the API, UI, workers, and services fit together.
* [Services](/services) — the background workers and what each does.
* [Environments](/environments) — staging, production, and how config differs.