Skip to main content
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.
1

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.
2

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.
3

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

1

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
2

Add the environment file

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

Run the installer

./install.sh
4

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:
ServicePurposeLocal port
appThe PHP API (and web)8080 → 80
mongoPrimary database27017
redisCache + queues6379
elasticsearchSearch index9200
elasticmqLocal SQS-compatible queue9324
workersBackground 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

CommandDoes
pixwel upStart the full stack (recommended).
pixwel stop / pixwel downStop / tear down the stack.
pixwel bashShell inside the API container.
pixwel logsTail application logs.
pixwel dlogsTail Docker logs.
pixwel debugRun 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 migrateRun database migrations.
pixwel karmaRun the UI 2.x tests.

​
Running the UI

The frontend runs outside Docker: 
cd ui
npm start            # 3.x, points at staging
npm run start:dev    # 3.x, points at your local API
npx gulp serve       # 2.x, points at staging
npx gulp serve --dev # 2.x, 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.

​
See also

  • Architecture — how the API, UI, workers, and services fit together.
  • Services — the background workers and what each does.
  • Environments — staging, production, and how config differs.