Installing Laravel on a Raspberry Pi with Sail

I'm a big fan of Laravel and Raspberry Pis, so I wanted to see if I could get Laravel working on one of my Pis. Installing PHP + Composer + Redis + a database is a chore, but Laravel offers a Docker-based solution called Sail that lets you run these in containers without having to install them on the base OS. The Laravel documentation's install script doesn't natively support ARM processors like those found on the Raspberry Pi, but it's still possible to use it to get Sail running with a few extra steps.

Things are changing quickly with Docker's support on ARM systems, so I have links to the official documentation for most of the steps. You may want to check the docs for changes as you get everything set up.

1. Uninstall old versions of Docker

sudo apt-get remove docker docker-engine docker.io containerd runc

See Docker's official docs for the most up-to-date commands for removing old versions.

2. Install Docker using the convenience script

At the time of writing this post, you can't just install Docker with apt install on a Raspberry Pi. Instead, you must use their convenience script.

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

See official docs for installing Docker via convenience script.

3. Add your user to the Docker group

This is optional, but it's probably a good idea to run Docker as your user instead of with sudo. You'll need to log out and log in again for this to actually take effect.

sudo usermod -aG docker <your-user>

You can read more about this and its security implications in the convenience script docs.

4. Install Docker Compose with Pip

Because nothing is straight forward on a Raspberry Pi, you need to install Docker Compose with Python's Pip package manager instead of installing a binary. The docs recommend that if you install with Pip that you should use virtualenv, but I installed it on the base machine to keep things simple.

sudo pip3 install docker-compose

Note: I used pip3 instead of pip when I installed. The docs say use pip, but I figure it should probably run in Python 3. I'm not 100% sure 🤷‍♂️
Check the docs for installing Docker Compose.

5. Install libseccomp2

From what I understand, Docker broke some ARM images around December 2020 because of something to do with the libseccomp2 library. I was using the full Raspberry OS with desktop enabled when I installed Laravel, so I navigated to the Debian libseccomp2 download page in my browser, download the deb file, opened it and clicked install.

If you're using Raspberry OS Lite, you'll need to find a way to get this package through the command line. If you're using Ubuntu Desktop on Raspberry Pi, the images work without needing to install libseccomp2.

I anticipate that this problem will be solved by Raspberry Pi OS in the future, but it is necessary for now.

6. Download and modify the Laravel installer script

If you go to the install page in Laravel's docs, it recommends installing Laravel by piping a script from cURL into Bash. Unfortunately, the script relies on the laravelsail/php80-composer Docker image, which isn't available for ARM processors.

Fortunately, this image seems to just be an image of Composer that has the official Laravel installer already installed. We'll download the installer script and replace the image with the official Composer image and modify the installation command.

Navigate to the directory where you want to install your project and download the script with the following command:

curl https://laravel.build/example-app --output install.sh

Now open install.sh with your favorite text editor and look for the following line:

docker run --rm \
    -v $(pwd):/opt \
    -w /opt \
    laravelsail/php80-composer:latest \
    bash -c "laravel new example-app && cd example-app && php ./artisan sail:install --with=mysql,redis,meilisearch,mailhog,selenium"

We will:

1. Replace the laravelsail/php80-composer:latest with composer:latest, which has support for ARM.
2. Change the bash command to use the Composer's create-project command instead of the global Laravel installer.
3. Replace mysql with pgsql, then remove meilisearch, mailhog and selenium. MySQL, MeiliSearch, Mailhog and Selenium do not currently have ARM images available.

Your command should now look like this:

docker run --rm \
    -v $(pwd):/opt \
    -w /opt \
    composer:latest \
    bash -c "composer create-project laravel/laravel example-app && cd example-app && php ./artisan sail:install --with=pgsql,redis"

Save the script and run it using the command below.

bash install.sh

7. Start Sail

At this point you should have a folder called example-app in your current directory. Run the following command in terminal:

cd example-app && ./vendor/bin/sail up

After about half an hour of installing dependencies, you should have a running container. In my case, my PostgreSQL and Redis containers were giving me errors and crashing. I restarted my computer then ran ./vendor/bin/sail up again in the project directory and everything worked: I had Laravel running on my computer.

8. Set a database password

On my machine, Sail got angry when I tried to connect to the PostgreSQL database when there was no password set in my .env file. If you get errors when you try to use the database, set the value of DB_PASSWORD in your .env file to any value you like and it should just work.

9. Build something cool!

Running Sail on a Raspberry Pi is currently a little involved, but with Raspberry Pi's continuing to gain popularity and Apple's M1 processors being ARM based, I imagine this will become much more streamlined in the not-so-distant future.

I've seen GitHub issues with developers offering to help build a Selenium image for ARM, and when I tweeted about this project originally, MeiliSearch reached out to me directly about potentially adding an ARM image to their roadmap. The Sail experience on Raspberry Pi will only continue to get better with time.

Has something changed since I published this post? Let me know in the comments below so I can update this to include the current process.