> For the complete documentation index, see [llms.txt](https://vladimirkostikov.gitbook.io/laraboom/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vladimirkostikov.gitbook.io/laraboom/getting-started/02-installation.md).

# 2. Installation and Docker

## What comes up

The root `docker-compose.yml` gives you these services:

| Service    | Role                                                     |
| ---------- | -------------------------------------------------------- |
| `nginx`    | HTTP on the `APP_PORT` port (8080 by default)            |
| `php`      | PHP-FPM, `working_dir` equals the selected host          |
| `queue`    | `php boom queue:work`                                    |
| `schedule` | `php boom schedule:work`                                 |
| `mysql`    | MySQL 8.4, host port `DB_PORT` (`.env.example` has 3307) |

The nginx root is `/var/www/${APP_TARGET}/web`.

## Quick start

From the monorepo root:

```bash
cp .env.example .env
docker compose up -d --build
```

Root variables (a fragment of `.env.example`):

```env
APP_TARGET=apps
APP_PORT=8080
DB_PORT=3307
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=secret
DB_ROOT_PASSWORD=root
```

`APP_TARGET` switches the host:

* `apps` is the full Demo tour
* `demos/shop` is the shop
* `demos/blog` is the blog

After changing `APP_TARGET` restart compose so that nginx and php pick up the new `working_dir`.

## New project via Composer

The host skeleton is the `laraboom/apps` package (`type: project`). Same contents as `apps/`.

### From this monorepo (now)

```bash
./bin/create-project my-app
```

The script copies `apps/`, wires `packages/laraboom` as a path repo, installs deps, copies `.env`, generates the key.

Then:

```bash
cd my-app
# fix DB_* in .env
php boom install --fresh
```

Web root: `my-app/web`.

### After Packagist publish

You need two packages:

1. `laraboom/core` from `packages/laraboom` (git tag `v0.1.0`)
2. `laraboom/apps` from `apps/` with `composer.dist.json` as `composer.json`

Prepare the skeleton archive:

```bash
./bin/pack-skeleton
# result: build/laraboom-apps/
```

User install:

```bash
composer create-project laraboom/apps my-app
cd my-app
# DB in .env
php boom install --fresh
```

`post-create-project-cmd` copies `.env` and runs `php boom key`. Sync/migrate/seed is `php boom install --fresh`.

In the monorepo, `apps/composer.json` keeps the path to `../packages/laraboom`. The dist file (`composer.dist.json`) has no path repo, only `laraboom/core: ^0.1` from Packagist.

## Installing host dependencies

In the php container (or locally if PHP and Composer are already there):

```bash
cd apps
composer setup
```

The `setup` script does:

1. `composer install`
2. copies `.env` from `.env.example` if the file is not there yet
3. `php boom install --fresh`

`php boom install` walks a chain. First the application key, then migrate, sync and seed. The full package command may have other steps too, for example `storage:link`.

The manual equivalent:

```bash
composer install
cp .env.example .env   # if needed
php boom key
php boom migrate --force
php boom sync
php boom seed
```

## Database. Mac and Docker

| Where you connect from                 | `DB_HOST`   | `DB_PORT`                              |
| -------------------------------------- | ----------- | -------------------------------------- |
| PHP inside Docker                      | `mysql`     | `3306`                                 |
| Client on the Mac (TablePlus, DBeaver) | `127.0.0.1` | `3307` (as in the root `.env.example`) |

The `php` container in compose already forces `DB_HOST=mysql` and `DB_PORT=3306`. The host `.env` in `apps/` for running outside Docker usually points at `127.0.0.1:3307`.

## Checking that everything is alive

```bash
# from apps/ or docker exec into php
php boom doctor
php boom routes
php boom schema
```

In the browser open `http://127.0.0.1:8080/` (the port from `APP_PORT`).

JSON:

```bash
curl -s http://127.0.0.1:8080/api/demos | head
```

The Demo resource name in the API is `demos`.

## Locally without Docker

You need PHP 8.3+, Composer, MySQL (or SQLite for tests).

1. Bring up MySQL and create the database.
2. Configure `apps/.env`.
3. Run `cd apps && composer setup`.
4. Point the web server document root at `apps/web`.

For day to day development in this repository the Docker stack is more convenient.

## Demo hosts

```bash
# in the root .env
APP_TARGET=demos/shop
```

Then:

```bash
docker compose up -d
docker compose exec php composer setup
```

Shop and blog have their own `composer.json` with a path to `../../packages/laraboom`.

## Useful commands right after installation

```bash
php boom resources          # list of resources
php boom explain demos      # fields, allow, filters, relations, routes
php boom openapi --out=openapi.json
php boom shell              # interactive shell (alias: tinker)
```

## Common problems

If you see a 502 or a blank page, look at the nginx and php logs. Often the host has no `composer install` yet or no `APP_KEY`.

If php cannot connect to MySQL, inside Docker the host must be `mysql`, not `127.0.0.1`. Compose already sets this through the service environment.

If port 8080 is taken, change `APP_PORT` in the root `.env`.

If the schema drifts, run `php boom schema --check` and `php boom sync`. Details in [chapter 6](/laraboom/data-model/06-schema.md).

## Tests

Locally:

```bash
cd packages/laraboom && composer test
cd apps && composer test
cd demos/shop && composer test
cd demos/blog && composer test
```

Next up is [Host and App](/laraboom/getting-started/03-host.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://vladimirkostikov.gitbook.io/laraboom/getting-started/02-installation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.