How-To: Dockerized Laravel that just works

## Run Laravel anywhere

Docker is rapidly becoming the standard for running server applications. One of the key benefits of Docker is portability: the ability to run applications identically regardless of the underlying platform or system. This is especially helpful when running Laravel applications that require installation and configuration of OS-level packages.

However, configuring a docker image is a tedious, and many times, frustrating endeavor.

## Laravel is difficult to configure on Docker

Unfortunately, many guides explain *just enough* to get your Laravel app working in Docker, but fall short in a few areas.

1. **The resulting image is large.** This makes for slow local setup, especially if you are working at a coffee shop. This large image also makes for a frustrating experience if you are deploying a critical fix to production and it is taking forever to pull the image.
2. **The container needs restarted locally.** Every time you make a change to your Laravel application, you have to rebuild/restart your container to see your changes. When we face this, we end up running Laravel on our local machine and discarding Docker.
3. **The image is configured for production use.** When configured *only* for production use, the docker image is difficult to debug or diagnose. We end up running Laravel locally and use Docker for production. Or we create a separate `local.Dockerfile` that we have to maintain separately.

## Laravel that just works, everywhere

This guide gets you started with docker on a default Laravel app that *just works* locally and in production with the following:
- Server is optimized for [php-fpm](https://php-fpm.org/).
- Static assets and files are automatically added using `ONBUILD` during your docker build process.
- When making code changes, no need to rebuild/restart your container.
- Logs are emitted to stdout/stderr.
- The resulting image is relatively small (~37mb).
- Preconfigured to attach [nginx](https://www.nginx.com/) sidecar container. See below.

This guide assumes the default setup uses a mysql database, but also contains details on how to add other dependencies and databases (e.g. postgres, redis, etc.).

## Quickstart

To get started, you will need to add 3 files to our repository.
Create `Dockerfile` in your repository root. This is used to build your local and production docker image.
If you're curious how the base image is configured, visit [https://github.com/nullstone-io/docker-laravel](https://github.com/nullstone-io/docker-laravel).

```docker

FROM nullstone/laravel

```

Create `.dockerignore` in your repository root. This will prevent docker from adding sensitive files (e.g. `env`) or PHP packages that are specific to your local system. Don't worry, your vendor directory inside the docker container will be cached.

```docker
.*
vendor/

```

Create `docker-compose.yml` in your repository root. This stands up a docker container running php containing your laravel app, an nginx container for static assets, and a mysql database container.

```docker
version: "3.8"
services:
 nginx:
   image: nginx:stable-alpine
   volumes:
     - app-public:/app/public
     - nginx-confd:/etc/nginx/conf.d
     - nginx-templates:/etc/nginx/templates:ro
   ports:
     - "3000:80"
   environment:
     - WEBAPP_ADDR=app:9000
   depends_on:
     - app
 app:
   build: .
   entrypoint: /docker-entrypoint.d/local.sh
   command: php-fpm8
   volumes:
     - vendor:/app/vendor
     - .:/app
     - app-public:/app/public
     - nginx-confd:/etc/nginx/conf.d
     - nginx-templates:/etc/nginx/templates
   environment:
     - APP_ENV=local
     - APP_KEY=${APP_KEY}
     - APP_DEBUG=true
     - DATABASE_URL=mysql://acme:acme@db:3306/acme
   depends_on:
     - db
 db:
   image: mysql:8.0
   ports:
     - "3306:3306"
   environment:
     MYSQL_ROOT_PASSWORD: acme
     MYSQL_DATABASE: acme
     MYSQL_USER: acme
     MYSQL_PASSWORD: acme
   healthcheck:
     test: ["CMD", "mysqladmin", "ping", "-pacme"]
     retries: 3
     timeout: 5s
volumes:
 vendor:
 app-public:
 nginx-confd:
 nginx-templates:
```

Now, let's launch our Laravel app.

```sh
$ docker compose up
```

Once your container is launched, the application should be reachable from [https://localhost:3000](https://localhost:3000).

## How to extend and configure

If your app did not launch properly, you may need to extend or configure.
Below is a set of common ways to configure and extend Laravel.

### **Port 3000 is already in use**

By default, this setup uses port 3000, but only by convention.
If you wish to change, refer to line 11 of `docker-compose.yml`.
Change `3000` in the line `- "3000:80"` to an unused port on your system.

### **I want to use postgresql instead of mysql**

By default, the database is configured for mysql.
If you would like to swap for postgres, you will need swap out the `db` service and reconfigure Laravel to use `pgsql`.
Swap out the `db` service in the `services:` section of `docker-compose.yml`.

```docker
services:
 ...
 db:
   image: postgres
   ports:
     - 5432:5432
   environment:
     - POSTGRES_USER=acme
     - POSTGRES_PASSWORD=acme
     - POSTGRES_DB=acme

```

Reconfigure Laravel for `pgsql`. Make sure to remove the existing `DATABASE_URL` environment variable.

```docker
services:
 ...
 app:
   ...
   environment:
     ...
     - DB_CONNECTION=pgsql
     - DATABASE_URL=postgres://acme:acme@db:5342/acme?sslmode=disable
```

### **I want to use redis for caching**

By default, caching is done using the file system.

If you would like to add a redis cache layer, then you will need to add redis to your docker-compose and configure Laravel to use redis inside the docker-compose. Then, you will need to update your `Dockerfile` with the appropriate dependencies.

Add `redis` service under the `services:` section in `docker-compose.yml`.

```docker
services:
 ...
 redis:
   image: redis:6-alpine
   ports:
     - "6379:6379"

```

Configure Laravel to use redis in the existing `app` service under `services:` section in `docker-compose.yml`.

```docker
services:
 app:
   ...
   environment:
     ...
     - CACHE_DRIVER=redis
     - REDIS_URL=tcp://redis:6379/0

```

Install `php-redis` extension to your Dockerfile. Warning: This was left out of the base image because it added ~100mb to the image size.

```docker
FROM nullstone/laravel
RUN apk add --no-cache pcre-dev $PHPIZE_DEPS \
 && pecl install redis \
 && rm -rf /tmp/pear \
 && docker-php-ext-enable redis.so
```

## What's next

Hopefully you have a fully functioning Laravel app running in docker on your local machine now. If you still need to configure the OS, you will need to use `apk` (the alpine package manager) instead of `apt`, `apt-get`, or `yum`. As you configure your app in different environments, make sure to follow docker best-practices by using environment variables. This will allow you to easily configure regardless of how your app is launched into production.

If you are interested in launching your newly-dockerized app to a cloud provider, log in at [https://app.nullstone.io](https://app.nullstone.io) and we will launch a secure container app on your cloud provider. We have a reference guide for Laravel in our docs at [https://docs.nullstone.io/frameworks/php/laravel.html](https://docs.nullstone.io/frameworks/php/laravel.html).