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 theDockerfile 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, orffmpeg, 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:workworker or a cron job that runs an Artisan command.
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
2. Point Laravel at floo’s Postgres and proxy
floo injectsDATABASE_URL. Laravel 12 reads the URL from DB_URL, so read either name in config/database.php:
config/database.php
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.
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:
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.CREATE EXTENSION IF NOT EXISTS vector; in a migration with DB::statement. See Postgres → Vector search.
5. Run the queue and scheduled commands
The defaultQUEUE_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
[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:
$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
6. Read the signed-in user
Withaccess_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.
use Illuminate\Http\Request; at the top of routes/web.php, then:
routes/web.php
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 infloo.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.
show prints, then watch
activation:
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:
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:showprints the database password. It shows the full connection URL. Keep it out of logs and agent transcripts; usephp artisan migrate:statusto check the database instead./healthzis 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 reach127.0.0.1. - Trust the proxy. Without
trustProxies(at: '*'), asset URLs and redirects usehttp://and the page loads without styles. - Logs go to stderr.
LOG_CHANNEL=stderrsends logs tofloo logs. The container filesystem is not kept between deploys, sostorage/logsis not a place to look. - File uploads. The local
storage/appdisk is lost on every deploy. Use Cloud storage with Laravel’ss3disk.
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.