# Dockerize a Filament App

Yes. An agent writes a multi-stage Dockerfile and compose file for your Filament app from what its CI needs, boots the admin panel in a container, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/dockerize-app/filament/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads what the image has to carry before it writes it. In an app like filamentphp/demo, `composer.json` asks for `php ^8.1` but both workflows in `.github/workflows` set up PHP 8.4, and the Laravel Boost guidelines in `CLAUDE.md` name 8.4 too, so that is the runtime. `tests.yml` is the clearest list of what the app needs: PHP with `mbstring`, `pdo` and `pdo_sqlite`, Node 20 for `npm ci && npm run build`, a copied `.env.example`, `php artisan key:generate`, a `touch database/database.sqlite`, and `composer test:pest`, which `composer.json` defines as `pest --parallel`. `.env.example` sets `DB_CONNECTION=sqlite`, `CACHE_DRIVER=file`, `SESSION_DRIVER=file` and `QUEUE_CONNECTION=sync`, so the app needs no database server and no queue worker to run. `vite.config.js` builds `app.css`, `app.js` and the Filament admin theme with Tailwind 4, and `laravel/octane` is already in `require`, with `config/octane.php` defaulting `OCTANE_SERVER` to `roadrunner` and `.gitignore` already listing FrankenPHP's files.

From that it writes a three-stage `Dockerfile`. A Node 20 stage runs `npm ci` and `npm run build` so the hashed assets land in `public/build`. A Composer stage runs `composer install --no-dev --prefer-dist --optimize-autoloader --no-scripts` against `composer.lock`, then runs `php artisan package:discover` and `php artisan filament:upgrade` itself, the two commands the `post-autoload-dump` script would have run, once the application code is copied in. The runtime stage starts from a PHP 8.4 image, installs the extensions `composer check-platform-reqs` lists plus `pdo_sqlite` and the image library the media library's conversions use, copies `vendor/` and `public/build` from the earlier stages, and ships no Node, Composer or dev dependency. Because Octane is already installed, the agent serves the app with `php artisan octane:start --server=frankenphp --host=0.0.0.0` from a FrankenPHP base image, and says in the pull request what to change for `php-fpm` behind nginx instead.

A small entrypoint does on first boot what `composer setup` does on a laptop: it creates `database/database.sqlite` when it is missing, runs `php artisan migrate --force`, runs `php artisan db:seed` only when `SEED=1` because the seeders in `database/seeders` load demo data and local images, and runs `php artisan storage:link` so the media library's public disk is reachable. `compose.yaml` has one `app` service on port 8000 with `APP_KEY` passed from the environment, and two named volumes, one for `storage/` and one for `database/`, so uploads and the SQLite file survive a rebuild. A `.dockerignore` keeps `vendor/`, `node_modules/`, `.env`, `storage/logs` and `public/build` out of the build context.

Then it proves the thing boots. The sandbox has no Docker preinstalled, so the agent installs it with `sudo apt-get install -y docker.io`, starts `dockerd`, and uses `docker-compose` v1 from that package set, since Compose v2 is not in it. It builds the image, starts the stack with `SEED=1`, opens the `/admin` login page in the sandbox's browser, signs in with the `admin@filamentphp.com` account the README documents, takes a screenshot of the dashboard with its seeded widgets, and uploads a product image to show the storage volume works. On the host checkout it runs `composer test:pest` and `composer test:phpstan` too, so the pull request shows no PHP file changed behaviour.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Dockerize this Filament app. Read composer.json, composer.lock, package.json, vite.config.js, .env.example, config/octane.php, the workflows in .github/workflows and the README first, and take the PHP version from CI rather than the composer floor. Write a multi-stage Dockerfile: a Node stage that builds the Vite assets, a Composer stage that installs production dependencies and then runs the package:discover and filament:upgrade commands from the post-autoload-dump script, and a PHP runtime stage with the extensions composer check-platform-reqs lists plus pdo_sqlite and the image library the media library needs. Serve with Octane on FrankenPHP since Octane is already installed, and explain the php-fpm alternative in the PR. Add an entrypoint that creates the SQLite file, migrates, seeds only when SEED=1 and runs storage:link; a compose.yaml with named volumes for storage and the database and APP_KEY from the environment; and a .dockerignore. Install Docker in the sandbox, build and start the stack, log in to /admin with the account the README documents, screenshot the dashboard, run composer test:pest and composer test:phpstan, and open a pull request with the commands and the screenshot.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch with `Dockerfile`, `compose.yaml`, `.dockerignore`, `docker/entrypoint.sh` and a Docker section in the README. No PHP, Blade or JavaScript file changes. The description lists each choice and the file it came from: PHP 8.4 from `tests.yml`, the extensions from `composer check-platform-reqs`, SQLite from `.env.example`, FrankenPHP from the Octane dependency already in `composer.json`, and the two volumes from where the media library and the database write.

