Deployment And Production

Packaging your app for deployment

In development you mount your code into the container. In production you build it into the image, so the same image runs in staging and production, can't be changed on the server, and rolls back by deploying the previous tag.

Copy your code into the image

Create a Dockerfile in the root of your project:

Dockerfile
FROM serversideup/php:8.5-fpm-nginx

ENV PHP_OPCACHE_ENABLE=1

COPY --chown=www-data:www-data . /var/www/html
  • PHP_OPCACHE_ENABLE=1 turns on OPcache, which is off by default so code edits show up during development. See production performance tuning for what it changes.
  • --chown=www-data:www-data gives the files to the user PHP runs as, so your app can write to directories like storage/. The image already runs as www-data, so you don't need a USER line unless you switch to root earlier in the file.

Build and tag the image with a version you can trace back to a commit:

Terminal
docker build -t my-app:$(git rev-parse --short HEAD) .

Keep files out of the image with .dockerignore

COPY . /var/www/html copies everything in the build context. Add a .dockerignore next to your Dockerfile so local dependencies and secrets stay out:

.dockerignore
.git
.env
node_modules
vendor
public/build

vendor and public/build are excluded because the build creates them, as shown below.

Install dependencies and build assets in the image

A multi-stage build installs Composer dependencies, compiles your front-end assets in a Node image, and copies only the results into the PHP image. Node and node_modules never reach production.

Dockerfile
FROM serversideup/php:8.5-fpm-nginx AS vendor
COPY --chown=www-data:www-data composer.json composer.lock ./
RUN composer install --no-dev --no-interaction --no-autoloader --no-scripts

FROM node:22-alpine AS assets
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
COPY --from=vendor /var/www/html/vendor ./vendor
ARG VITE_APP_NAME
RUN npm run build

FROM serversideup/php:8.5-fpm-nginx

ENV PHP_OPCACHE_ENABLE=1

COPY --chown=www-data:www-data --from=vendor /var/www/html/vendor ./vendor
COPY --chown=www-data:www-data . .
COPY --chown=www-data:www-data --from=assets /app/public/build ./public/build
RUN composer dump-autoload --no-dev --optimize

Composer is included in every image, and the working directory is /var/www/html. Copying composer.json and composer.lock before the rest of your code lets Docker reuse the composer install layer until your dependencies change. composer dump-autoload then runs your Composer scripts, such as Laravel's package:discover, once the code is in place.

The assets stage gets a copy of vendor because some front-end builds import files from it, such as the CSS for Livewire's Flux components.

Vite builds VITE_* values into your JavaScript, and .env isn't in the build context. Declare each one with ARG in the assets stage and pass it at build time:

Terminal
docker build --build-arg VITE_APP_NAME="My App" -t my-app:$(git rev-parse --short HEAD) .

These values end up in public JavaScript, so never pass a secret this way.

If you need extra PHP extensions, switch to root to install them and switch back before you copy your code. See installing additional PHP extensions.

Pass secrets when the container starts

Don't put secrets in the image with ENV or by copying .env. Anyone who can pull the image can read them. Provide them as environment variables or secrets from your orchestrator when the container starts.

Test the image locally

Run the image you built, without a volume, to check that everything it needs is inside it:

compose.prod.yml
services:
  php:
    image: my-app:1.0.0
    ports:
      - 80:8080
Terminal
docker build -t my-app:1.0.0 .
docker compose -f compose.prod.yml up

Run it in production

The image runs the same way under Docker Compose, Docker Swarm, or Kubernetes. If you want a tool that sets up servers, Swarm, and zero-downtime deployments for these images, see Spin.

Next, configure SSL for your domain.