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

# Local setup

> Getting a Core checkout running on your machine.

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.

```bash theme={"theme":"one-dark-pro"}
git clone git@github.com: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.

```bash theme={"theme":"one-dark-pro"}
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`

<Note>
  `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.
</Note>

### Xdebug

```bash theme={"theme":"one-dark-pro"}
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:

```dotenv theme={"theme":"one-dark-pro"}
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:

```bash theme={"theme":"one-dark-pro"}
./deploy/install.sh --check-only
```

<Steps>
  <Step title="Install dependencies">
    ```bash theme={"theme":"one-dark-pro"}
    composer install
    composer run hooks:install
    npm install
    ```
  </Step>

  <Step title="Prepare the environment">
    ```bash theme={"theme":"one-dark-pro"}
    cp .env.example .env
    php artisan key:generate
    ```

    Then check the database settings:

    ```dotenv theme={"theme":"one-dark-pro"}
    DB_CONNECTION=pgsql
    DB_HOST=127.0.0.1
    DB_PORT=5432
    DB_DATABASE=fapost_core
    DB_USERNAME=root
    DB_PASSWORD=
    ```
  </Step>

  <Step title="Migrate and run">
    ```bash theme={"theme":"one-dark-pro"}
    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.
  </Step>
</Steps>

## Checks

```bash theme={"theme":"one-dark-pro"}
composer test
composer run test:arch
vendor/bin/pint --dirty --format agent
```

See [Testing and architecture checks](/contributing/testing) for what each covers.

## Running it like production

To exercise the actual production images locally, follow
[Docker Compose](/self-hosting/docker-compose). Same topology, different images —
useful for reproducing something that only happens with a compiled config cache
and no dev dependencies.