# Deploy Laravel Self-Hosted: Docker, Health Checks, Rollback

> Deploy a Laravel 13 app to your own server from git with no Dockerfile. Real output for the PHP constraint, APP_KEY, the health route and a rollback.

Canonical URL: https://levelrail.com/blog/deploy-laravel-self-hosted/

By the end of this guide a Laravel 13 app runs in Docker on your own machine or server, built from git without a Dockerfile, checked by a health route, with its `APP_KEY` stored as a secret and one rollback rehearsed. The tool is [Levelrail](https://github.com/glincker/levelrail), a self-hosted deploy platform. Install it first with [the five minute install](https://levelrail.com/blog/install-levelrail-five-minutes/). You also need a Laravel repo on a git host the server can reach.

I ran every step below on Levelrail v1.5.7 and pasted the real output.

## Deploy Laravel self-hosted: the short version

| Step | What you do | Checkpoint |
| --- | --- | --- |
| 1 | Pin the PHP version in `composer.json` and refresh the lockfile | build uses the PHP you chose |
| 2 | Add a cheap health route | `/healthz` is committed |
| 3 | Create the app with the `laravel` preset and `APP_KEY` as a secret | deploy reports `healthy` |
| 4 | Hit the health route and read logs | `{"ok":true}` |
| 5 | Roll back to the last good deploy | the old release serves again |

## Step 1: create a small Laravel app and pin PHP

Laravel deploys go best when the version you develop on is the version you ship. The preset does not need a Dockerfile, so the only inputs are your repo, your lockfile and a few settings. That makes the lockfile the source of truth, and it is worth a minute of care before the first deploy.

I used the stock skeleton, made with the Composer image so nothing was installed on the host:

```bash
docker run --rm -v $PWD:/w -w /w composer:2 create-project laravel/laravel app
```

That gave Laravel 13. The platform reads the `php` constraint in `composer.json` and builds with a PHP that satisfies it, so state the version you want and make the lockfile agree. Set `"php": "^8.4"` and refresh the lock:

```bash
# composer.json: "php": "^8.4"
docker run --rm -v $PWD:/w -w /w composer:2 update --lock --no-interaction --no-scripts
```

Commit both files. The build then ran FrankenPHP on PHP 8.4.28. Keeping the constraint in line with the PHP your lockfile was resolved on puts your local machine, CI and the server on the same version, which is worth doing for any Laravel project.

Checkpoint: `composer.json` and `composer.lock` are committed, and the constraint matches the PHP in the Composer image you used.

## Step 2: add a health route

Laravel already answers `/up`. I added a route that returns JSON so the check proves PHP ran your code:

```php
// routes/web.php
Route::get('/healthz', fn () => response()->json(['ok' => true]));
```

Keep it free of database calls. A readiness check that depends on the database marks the whole app unready for reasons your release did not cause.

Checkpoint: the route is committed to the branch you will deploy.

## Step 3: create the app

Creating an app does four things in one command. It registers the repo, selects the preset, stores the secret and starts the first build. Nothing about the key touches git, so the same repo can feed a staging app and a production app with different keys.

Levelrail has a framework preset for Laravel. List the presets with `levelrail-cli build frameworks`. The Laravel line reads `railpack  port 80  health /up`. Generate a key and pass it as a secret:

```bash
KEY=$(docker run --rm php:8.3-cli php -r 'echo "base64:".base64_encode(random_bytes(32));')

levelrail-cli apps create \
  --name laravel-demo \
  --repo YOUR_REPO_URL \
  --ref main \
  --framework laravel \
  --image-repo laravel-demo \
  --secret APP_KEY=$KEY
```

```text
app "laravel-demo" created, building from YOUR_REPO_URL (ref main)...
follow it with "apps deploys wait laravel-demo"
attaching 1 volume(s)...
app "laravel-demo" created
name:     laravel-demo
image:    laravel-demo:pending
port:     80
volume:   storage -> /app/storage
```

The preset also mounted a volume at `/app/storage`, so uploads and compiled views survive a redeploy. Wait for the deploy:

```bash
levelrail-cli apps deploys wait laravel-demo
```

```text
deploy dep_Q5tg5WmfbVFf of "laravel-demo": healthy
```

`--timeout` sets how long it waits. Its default is 10 minutes. If you want to see what the platform finds in your repo first, `levelrail-cli apps detect .` reads files only and reports the language and port. Pass `--framework laravel` so the Laravel preset applies.

Checkpoint: the deploy reports `healthy`.

## Step 4: hit the health route and read logs

With the deploy healthy, confirm the app from the outside. The network command tells you which host port the container maps to, and a plain curl does the rest. Do this once by hand before you wire up a domain, so you know the app itself answers.

```bash
levelrail-cli apps network laravel-demo
```

```text
container port:  80
host port:       56932
running:         true
```

```bash
curl -s http://127.0.0.1:56932/healthz
```

```text
{"ok":true}
```

`/up` and `/` both returned 200. Logs come from `apps logs`:

```bash
levelrail-cli apps logs laravel-demo
```

The output is FrankenPHP's own JSON, including a line like `FrankenPHP started` with `"php_version":"8.4.28"`, which confirms the version you pinned in step 1. To read the platform's view of any deploy, use `apps deploys show` and `apps deploys logs <deploy-id>`.

Checkpoint: `/healthz` returns `{"ok":true}` and the log shows the PHP version you chose.

## Step 5: roll back a Laravel deploy

Rolling back is the safety net that lets you ship on a Friday. Each successful deploy keeps its image, so going back is a redeploy of something that already ran, not a rebuild. That makes it quick and predictable.

A rollback needs two deploys. I deployed a second image that added `public/release.txt`, confirmed it served, then rolled back:

```bash
levelrail-cli apps deploys list laravel-demo
levelrail-cli apps deploys rollback-to laravel-demo dep_Q5tg5WmfbVFf
```

```text
image:    levelrail-rollback/laravel-demo:dep_Q5tg5WmfbVFf@sha256:32226e8b61f46aa2e783da19d67d66b2dfeea65b7efb953a018a4ed2eecfa1a9
port:     80
volume:   storage -> /app/storage
deploy dep_iJZFa5Y_4rS7 of "laravel-demo": healthy
```

After it, `/release.txt` returned 404 and `/healthz` returned `{"ok":true}`. Levelrail pins each previous image under a `levelrail-rollback/` name, by digest, so the rollback redeploys exactly what ran before. More on that in [zero downtime deploys for Docker apps](https://levelrail.com/blog/zero-downtime-deploy-docker-rollback/). For rolling out PHP security fixes the same way, see [shipping a PHP security update](https://levelrail.com/blog/ship-php-security-update-docker-zero-downtime/).

Checkpoint: the file added in the second release returns 404 again, and the health route still answers.

Between them, these five steps are the whole loop for a Laravel app: pin, check, create, verify and go back. Once you have run them once, a normal release is a commit, a build and a wait.

## Quick reference

| Task | Command |
| --- | --- |
| See what the platform detects | `levelrail-cli apps detect .` |
| Watch a deploy finish | `levelrail-cli apps deploys wait laravel-demo` |
| Find the port | `levelrail-cli apps network laravel-demo` |
| Read container logs | `levelrail-cli apps logs laravel-demo` |
| Return to a good release | `levelrail-cli apps deploys rollback-to laravel-demo <deploy-id>` |

## Next steps

The repo in this guide came from a local git server, so deploys were triggered by hand. To deploy on every push, connect a git provider and use push trigger mode. For secrets beyond `APP_KEY`, read [managing secrets for Docker apps](https://levelrail.com/blog/manage-secrets-self-hosted-docker/).

## FAQ

### Do I need a Dockerfile for Laravel?

No. The Laravel preset builds from git with Railpack and runs FrankenPHP on port 80.

### Where does APP_KEY go?

In the secret store, with `--secret` at create time. Keep it out of the repo.

### Which PHP version does the build use?

The one your `composer.json` constraint allows. Set `php` to `^8.4`, run `composer update --lock`, and the build ran PHP 8.4.28.

### Does the health route need the database?

No. Keep it cheap, and let it prove only that PHP can answer a request.

Levelrail is open source under Apache 2.0. What would you deploy next, a queue worker or a second Laravel app? If this saved you time, a star on [the repo](https://github.com/glincker/levelrail) helps other self-hosters find it.

## Frequently asked questions

### Do I need a Dockerfile for Laravel?

No. The Laravel preset builds from git with Railpack, which runs FrankenPHP on port 80. Add a Dockerfile only if you need to control the image.

### Where does APP_KEY go?

In the secret store, passed with --secret at create time. It never goes in the repo or in app.yaml.

### Which PHP version does the build use?

The one your composer.json constraint allows. Set php to ^8.4, run composer update --lock, and the build ran FrankenPHP on PHP 8.4.28.

### Does the health route need the database?

No. Keep it cheap. Laravel already ships /up, and a plain JSON route proves PHP can answer.
