Key takeaway
- Containerise a Laravel app with a multi-stage Docker build, push the image and run it on Kubernetes with config, probes and scaling, per official docs.
To run Laravel in Docker, build an image that holds your PHP code, its Composer dependencies and a web server pointed at the public directory, push it to a registry, then run it on Kubernetes with a Deployment, a Service and a readiness probe on Laravel's /up health route. Keep configuration outside the image, and keep the image small with a multi-stage build.
This guide walks through that path step by step for engineering leads and platform teams. Every Laravel and Docker claim below comes from the official Laravel deployment docs or Docker build docs. For the cluster itself, see our guide to Kubernetes architecture components.
What do you need before you start?
You need a Kubernetes cluster (Minikube is enough for testing), kubectl, Docker, a Laravel application with its source code, a Dockerfile and an account on a container registry. You also need a PHP version your Laravel release supports, because the base image decides which PHP the application runs on.
Which Laravel and PHP versions should the image use?
Choose the base image from the support policy on the Laravel release notes, read on 13 November 2026. The Laravel 12 page lists the following, and says Laravel 13 is the current major version.
| Laravel version | Supported PHP | Security fixes until |
|---|---|---|
| 11 | 8.2 to 8.4 | March 12th, 2026 |
| 12 | 8.2 to 8.5 | February 24th, 2027 |
| 13 | 8.3 to 8.5 | Q1 2028 (as listed) |
The deployment page also lists the PHP extensions Laravel needs: Ctype, cURL, DOM, Fileinfo, Filter, Hash, Mbstring, OpenSSL, PCRE, PDO, Session, Tokenizer and XML. Check each of them in the image, and confirm tags on the official PHP image page before you pin one.
Should you use Laravel Sail or write your own Dockerfile?
Use both, for different jobs. The Sail documentation describes Sail as a light-weight command-line interface for Laravel's default Docker development environment, built around a compose.yaml file and a sail script. The page presents it for local development. A production image is a separate artefact that you design for size, security and repeatable builds.
| Option | When it fits | Current status |
|---|---|---|
| Laravel Sail | Local development with PHP, MySQL and Redis, no prior Docker experience needed | Installed with new Laravel applications, according to its docs |
| Your own multi-stage Dockerfile | Images you push to a registry and run on Kubernetes | You own the base image, PHP version and patching |
| Laravel Forge or Laravel Cloud | Teams that prefer a managed platform to running a cluster | Described on the Laravel deployment page |
How do you write a Dockerfile for Laravel?
Use a multi-stage build. The Docker multi-stage documentation explains that each FROM starts a new stage and that you copy only the artefacts you need into the final image, so build tools stay out of it. The Docker PHP guide follows the same pattern, with composer:lts for dependencies and a php:8.2-apache runtime stage. The example below is an illustration, not a drop-in file.
# Stage 1: install production dependencies
FROM composer:lts AS deps
WORKDIR /app
COPY . .
RUN composer install --no-dev --no-interaction
# Stage 2: runtime image (pick a PHP tag your Laravel version supports)
FROM php:8.3-apache AS final
RUN docker-php-ext-install pdo pdo_mysql
COPY docker/laravel.conf /etc/apache2/sites-available/000-default.conf
COPY --from=deps /app /var/www/html
RUN chown -R www-data:www-data /var/www/html/storage /var/www/html/bootstrap/cache
Three points matter here. First, Laravel documents that the web server must send all requests to public/index.php, so your laravel.conf virtual host should use the public directory as its document root. Second, Laravel needs to write to storage and bootstrap/cache, which the chown line handles. Third, add a .dockerignore file: Docker says it excludes files that are not relevant to the build, and its PHP guide excludes vendor, node_modules and environment files.
Docker also advises using USER to switch to a non-root user when a service can run without privileges, and warns that image tags are mutable. Pinning to a digest gives identical builds but means you opt out of automated security fixes, so pair it with a tool such as Dependabot. Whether your web server can run unprivileged on port 80 depends on the image, so test it before you adopt it.
How do you build and publish the image?
Build the image, tag it for your registry and push it. Any registry that your cluster can pull from will work; use your registry's own sign-in steps.
docker build -t <registry>/<app>:<version> .
docker login <registry>
docker push <registry>/<app>:<version>
Use an explicit version tag for each release, because a mutable tag such as latest makes it hard to know which build a cluster is running. Our CI/CD pipeline guide covers automating this step.
How should configuration and secrets be handled?
Keep them out of the image. The Laravel configuration docs say the .env file should not be committed to source control, because it can expose credentials, and that any variable in it can be overridden by external environment variables. In Kubernetes, that means supplying values through the environment of the container rather than baking them in.
| Setting | What Laravel documents | Why it matters in a container |
|---|---|---|
APP_DEBUG | Should always be false in production, or sensitive configuration values may be exposed | Set it explicitly in the Deployment |
php artisan optimize | Caches config, events, routes and views; run it as part of deployment | Run it where the real environment variables exist |
config:cache | After caching, .env is not loaded and env() calls outside config files return null | Read env() only inside config files |
env:encrypt | Encrypts .env so the encrypted file can be stored in source control | Keep the decryption key in a secret manager |
How do you deploy the image to Kubernetes?
Describe the application with a Deployment and expose it with a Service. Laravel serves a health route at /up by default, which returns a 200 response if the application has booted without exceptions and a 500 otherwise, so it suits a readiness probe. The example is illustrative; confirm API versions on the Kubernetes documentation for your cluster.
apiVersion: apps/v1
kind: Deployment
metadata:
name: laravel-app
spec:
replicas: 2
selector:
matchLabels:
app: laravel-app
template:
metadata:
labels:
app: laravel-app
spec:
containers:
- name: laravel-app
image: <registry>/<app>:<version>
ports:
- containerPort: 80
env:
- name: APP_DEBUG
value: "false"
readinessProbe:
httpGet:
path: /up
port: 80
---
apiVersion: v1
kind: Service
metadata:
name: laravel-app
spec:
selector:
app: laravel-app
ports:
- port: 80
targetPort: 80
Apply the files with kubectl apply -f, check the pods with kubectl get pods, and reach the application through the Service or an ingress. If the application stores user uploads, do not write them to the container filesystem: use an external object store or a persistent volume claim from your platform. Helm can template these manifests per environment; see our Helm guide.
How do you scale and troubleshoot a Laravel container?
Make the application stateless first, so any replica can serve any request. Then scale with kubectl scale --replicas=3 deployment/laravel-app. Laravel notes that long-running processes such as queue workers need restarting after a deploy and that, outside Laravel Cloud, you need a process monitor to restart them. On Kubernetes, run workers as their own Deployment and replace them with a rolling update.
| Symptom | First check |
|---|---|
| Pod will not start | kubectl describe pod and kubectl logs |
| Pod running but not ready | Does /up return 200? Are PHP extensions and environment values present? |
| 500 errors after a config change | Was config:cache run with the right environment, and is env() used only in config files? |
| Write errors | Can the web server user write to storage and bootstrap/cache? |
| Service unreachable | Do the Service selector and pod labels match? |
What should governance, security and cost look like?
Treat the image as a controlled artefact. Rebuild it regularly with updated dependencies, because Docker notes that images are immutable and that tags can move. Scan it, keep secrets out of it, and record which version runs where. Our container security guide and the Docker container architecture guide cover the wider controls. On cost, small images pull faster and a multi-stage build keeps build tools out of production.
If you also run AI agents next to Laravel services, ElixirClaw is an agentic OS platform to build, orchestrate and govern AI agents and automation workflows while keeping humans in control, and AgentGRC keeps autonomous agent actions inside policy, with the audit trail risk teams need.
When is this the wrong approach?
Kubernetes adds operating cost. If you run one application with modest traffic, the Laravel deployment page describes Laravel Forge, a VPS server management platform, and Laravel Cloud, a managed deployment platform, as simpler routes. Choose a cluster when you already run one, need many services on shared infrastructure, or need rolling updates and self-healing across replicas.
What is a sensible adoption sequence?
| Step | Action | Done when |
|---|---|---|
| 1 | Run the app locally with Sail | The app works in containers |
| 2 | Write a multi-stage production Dockerfile | The image builds with no dev dependencies |
| 3 | Move configuration to environment variables | No .env file in the image |
| 4 | Deploy to a test cluster with the /up probe | Pods become ready |
| 5 | Automate build, push and rollout in CI/CD | A merge produces a tagged release |
| 6 | Add scanning, rebuild schedules and workers | Patching is routine |
To map one decision your agents should make when they touch your Laravel services, and the context and policy it depends on, book a Context Workshop. See what happens in the workshop.
Frequently asked questions
Can I use Laravel Sail in production?
The Laravel Sail documentation describes it as a development tool for Laravel's default Docker environment, and never positions it for production. Build a separate multi-stage image for production.
Which health check should Kubernetes use for Laravel?
Laravel serves a health route at /up by default. It returns a 200 response if the application booted without exceptions and a 500 otherwise, so it suits a readiness probe.
Should the .env file go into the Docker image?
No. Laravel says the .env file should not be committed to source control, and variables can be overridden by external environment variables. Supply values at runtime, or use env:encrypt if you must store the file.
Why does env() return null after config:cache?
Once configuration is cached, the .env file is no longer loaded and env() calls outside config files return null. Read environment values only inside config files.
Do I need Kubernetes to deploy Laravel?
No. Laravel documents Forge and Laravel Cloud as alternatives. Kubernetes fits teams that already run clusters or need many services on shared infrastructure.
How Can XenonStack Help You?
Follow XenonStack on LinkedIn: XenonStack on LinkedIn for new guides on agentic AI, data and platform engineering.
Explore the XenonStack platform family: ElixirData · ElixirClaw · ElixirHub · NexaStack · MetaSecure · Neural AI · AgentGRC · AgentSRE · AgentAnalyst · AgentInstruct · AgentRAI · AgentScrum · AgentSearch · AgentForce · AI Aviator · SAIF Aviator · CohortIQ · XenonStack AI · XenonStack UAE