Install
Markdown
Ask AI
Share

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.

Markdown
Ask AI
Share

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, a self-hosted deploy platform. Install it first with the five minute install. 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#

StepWhat you doCheckpoint
1Pin the PHP version in composer.json and refresh the lockfilebuild uses the PHP you chose
2Add a cheap health route/healthz is committed
3Create the app with the laravel preset and APP_KEY as a secretdeploy reports healthy
4Hit the health route and read logs{"ok":true}
5Roll back to the last good deploythe 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
output
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
output
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
output
container port:  80
host port:       56932
running:         true
bash
curl -s http://127.0.0.1:56932/healthz
output
{"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
output
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. For rolling out PHP security fixes the same way, see shipping a PHP security update.

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#

TaskCommand
See what the platform detectslevelrail-cli apps detect .
Watch a deploy finishlevelrail-cli apps deploys wait laravel-demo
Find the portlevelrail-cli apps network laravel-demo
Read container logslevelrail-cli apps logs laravel-demo
Return to a good releaselevelrail-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.

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

Next steps

Keep reading

Zero downtime, with a way back Zero downtime, with a way back

explainer 5 min read

Zero Downtime Deploy for Docker Apps, With Rollback

How a Docker deploy waits for readiness before cutover, holds the previous release for rollback, rolls back on its own, and how to rehearse it.

  • Docker
  • Deployments
  • Rollback