The record is in the transcript at `GET /o/{org}/sessions/{id}/messages`: the Docker install, each `docker build` including any attempt that failed before a fix, the container logs with the migration and seed output, the browser login and the dashboard screenshot, the image size from `docker image ls`, and the Pest and PHPStan runs. The repository's own `tests` and `phpstan` workflows run on the pull request as before, since the application code is unchanged.

Before merging, a reviewer checks that `APP_KEY` comes from a secret and not the compose file, that the `storage/` volume is backed up wherever the container runs, and whether production should use MySQL or Postgres rather than the SQLite file, which the README's `composer setup` flow and CI both use. One follow-up message to the same session adds a database service and the `DB_*` variables if so.

## Run it on every new Laravel service without a Dockerfile

A developer starts one run from the terminal with this prompt and the repository when a service needs to run somewhere other than a laptop, and gets the pull request back with the screenshot of the panel served from the container. The sandbox parks when the turn ends, so a follow-up that swaps SQLite for Postgres wakes it with the image already built.

A platform team can send one `POST /o/{org}/sessions` per repository. `GET /o/{org}/github` lists the repositories the Rush GitHub App installation reaches, and a script starts a run only where no `Dockerfile` exists. Each run reads that app's own CI, extensions and drivers, so two Filament apps get two different Dockerfiles.

## Why run it on Rush?

A Dockerfile copied from a blog post fails on the first extension the media library needs or the first Octane flag that does not match the server. The agent reads the workflows, `composer.json` and the environment file, runs `composer check-platform-reqs` against the real lock file, and then installs Docker in its own sandbox and builds the image until the admin panel loads with seeded data, which is the only test that matters for this job.

The pull request carries its own proof: the build log, the container logs, the browser screenshot of the dashboard and the Pest run are in the transcript beside the commands that produced them. Several repositories can be handled at once, each in its own sandbox with its own Docker daemon.

## Frequently asked questions

### Why FrankenPHP and Octane rather than php-fpm and nginx?

Because `laravel/octane` is already in the app's `require` and `.gitignore` already lists FrankenPHP's files, so the team has run it that way before. The pull request explains the `php-fpm` variant with nginx in front for teams that prefer it, and the entrypoint and volumes are the same either way.

### Does the image seed the demo data?

Only when `SEED=1` is set, because the seeders load demo records and local images that a production deployment does not want. The entrypoint always migrates and links storage; seeding is a one-time choice the README documents.

### Is SQLite the right database in a container?

It is what `.env.example`, `composer setup` and CI use, so the first image matches how the app is tested today, with the file on a named volume so it survives a rebuild. For MySQL or Postgres, a follow-up adds the service and the `DB_*` variables; the `pdo_mysql` or `pdo_pgsql` extension is the only image change.

### Will dev dependencies end up in the image?

No. The Composer stage installs with `--no-dev`, the Node stage exists only to build `public/build`, and the runtime stage copies `vendor/` and the built assets from them. Pest, PHPStan, Pint, Rector and Sail stay out, and the `.dockerignore` keeps a local `vendor/` and `node_modules/` out of the build context.

## More Filament jobs

- [Upgrade Filament and Composer Dependencies](https://getrush.ai/run/upgrade-composer-dependencies/filament/)
- [Write Tests for a Filament Admin Panel](https://getrush.ai/run/write-filament-tests/filament/)
- [Add an Audit Log to a Filament Admin Panel](https://getrush.ai/run/add-audit-log/filament/)

## The same job on other stacks

- [Dockerize a Gin API](https://getrush.ai/run/dockerize-app/gin/)
- [Dockerize a Hono App Running on Bun](https://getrush.ai/run/dockerize-app/hono/)
- [Dockerize a Ktor Server](https://getrush.ai/run/dockerize-app/ktor/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
