[3.x] Laravel Sail "quick setup" + Multi-Stage Deployment strategy

[iksaku]

While Laravel Sail provides its own set of runtimes, it is fairly easy to also use with the new v3.x images.

Setup is pretty quick and doesn't need the developer to blow their project with files, nor give up customization. Below are the steps I used:

1. The Dockerfile

We'll need to create a Dockerfile, which can be placed inside the docker/ directory that sail creates by default, or even in the root of the project. We'll pull the serversideup/php image we prefer and create a sail user for the container:

FROM ghcr.io/serversideup/php:8.2-cli

# We will later modify the docker-compose.yml to pass these as arguments.
# They represent the host machine user's uid and gid respectively.
ARG WWWUSER
ARG WWWGROUP

# As the image defaults to unprivileged www-data user, we need to quickly switch to root
USER root

# 1. To keep permissions in check, we modify default www-data IDs
# 2. Sail expects a sail user to exist, we can just bind it to www-data IDs
#    Note: We create a /home/sail directory for tinker to work, otherwise psysh will fail
RUN usermod -ou $WWWUSER www-data \
    && groupmod -og $WWWGROUP www-data \
    && useradd -mNo -g www-data -u $(id -u www-data) sail

# Remember to switch back to unprivileged.
# Note: sail user will be sharing IDs with www-data, so "whoami" will always output "www-data"
USER www-data

CMD ["php", "artisan", "serve", "--host=0.0.0.0", "--port=8080"]

Tip

Check out the man page for useradd: https://linux.die.net/man/8/useradd

If using Alpine, we need to install bash as it is the shell that Sail defaults to:

FROM ghcr.io/serversideup/php:8.2-cli-alpine

ARG WWWUSER
ARG WWWGROUP

USER root

RUN set -eux \
    && apk add --no-cache bash \
    && usermod -ou $WWWUSER www-data \
    && groupmod -og $WWWGROUP www-data \
    && useradd -mNo -g www-data -u $(id -u www-data) sail

USER www-data

CMD ["php", "artisan", "serve", "--host=0.0.0.0", "--port=8080"]

If you know of a way to redirect bash to sh or ash, please let me know!

2. Updating the docker-compose.yml file

For simplicity, the Dockerfile will be considered to be in the root of the project, so need to change the container's build context:

services:
    laravel.test:
        build:
-           context: ./vendor/laravel/sail/runtimes/8.2
+           context: . 

By default, WWWGROUP is already part of build arguments, and WWWUSER only as environment variable, so we just need to move WWWUSER to be and argument instead.

services:
    laravel.test:
        build:
            context: . 
            args:
+               WWWUSER: '${WWWUSER}'
                WWWGROUP: '${WWWGROUP}'
#       ...
        envrionment:
-           WWWUSER: '${WWWUSER}'
#            ...

These changes should be enough to get Sail working with the project 🎉

---

If you're like me and you're looking to reuse the images for production, then we can make use of multi-stage builds to build a base image, a sail image for development and (optionally) a production-ready image.

Depending on your use case, you can have the production-ready image be the base image and manually mount the project directory, or pack the whole project into a single image and deploy to platforms like Fly, Render, Railways or any other hosting provider that can manage containers.

In this case, I'm deploying my project already packed in a container, and my Dockerfile looks like this:

FROM ghcr.io/serversideup/php:8.2-cli-alpine AS base

USER root

RUN set -eux && install-php-extensions intl

USER www-data

CMD ["php", "artisan", "serve", "--host=0.0.0.0", "--port=8080"]

##############################################################################

FROM base AS development

ARG WWWUSER
ARG WWWGROUP

USER root

RUN usermod -ou $WWWUSER www-data \
    && groupmod -og $WWWGROUP www-data \
    && useradd -mNo -g www-data -u $(id -u www-data) sail

USER www-data

##############################################################################

FROM node:18-alpine AS assets
# ...

##############################################################################

FROM base AS production

# Again, this is not to mess with permissions
COPY --chown=www-data:www-data . /var/www/html

RUN composer install --optimize-autoloader --no-dev

RUN sed -i 's/protected \$proxies/protected \$proxies = "*"/g' app/Http/Middleware/TrustProxies.php

COPY --from=assets /app/public/build /var/www/html/public/build

You must not forget to set the build.target property in your docker-compose.yml file:

services:
    laravel.test:
        build:
            context: .
+           target: development
# ...

---

I hope this proves useful and hopefully makes it into documentation, although built-in support for sail would be best, but with such a huge rewrite that 3.x is, I think you have enough stuff to do before 😅

Please let me know if anyone has any questions or suggestions regarding Sail support 😄

Changelog

• 2024-04-24: Align example with new "unprivileged" image system.
• 2024-05-31: v3 is out of beta 🎉

[jaydrogers]

Thank you very much for submitting this! I'll definitely review this and tee this up to get into the docs once I get through Spin. Thanks again for all your efforts!

[IgordeOliveira]

@iksaku I should change the target in docker-composer for use development stage right?

[iksaku]

Yes! I forgot to add that part 😅

[yetiyeti1998]

I'm using Laravel Jetstream with Inertia, when I run on production it show error "vite manifest not found" while I already defined npm run build on Dockerfile, any idea how to fix it?

[yetiyeti1998]

Now I've got this using php:beta-php8.2-fpm-alpine 😭

[jaydrogers]

You should subscribe to our releases to make sure you're not missing out on important updates: https://serversideup.net/open-source/docker-php/docs/getting-started/upgrade-guide#subscribe-to-repository-updates

See why your installation is failing here: https://github.com/serversideup/docker-php/releases/tag/v3.0.0-beta4

[iksaku]

Images now default to www-data user. To install extensions you need to switch to root with the USER docker command:

FROM base
# ...
USER root
RUN install-php-extensions intl curl gd
# Any other changes that require root privileges
# Finally, remember to go back to unprivileged
USER www-data

I will update my guide above and add a little note with it :)

[iksaku]

Example updated 👍 I've added more comments in the step-by-step explanation, hope it is not confusing 😅

@jaydrogers I know you also have Spin, but if there is a small room for this to be up in the docs please let me know and I will make a PR 😉

[jaydrogers]

Thanks!! I'll keep you posted. Lots of things moving with Spin and Docker PHP. I'll loop back here once I have a spot 👍