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

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 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 image:
Dockerfile
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:
.dockerignore
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:
config/database.php
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:
bootstrap/app.php

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.
For a single-service Laravel app:
floo.app.toml
access_mode = "accounts" puts invite-only sign-in in front of the app from the first deploy; see step 6. 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 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. 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:
No GitHub repository? floo deploy --hosted has floo host the repository. See Deploy without GitHub. When it’s done:
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.

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:
floo.app.toml
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:
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:
floo.app.toml
See Cron jobs.

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:
routes/web.php
Locally, run floo dev --fixture-user (see section 8), which sends the same headers. Access modes and identity headers in full: App sign-in.

7. Add a custom domain

Declare the domain in floo.app.toml:
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.
Commit and push, wait for that commit’s dev deploy to go live, then release it to prod and read the DNS records:
Wait for the prod deploy to finish, then read the DNS records:
Publish the traffic and certificate CNAME records that show prints, then watch activation:
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.

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:
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:
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:

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 with Laravel’s s3 disk.

Next steps

App sign-in

Identity headers, access policies, and access modes in detail.

Cron jobs

Run Artisan commands on a schedule in the same image.

Dockerfiles

Layer order for fast pushes and recommended multi-stage builds.

Production environments

Dev vs prod, promotion, env overrides.