Local Development - Pixwel Platform

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.

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.

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.

Start the stack

Run cd director; npm start. A dashboard opens with links to each running service.

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
Node.js
AWS CLI, configured with credentials
Linux only: raise the ElasticSearch mmap limit — sysctl -w vm.max_map_count=262144 (persist it in /etc/sysctl.conf)

Install

Clone and link the CLI

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

Add the environment file

Obtain development.env and place it inside docker/, then export your GitHub packages token:

export NPM_TOKEN=xxx

Run the installer

./install.sh

Bring the stack up

pixwel up

The API is served at http://localhost:8080.

Load data

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

# 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.
`pixwel kahlan [--debug] [--watch]`	Run the API specs (Kahlan).
`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:

# 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

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.

​Codespaces (one-click)

​Local Docker setup

​Prerequisites

​Install

​Load data

​What’s in the stack

​Common commands

​Running the UI

​See also

Codespaces (one-click)

Local Docker setup

Prerequisites

Install

Load data

What’s in the stack

Common commands

Running the UI

See also