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

# Build a Laravel app on floo

> Deploy a Laravel app with Postgres, sign-in, a queue, and scheduled commands.

From a Laravel 12 or later project on GitHub (or a fresh `laravel new`) to a live app at `https://<app>.getfloo.app`, with managed Postgres, signed-in users, and your own domain.

New to floo? Start with the [Quickstart](https://getfloo.com/docs/introduction.md).

## What your agent controls

floo builds the `Dockerfile` in your repository. Add one that specifies the runtime for your app:

* The base image, the exact PHP version, and the PHP server (this guide uses FrankenPHP).
* PHP extensions and system packages, such as `pdo_pgsql`, `gd`, `imagick`, or `ffmpeg`, each one install line.
* The build steps, including Composer and the Vite asset build, and the start command.
* More services from the same repository, such as a `queue:work` worker or a [cron job](https://getfloo.com/docs/guides/cron-jobs.md) that runs an Artisan command.

Declare services, managed Postgres, sign-in, and domains in `floo.app.toml`. Store secrets outside git.

## 1. Add a Dockerfile

This walkthrough uses Postgres from the first deploy, because a new Laravel app keeps sessions, cache, and queued jobs in the database.

The Dockerfile builds the Vite assets in a Node stage, then installs Composer dependencies on the [FrankenPHP](https://frankenphp.dev) image:

```dockerfile Dockerfile theme={null}
FROM node:22-slim AS assets
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM dunglas/frankenphp:1-php8.4

RUN install-php-extensions pdo_pgsql intl zip opcache pcntl

COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

WORKDIR /app

COPY composer.json composer.lock ./
RUN composer install --no-dev --no-scripts --no-autoloader --prefer-dist --no-interaction

COPY . .
COPY --from=assets /app/public/build public/build
RUN composer dump-autoload --optimize --no-dev && \
    php artisan package:discover --ansi

ENV APP_ENV=production \
    APP_DEBUG=false \
    LOG_CHANNEL=stderr \
    DB_CONNECTION=pgsql

CMD php artisan optimize && exec frankenphp php-server --listen 0.0.0.0:$PORT --root public/
```

`php artisan optimize` caches config and routes when the container starts, after floo has injected the runtime env vars. Running it at build time would cache an empty config. `DB_CONNECTION=pgsql` makes every deploy, the first one included, migrate Postgres instead of Laravel's default SQLite file. `exec` hands the process to FrankenPHP so it receives shutdown signals.

Add a `.dockerignore` so local files stay out of the image:

```text .dockerignore theme={null}
.env
.git
node_modules
vendor
public/build
storage/logs/*
database/database.sqlite
```

> [!TIP]
>
> Bind to `0.0.0.0` on `$PORT`, not `127.0.0.1` on a fixed port. floo sets `PORT` at runtime and routes only to processes bound to all interfaces. The shell form of `CMD`, without brackets, expands `$PORT`. Do not ship `php artisan serve`: it is the development server.

## 2. Point Laravel at floo's Postgres and proxy

floo injects `DATABASE_URL`. Laravel 12 reads the URL from `DB_URL`, so read either name in `config/database.php`:

```php config/database.php theme={null}
'pgsql' => [
    'driver' => 'pgsql',
    'url' => env('DB_URL', env('DATABASE_URL')),
    // ...keep the rest of the pgsql block as generated
],
```

floo's edge terminates TLS and forwards `X-Forwarded-Proto: https`. Trust it in `bootstrap/app.php`, or Laravel builds `http://` links and Vite asset URLs that browsers block on an `https` page:

```php bootstrap/app.php theme={null}
->withMiddleware(function (Middleware $middleware): void {
    $middleware->trustProxies(at: '*');
})
```

## 3. Initialize the floo config

Install the CLI and sign in: `curl -fsSL https://getfloo.com/install.sh | bash`, then `floo auth login`. An agent can run the same journey over the HTTP API instead, starting from [getfloo.com/agents.md](https://getfloo.com/agents.md).

```bash theme={null}
floo init my-laravel-app
```

For a single-service Laravel app:

```toml floo.app.toml theme={null}
[app]
name = "my-laravel-app"
access_mode = "accounts"

[services.web]
type = "web"
path = "."
port = 8000
ingress = "public"
dev_command = "php artisan serve --host 127.0.0.1 --port 8000"
migrate_command = "php artisan migrate --force"

[services.web.env]
managed = ["postgres"]

[managed.default]
type = "postgres"
```

`access_mode = "accounts"` puts invite-only sign-in in front of the app from the first deploy; see [step 6](#6-read-the-signed-in-user). For a site anyone can open, set `access_mode = "public"`.

`migrate_command` runs as a one-off job with the new image before traffic moves to it. `--force` is required because `APP_ENV` is `production`. A failed migration stops the deploy. Use [expand-then-contract migrations](https://getfloo.com/docs/guides/postgres.md#schema-portability-across-dev-and-prod) to keep the schema compatible with both old and new code.

## 4. Connect the repo and deploy

floo builds from your GitHub repository, not local files, so commit first. `floo deploy` pushes the commit and waits until the dev URL is live. The first time, it stops with one link if the floo GitHub App can't read the repository yet: a human opens it and installs the App on the account that owns the repository, then you run `floo deploy` again. See [Give floo access to your GitHub repository](https://getfloo.com/docs/introduction.md#2-give-floo-access-to-your-github-repository).

Laravel needs `APP_KEY`, and floo sets env vars only on an app that exists. The first `floo deploy` creates the app and its database and runs the migrations. Its pages return a 500 error until `APP_KEY` is set, so set it and rebuild:

```bash theme={null}
git add . && git commit -m "feat: floo config + Dockerfile"
floo deploy --preflight
floo deploy
APP_KEY="base64:$(openssl rand -base64 32)"
echo "$APP_KEY" | floo env set APP_KEY --stdin --secret --app my-laravel-app
floo deploy --rebuild --app my-laravel-app
floo status --wait --app my-laravel-app
```

No GitHub repository? `floo deploy --hosted` has floo host the repository. See [Deploy without GitHub](https://getfloo.com/docs/deploy/without-github.md).

When it's done:

```bash theme={null}
floo apps show my-laravel-app
```

> [!TIP]
>
> **Your Laravel app is live** at `https://my-laravel-app.getfloo.app`, and only people you invite can sign in.
>
> Every `git push origin main` ships to dev.

Dev and prod each get a separate Postgres database and credentials, with no shared state. Need embeddings? Add `CREATE EXTENSION IF NOT EXISTS vector;` in a migration with `DB::statement`. See [Postgres → Vector search](https://getfloo.com/docs/guides/postgres.md#vector-search-with-pgvector).

## 5. Run the queue and scheduled commands

The default `QUEUE_CONNECTION=database` keeps jobs in Postgres, so a worker needs no Redis. Run it as its own service from the same build. A worker takes no deployed HTTP traffic, and its `ingress` defaults to internal. The local `floo dev` runner requires a distinct port in the config even for a worker:

```toml floo.app.toml theme={null}
[services.worker]
type = "worker"
path = "."
command = "php artisan queue:work --tries=3"
dev_command = "php artisan queue:work"
port = 8001

[services.worker.env]
managed = ["postgres"]
```

Keep `[services.web.env]` from step 3: once any service lists its databases, each service gets only the ones it lists. The web service keeps running the migrations, so the worker needs no `migrate_command`.

Commit and push to deploy the worker. `floo env set` stores a value on the service it targets and needs that service to exist, so once the worker is deployed, give it the same `APP_KEY` as the web service and restart dev:

```bash theme={null}
git add floo.app.toml && git commit -m "feat: queue worker" && git push
floo status --wait --app my-laravel-app
echo "$APP_KEY" | floo env set APP_KEY --stdin --secret --service worker --restart --app my-laravel-app
```

Here `$APP_KEY` holds the key you set in step 4; secrets cannot be read back, so keep it in your password manager. With two services, `floo env set` needs `--service` to name the one it targets.

Run Artisan commands on a schedule with a cron job in `floo.app.toml` instead of a `schedule:run` loop. Create the command with `php artisan make:command SendDigest`, give it the signature `app:send-digest`, then schedule it. Each job runs in the web service's image, in UTC:

```toml floo.app.toml theme={null}
[cron.daily-digest]
schedule = "0 8 * * *"
command = "php artisan app:send-digest"
service = "web"
```

See [Cron jobs](https://getfloo.com/docs/guides/cron-jobs.md).

## 6. Read the signed-in user

With `access_mode = "accounts"` from step 3, floo's gateway:

* Redirects unauthenticated requests to a hosted login page.
* Validates the session cookie on every request.
* Injects identity headers into every request that reaches your Laravel app.

Routes and controllers read the headers, with no auth package, callback handlers, or user table to manage. Add `use Illuminate\Http\Request;` at the top of `routes/web.php`, then:

```php routes/web.php theme={null}
Route::get('/me', function (Request $request) {
    $email = $request->header('X-Floo-User-Email');
    abort_unless($email, 401);

    return [
        'email' => $email,
        'id' => $request->header('X-Floo-User-Id'),
        'name' => $request->header('X-Floo-User-Name'),
    ];
});
```

Locally, run `floo dev --fixture-user` (see [section 8](#8-local-development-with-dev-credentials)), which sends the same headers. Access modes and identity headers in full: [App sign-in](https://getfloo.com/docs/guides/app-auth.md).

## 7. Add a custom domain

Declare the domain in `floo.app.toml`:

```toml theme={null}
[domains."app.example.com"]
service = "web"
```

`floo env set` targets dev unless you pass `--env prod`, so prod starts without `APP_KEY`. Give prod its own key on both services before the first release:

Replace `owner/repo` with your GitHub repository. For a floo-hosted project, see [Environments](https://getfloo.com/docs/guides/environments.md#the-flow).

```bash theme={null}
PROD_APP_KEY="base64:$(openssl rand -base64 32)"
echo "$PROD_APP_KEY" | floo env set APP_KEY --stdin --secret --service web --env prod --app my-laravel-app
echo "$PROD_APP_KEY" | floo env set APP_KEY --stdin --secret --service worker --env prod --app my-laravel-app
```

Commit and push, wait for that commit's dev deploy to go live, then release it
to prod and read the DNS records:

```bash theme={null}
gh release create v1 --repo owner/repo
```

Wait for the prod deploy to finish, then read the DNS records:

```bash theme={null}
floo domains show app.example.com --app my-laravel-app
```

Publish the traffic and certificate CNAME records that `show` prints, then watch
activation:

```bash theme={null}
floo domains watch app.example.com --app my-laravel-app
```

With trusted proxies from step 2, Laravel reads the host from `X-Forwarded-Host`. Set `APP_URL` to the domain for links built outside a request, such as in queued mail. DNS setup and troubleshooting: [Custom domains](https://getfloo.com/docs/guides/custom-domains.md).

## 8. Local development with dev credentials

`floo dev` and `floo run` run commands on your machine, so they need PHP 8.4 and Composer installed locally. Install the dependencies and build the assets once:

```bash theme={null}
composer install && npm install && npm run build
```

```bash theme={null}
floo dev --app my-laravel-app
```

Runs `dev_command` locally with `DATABASE_URL` and readable env vars from the app's dev environment: a real connection to your dev Postgres, with no credentials in your shell history. Set `DB_CONNECTION=pgsql` in your local `.env`, since the Dockerfile's value applies only to the image. Write-only secrets such as `APP_KEY` are withheld, so keep the local `APP_KEY` in `.env`. Values floo injects take precedence over `.env`. Prod credentials never reach a local session.

The database exists after the first deploy that declares `[managed.default]`. Before that deploy, `floo dev` starts without `DATABASE_URL`.

To test signed-in flows, add `--fixture-user`:

```bash theme={null}
floo dev --app my-laravel-app --fixture-user you@example.com
```

`floo dev` then puts a proxy in front of each accounts-mode service that injects the same `X-Floo-User-*` headers floo's gateway adds in production. The output table shows the raw service URL and the auth-proxied URL; use the auth-proxied one for any path that reads identity headers.

Run one-off Artisan commands on your machine against the dev database with `floo run`:

```bash theme={null}
floo run --service web -- php artisan db:seed
floo run --service web -- php artisan tinker
```

## Common gotchas

* **`php artisan db:show` prints the database password.** It shows the full connection URL. Keep it out of logs and agent transcripts; use `php artisan migrate:status` to check the database instead.
* **`/healthz` is reserved.** floo's edge intercepts that exact path. Laravel 12's built-in health route is `/up`, which works as is.
* **Bind to `0.0.0.0`.** floo cannot reach `127.0.0.1`.
* **Trust the proxy.** Without `trustProxies(at: '*')`, asset URLs and redirects use `http://` and the page loads without styles.
* **Logs go to stderr.** `LOG_CHANNEL=stderr` sends logs to `floo logs`. The container filesystem is not kept between deploys, so `storage/logs` is not a place to look.
* **File uploads.** The local `storage/app` disk is lost on every deploy. Use [Cloud storage](https://getfloo.com/docs/guides/cloud-storage.md) with Laravel's `s3` disk.

## Next steps

> [card] [App sign-in](https://getfloo.com/docs/guides/app-auth.md)
>
> Identity headers, access policies, and access modes in detail.

> [card] [Cron jobs](https://getfloo.com/docs/guides/cron-jobs.md)
>
> Run Artisan commands on a schedule in the same image.

> [card] [Dockerfiles](https://getfloo.com/docs/guides/dockerfiles.md)
>
> Layer order for fast pushes and recommended multi-stage builds.

> [card] [Production environments](https://getfloo.com/docs/guides/environments.md)
>
> Dev vs prod, promotion, env overrides.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.