Skip to main content
XenonStack

DevOps

XenonStack Blog Laravel Docker: Build and Deploy on Kubernetes

and | Published | Updated

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 versionSupported PHPSecurity fixes until
118.2 to 8.4March 12th, 2026
128.2 to 8.5February 24th, 2027
138.3 to 8.5Q1 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.

OptionWhen it fitsCurrent status
Laravel SailLocal development with PHP, MySQL and Redis, no prior Docker experience neededInstalled with new Laravel applications, according to its docs
Your own multi-stage DockerfileImages you push to a registry and run on KubernetesYou own the base image, PHP version and patching
Laravel Forge or Laravel CloudTeams that prefer a managed platform to running a clusterDescribed 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.

Two columns: build steps (Composer stage, runtime stage, registry push, no .env in image) mapped to Kubernetes controls (Deployment, readiness probe on /up, Service, environment values).
# 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.

SettingWhat Laravel documentsWhy it matters in a container
APP_DEBUGShould always be false in production, or sensitive configuration values may be exposedSet it explicitly in the Deployment
php artisan optimizeCaches config, events, routes and views; run it as part of deploymentRun it where the real environment variables exist
config:cacheAfter caching, .env is not loaded and env() calls outside config files return nullRead env() only inside config files
env:encryptEncrypts .env so the encrypted file can be stored in source controlKeep 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.

SymptomFirst check
Pod will not startkubectl describe pod and kubectl logs
Pod running but not readyDoes /up return 200? Are PHP extensions and environment values present?
500 errors after a config changeWas config:cache run with the right environment, and is env() used only in config files?
Write errorsCan the web server user write to storage and bootstrap/cache?
Service unreachableDo 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?

StepActionDone when
1Run the app locally with SailThe app works in containers
2Write a multi-stage production DockerfileThe image builds with no dev dependencies
3Move configuration to environment variablesNo .env file in the image
4Deploy to a test cluster with the /up probePods become ready
5Automate build, push and rollout in CI/CDA merge produces a tagged release
6Add scanning, rebuild schedules and workersPatching 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.

Table of Contents

navdeep-singh-gill

Navdeep Singh Gill

Global CEO and Founder of XenonStack

LinkedIn profile

Navdeep Singh Gill is serving as Chief Executive Officer and Product Architect at XenonStack. He holds expertise in building SaaS Platform for Decentralised Big Data management and Governance, AI Marketplace for Operationalising and Scaling. His incredible experience in AI Technologies and Big Data Engineering thrills him to write about different use cases and its approach to solutions.

Get the latest articles in your inbox

Subscribe Now

Interested in solving your challenges with the XenonStack team?
Get Started

Tell us about you and your priorities so we can prepare the right conversation. It takes about 2 minutes.

Please Select your Industry
Banking
Fintech
Payment Providers
Wealth Management
Discrete Manufacturing
Semiconductor
Machinery Manufacturing / Automation
Appliances / Electrical / Electronics
Elevator Manufacturing
Defense & Space Manufacturing
Computers & Electronics / Industrial Machinery
Motor Vehicle Manufacturing
Food and Beverages
Distillery & Wines
Beverages
Shipping
Logistics
Mobility (EV / Public Transport)
Energy & Utilities
Hospitality
Digital Gaming Platforms
SportsTech with AI
Public Safety - Explosives
Public Safety - Firefighting
Public Safety - Surveillance
Public Safety - Others
Media Platforms
City Operations
Airlines & Aviation
Defense Warfare & Drones
Robotics Engineering
Drones Manufacturing
AI Labs for Colleges
AI MSP / Quantum / AGI Institutes
Retail Apparel and Fashion

Continue