Local setup

Getting a Core checkout running on your machine.

This is the development environment — a checkout you can run and change. For installing FaPost on a server, see Self-hosting instead; the two have different goals and different trade-offs.

There are two ways to start. Docker gives you a runtime that matches production; a local install is faster if you already run PHP that way.

With Docker

Nothing to install but Docker itself.

git clone [e-mail]:fapost-lab/core.git && cd core
cp .env.example .env
cd docker && make dev

That builds a development image from the same base as the production one, mounts your working tree, and starts PostgreSQL, Redis, Horizon, the scheduler and Vite. Edits take effect immediately — no rebuild.

make dev          # build and start; add INSTALL_XDEBUG=1 to include Xdebug
make dev-shell    # a shell inside the application container
make dev-test     # run the suite there
make dev-down     # stop

The application is on http://localhost:8000, Vite on http://localhost:5173.

Why the dev image shares the production base

The development image is the dev target of docker/Dockerfile, built from the same base stage as the production one. That is deliberate: a separately assembled development image would have its own PHP build and extension set, and every difference between the two becomes a bug that only appears after deployment.

What does differ is only what should:

• dev Composer dependencies are installed
• the source is mounted rather than copied, so edits are live
• opcache.validate_timestamps=1, or nothing you type would take effect
• the container runs as your user id, so files it writes stay yours
• Xdebug is available, off unless the image is built with INSTALL_XDEBUG=1

vendor/ and node_modules/ are deliberately not mounted from the host. They are installed inside the container for its own platform, and sharing them would mix binaries built for a different OS.

Xdebug

INSTALL_XDEBUG=1 make dev

Step debugging is trigger-based, so it costs nothing until you ask for it. The callback address defaults to host.docker.internal, which resolves on Linux too because compose maps it to the host gateway. If your IDE is elsewhere:

XDEBUG_CLIENT_HOST=192.168.1.50

On your own machine

Requirements:

• PHP 8.4 or newer
• Composer 2
• Node.js 20+ and npm
• PostgreSQL 15+ or compatible
• Redis
• PHP extensions: pdo_pgsql, redis, intl, bcmath, gd, zip, plus pcntl and posix for Horizon

Check them all at once:

./deploy/install.sh --check-only

1. Install dependencies

   composer install
   composer run hooks:install
   npm install
   
2. Prepare the environment

   cp .env.example .env
   php artisan key:generate
   

   .env.example ships the credentials the Docker stack creates for itself, so that path works unedited. Running against services you provisioned yourself means pointing these at them:

   DB_CONNECTION=pgsql
   DB_HOST=127.0.0.1
   DB_PORT=5432
   DB_DATABASE=fapost_core
   DB_USERNAME=fapost
   DB_PASSWORD=secret
   
   REDIS_HOST=127.0.0.1
   REDIS_PORT=6379
   REDIS_PASSWORD=secret
   

   If your Redis runs without requirepass, set REDIS_PASSWORD=null rather than leaving it empty — Laravel reads the literal null as “no password”, and an empty string is a password of zero length.

3. Migrate and run

   php artisan migrate
   composer run dev
   

   composer run dev starts the Laravel dev server, the queue listener, pail log tailing, and the Vite dev server together.

Checks

composer test
composer run test:arch
vendor/bin/pint --dirty --format agent

See Testing and architecture checks for what each covers.

Running it like production

To exercise the actual production images locally, follow Docker Compose. Same topology, different images — useful for reproducing something that only happens with a compiled config cache and no dev dependencies.