I was playing with a Digital Ocean Kubernetes cluster (the default 3 Nodes is ~$72/mo, which will run a decent number of your typical Laravel apps).

Like other clouds, DO's flavor of K8s is...just K8s (that's a good thing!) and integrates with their other services, such as a managed load balancer. This means we can get traffic into our K8s cluster pretty easily.

So, based on this DO article, here's how I did stuff on K8s on Digital Ocean.

Everything here is updated to the most modern version (as of this writing), and shorted to make a bit more sense (to me), and do less work (skip generating SSL certs).

The Goal

The goal here is to run an application, and get public traffic routed to it.

We need a few things:

1. A K8s cluster
2. A way to ingress (get incoming traffic to) to the cluster
3. A way to run web app containers

You'll need kubectl to do anything useful here. It's likely already present if you're using Docker on Mac.

Let's start!

The Cluster

We first create a K8s cluster. This is just clicking around the DO UI. Don't get hung up on the number of Nodes, etc - to play with this, just create the basic 3-node "regular CPU/disk drive" option.

Once you've watched the create progress bar for a few minutes, refresh to find that maybe the progress bar was lying, and then find yet even more buttons that appear to download the configuration (Kubeconf) file.

Then we can confirm that everything is running:

# Normally this is at ~/.kube/config, but
# I'm just using the downloaded file here
export KUBECONFIG=/Users/fideloper/Downloads/fidelopers-cluster-luck-kubeconfig.yaml

# Confirm it works, find all
# Pods running in all namespaces
kubectl get pods -A

# Get all resources in this
# cluster across all namespaces
kubectl get all -A

You'll see a big list of Pods running in your K8s cluster. It's all normal - things that provide networking (Cilium, coredns, kube-proxy), a CSI (container storage interface) to help with attaching storage, things monitoring your cluster, and more things specific to how DO manages your cluster.

Ingress

The term "ingress" refers to incoming network traffic. We're going to get public web requests into stuff running in our K8s cluster.

To do that, we'll install Ingress Nginx, which will do 2 things:

1. Create a DO managed load balancer
2. Run Nginx within the K8s cluster

These two things work together - the load balancer gets Nginx registered as an endpoint to proxy traffic to, and then Nginx (running within the cluster) can accept web requests and route them to the correct Service (and therefore the correct Pods running your apps).

The Ingress Nginx has configuration for the popular flavors of managed (and unmanaged) K8s.

We're using the do flavor here.

# Find the latest release of the controller (not of the Helm chart!) here:
# https://github.com/kubernetes/ingress-nginx/releases
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.10.1/deploy/static/provider/do/deploy.yaml

It will take a few moments for the Load Balancer to be created (find it in the Networking tab of your DO console).

We have the cluster and a way to ingress into the cluster. Let's now create the other stuff we need to route traffic to the correct place.

This requires the following:

1. A Service
2. A Deployment
3. An Ingress

A Service exposes a Deployment as something reachable by the network, basically saying (for example) "all requests to this service at this port go to this target".

A Deployment gets some Pods running, with the containers of your choice. This also sets sets the port the containers are running on (the aforementioned "target").

An Ingress defines how ingress traffic (external traffic headed into the cluster) is routed to the Service and thus can reach the Pods within that Service.

The Service + Deployment

We're going to define 2 K8s objects at once here:

1. a Service
2. a Deployment

The Service points traffic to the Pods created in the Deployment.

The Deployment creates a ReplicaSet and Pods. A ReplicaSet is a thing that says "keep this many of this Pod running".

The Deployment also helps deploy the Pods (creating and later updating them), using a "rolling" deployment strategy by default.

Here's what it looks like to define them - create file echo.yaml:

apiVersion: v1
kind: Service
metadata:
  name: echo1
spec:
  ports:
  - port: 80
    targetPort: 5678
  selector:
    app: echo1
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: echo1
spec:
  selector:
    matchLabels:
      app: echo1
  replicas: 2
  template:
    metadata:
      labels:
        app: echo1
    spec:
      containers:
      - name: echo1
        image: hashicorp/http-echo
        args:
        - "-text=echo1"
        ports:
        - containerPort: 5678

And then apply it:

k apply -f echo.yaml

I've named everything "echo1" (you can duplicate all of this and adjust it to be echo2 to create a second Service, etc).

There's a bunch going on, but the Service name being echo1 is the most important in terms of getting external traffic routed to this.

One thing we did is give the Pods a the key=value label of app: echo1. That's done with the template, which is a tempmlate for the Pod spec.

You can create a Pod directly too, but using a Deployment is generally what you want to do, since it provides the ReplicaSet and a deployment strategy. See how we have a replica of 2? There will be 2 pods of this container running.

(The "selector" stuff is applying the Service and Deployment to those Pods of label app: echo1).

Got it? Me either. This took me a while. The K8s yaml provides for a lot of use cases, and so its abstractions are a bit odd at first.

We can't route traffic yet

So we can't yet route traffic to this service from the outside world. However we can test this out via K8s internal DNS:

# Run a Pod of Ubuntu 24.04 and make some 
# curl requests to the service we just created
# This is just like running a Docker container, e.g.
#   "docker run --rm -it ubuntu:24.04 bash"
kubectl run --rm -it --image=ubuntu:24.04 -- bash

> apt-get update && apt-get install -y curl
> curl echo1.default.svc.cluster.local
># echo1

The hostname echo1.default.svc.cluster.local is in format <service-name>.<namespace>.svc.cluster.local. The HTTP response is just "echo1".

Ingress

We created a service, and we can use internal DNS to send requests to it from within the cluster. However, we want external traffic to reach it through the load balancer!

The flow of traffic will be my laptop -> DO load balancer -> Ingress Nginx -> one of the 2 Pods.

To accomplish that, we need to define an Ingress. The Ingress will tell K8s to use Ingress Nginx to route requests to the correct Service based on hostname (we'll configure it to map hostnames to Services, but you can do other stuff).

Create a new file ingress.yaml:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: echo-ingress
  annotations:
    kubernetes.io/ingress.class: "nginx"
spec:
  rules:
  - host: echo1.example.com
    http:
        paths:
        - pathType: Prefix
          path: "/"
          backend:
            service:
              name: echo1
              port:
                number: 80

And then apply it:

k apply -f ingress.yaml

Since we set the annotation kubernetes.io/ingress.class: "nginx", this will read a thing called an IngressClass that exists.It's named nginx and was created by Ingress Nginx when we installed it. It's job is to tells Ingress Nginx to reconfigure itself to route requests to hostname echo1.example.com to the service named echo1.

My Load Balancer IP address is 143.244.220.120, and at this point I can send requests to it successfully:

curl -H "Host: echo1.example.com" 143.244.220.120
# echo1

# BTW, this won't work since it didn't pass a Host header:
curl 143.244.220.120
# 404

So, that's cool! We can route web traffic to this!

At this point I stopped, because the addition of adding SSL certificates is a bit boring (which isn't to say easy or non-trivial). It requires a real domain tho, and I didn't feel like doing DNS things to make it work. However the article on using CertManager to manage SSL via LetsEncrypt are good!

This isn't about how to do Continuous Integration with Laravel, but instead it's best for local development.

Our Goals:

• Unit test to version of PHP you want
• Watch for file changes

Without Docker:

We can use a utility called pywatch to run a command when files are changed. Here's how we create a new Laravel project and run unit tests automatically when they're updated:

cd ~/Sites
composer create project laravel/laravel docker-testing

cd docker-testing

virtualenv .venv
source .venv/bin/activate
pip install pywatch

pywatch ./vendor/bin/phpunit ./tests/*.php

This works pretty great, but what if we want to test a specific version of PHP when we run our unit tests? Docker can help us there.

With Docker

docker pull php:7.0-cli
# See the new docker images we pulled down
docker images

# Run PHP in a container to run our local phpunit
docker run --rm -v ~/Sites/homestead/docker-testing:/opt php:7.0-cli php /opt/vendor/bin/phpunit /opt/tests

That's good, but let's use pywatch in a container to run unit tests automatically. We'll make our own Docker image. Create a new file named Dockerfile.

FROM php:7.0-cli

MAINTAINER Chris Fidao

RUN apt-get update
RUN apt-get install -y python-pip
RUN pip install -U pip
RUN pip install pywatch

WORKDIR /opt

ENTRYPOINT ["pywatch"]

Then we can build our Docker image and try it out:

mkdir docker
cd docker

# create Dockerfile here

# Create a new Docker image named "phptest" and tag it as PHP 7.0
docker build . -t phptest:7.0

# Try running the new image
docker run --rm -it -v ~/Sites/homestead/docker-testing:/opt phptest "php ./vendor/bin/phpunit" ./tests/*.php

This uses the pywatch command set as the ENTRYPOINT and appends the other commands we added. The full command run in the container becomes pywatch "php ./vendor/bin/phpunit" ./tests/*.php, which watches the files in the tests directory ending in .php.

In this video, we'll add to the input chain, which controls incoming (ingress) traffic:

sudo iptables -A INPUT -i lo -j ACCEPT
sudo iptables -A INPUT -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -j DROP

We appended rules so far, but you can also insert rules to a specific location:

sudo iptables -I INPUT 5 -p tcp --dport 443 -j ACCEPT

Finally, we need to persist these rules through reboots:

# Install it (this should save your current rules)
sudo apt-get install -y netfilters-persistent

# Persist for next reboot (may be unnecessary)
sudo iptables-save > /etc/iptables/rules.v4

Resources

• Consider using iptables-nft instead of the "legacy" iptables command
• See how to convert rules to nft format here.

Edit /etc/ssh/sshd_config:

# Important
PermitRootLogin no
PasswordAuthentication no

# Double check these
PubkeyAuthentication yes
PermitEmptyPasswords no

# Optional
AllowUsers fideloper
AllowGroups sudo ssh

Then restart ssh:

sudo service ssh restart

We'll also install fail2ban, which will check our /var/log/auth.log file for repeated SSH login failures and ban further logins from the source (IP) of those logins, giving us extra protections against brute-force based SSH access attempts.

sudo apt-get install -y fail2ban

Check to make a file exists within /etc/fail2ban/jail.d exists with the sshd config similar this:

[sshd]
enabled = true

sudo adduser fideloper

# Locally:
# cd ~/.ssh
# ssh-keygen -o -a 100 -t ed25519 -f id_ed
# cat id_ed.pub | pbcopy

# Back on server when logged in as user "fideloper":
echo "your-public-key" >> ~/.ssh/authorized_keys

Resources

• Upgrade your SSH Keys

This is a guest post from Jack Ellis, who has a lot of experience in AWS and, specifically, working with serverless. Here's how he used serverless technologies to stop having to worry about servers.

Back in mid 2018, Fathom Analytics was deployed across a series of dedicated / virtual servers. The team paid a good amount of cash for these servers, and they thought it would lead to good uptime, great redundancy and a life of very little server maintenance. Unfortunately, that wasn't the case. The servers would go offline, run into various issues, and require attention from a member of the team regularly. They were on the verge of hiring a freelance DevOps chap ($1k / month) to be available in case of an emergency. At that time, they couldn't really afford that, so it meant they had to take responsibility and handle the issues themselves.

Fast forward to late 2018, the main developer (Danny) left the Fathom team to become a teacher, and Paul Jarvis was left with a hard decision. Should he attempt to keep Fathom going or should he shut it down? I remember the phone call. Myself and Paul were working on Pico (acquired by Ghost), and Paul asked if I wanted to join the Fathom team. And I immediately said yes, because I saw the potential it had if a skilled developer was to be brought in.

We rebuilt the system in Laravel. It took us a few months, working part time on it, and we deployed it to Heroku in no time. Fast forward a few more months, as we were pricing out Heroku and considering how we would grow with their rigid tier jumps, Taylor Otwell announced Laravel Vapor, a serverless deployment platform for Laravel. We immediately jumped onto the waiting list and, when it launched, we were one of the first companies to deploy our entire application on it. Since then, we've grown to handle millions upon millions of requests each month.

What is this, a history lesson? I came here to read about why you choose serverless. Okay, calm down Jonathan. Here's why we choose to use serverless infrastructure:

We don't want to manage servers

I'm sure you've all experienced this. It's 2AM in the morning, and you're disoriented as your phone rings. Who could be calling at this time? Oh, PingPing has pinged our web hook and we're now getting a phone call. Great.

“Are you ok?” the wife asks. “I hate servers” you reply. “Why don't you just go serverless?” your German shepherd inquires.

You fix the issue and try to get back to sleep. But the adrenaline prevents that. 4 hours sleep will have to do, time to start your day.

We don't know when we'll land that whale

Most of our customers are in the < 1 million page views range. But what happens when someone emails us asking for 500M page views per month? We can't say “Sure, just let us know when you're going to add the javascript code to your website because our infrastructure won't be able to handle it”. Imagine how that would make them feel. Nobody wants to be your biggest customer.

Comparatively, we fear nothing these days. 500M page views? Bring it on, Lambda auto scales and SQS has a practically infinite capacity for queued jobs. When someone asks me if we can quote them for 500M page views, I say “Is that all you're going to need. Let me know if you need more, we can provide quotes for up to 5 billion” page views. I'm only joking, but that's how I feel.

Our service needs to be highly-available

People don't want their analytics to go offline. We've always taken uptime incredibly seriously. Paul once told me that before I joined, he would get regular “website down” emails. We haven't received a "website down" email in a very long time, and we wouldn't have it any other way. With Laravel Vapor, it provisions lambda functions, which means we have incredible redundancy and availability. If a lambda functions “breaks”, it's just replaced with another one.

Deployment is unbelievably simple

We use Laravel Vapor, so everything is managed from a simple YAML file (I have a lesson on this in my course). We can provision environments in less than 2 minutes. We can also tweak memory, worker memory, concurrency, attach databases, caches and more, all from a single YAML file. It's a truly wonderful way to manage deployments. I thought Heroku was great with their dyno slider, but Vapor takes it to a whole new level. I remember how much I laughed when I spun up a staging environment in under 60 seconds. Doing that in DigitalOcean would take so much longer. Even tweaking memory settings is a joke on DigitalOcean compared to Vapor

Varying server load

I mentioned the whale problem above (which we no longer have) but we also don't have to worry about spikes & drops. Imagine that during the day we're hitting 100M requests p/h, and then it drops to 1M requests p/h at night, we need to set-up some auto scaling. We really don't want to be spending time setting the scaling up, and we don't want to pay to be over-provisioned "just in case".

And I could keep writing reasons for why we use serverless until the cows come home.

We've been using Vapor since it launched in 2019 and we sleep incredibly well knowing that we don't have to spend time thinking about servers. Everything is managed. RDS, Elasticache, DynamoDB etc. are wonderful. We provision these services with Vapor, and then we let the AWS team do their thing. And yes, these add-on services do need to be scaled, but there are ways to control things like database load, and set-up modest thresholds for notifications when it's time to scale. Oh, and scaling is handled with zero to minimal downtime with high-availability set-ups, which is huge to us.

I've said enough. If you want to become an expert at using Laravel Vapor, I can help you with that. I've spent hundreds of hours in the field and have used it at high scale since it launched. My course (Serverless Laravel) is currently only $149 ($100 discount during launch). If you're reading this article after the launch is over, drop me an email and we'll see what we can do. Anyway, this course will save you from running into common gotchas, and is an express route to Vapor mastery. Do you have any questions? Are you mad that I contradict myself because we do need to scale our cache / database etc. at some point? Are you angry at me and you want me to know that you're angry? I'm @jackellis on Twitter

While a traditional LEMP stack will work for hosting WordPress, it won't perform optimally, and it certainly won't be able to handle any significant amount of traffic. However, with a few special considerations, WordPress can be both snappy and scalable. I’ve spent the last year building our new app, SpinupWP, that spins up optimal servers for WordPress, incorporating a lot of these considerations. However, in this article, I'm going to discuss two simple caching mechanisms that you can implement to ensure WordPress is performant on a LEMP stack no matter where you’re setting your servers up. Let's start with object caching.

Object Caching

As with most database-driven content management systems, WordPress relies heavily on the database. A clean install of WordPress 5.0 with the Twenty Nineteen theme activated will execute a total of 19 SQL queries on the homepage alone. That's before you throw third-party plugins into the mix. It's not uncommon for over 100 SQL queries to be executed on every page load, which can be a huge strain on the server.

To combat this, WordPress introduced an internal object cache that stores data in PHP memory (including the results of database queries). However, the object cache is non-persistent by default - meaning that the cache is regenerated on every single page load, which is extremely inefficient. Luckily, it's possible for WordPress to utilize an external in-memory datastore such as Redis. This can dramatically reduce the number of database queries on each page load.

On Ubuntu, Redis can be installed like so:

sudo apt-get update
sudo apt-get install -y redis-server

Once Redis has been installed you'll need to install the Redis Object Cache WordPress plugin. This will instruct WordPress to store it's object cache data in Redis and persist the data across requests.

While this is a huge improvement (down from 19 queries to 3 queries), it doesn't completely remove the reliance on the database, which is often the biggest bottleneck in WordPress. This is because the SQL queries to build the post index will always be executed as the results are not cached. This leads us on to full page caching...

Page Caching

A full page cache is hands down the most important thing you can implement to ensure WordPress doesn't fall over under load. It'll also improve response time for individual page requests. While there are a number of WordPress cache plugins available, most won't perform as well as a server-side solution (because the request is still being handled by PHP. As we're already using LEMP we can utilize Nginx FastCGI caching, which will cache a static HTML version of each page. Subsequent visits will serve the static HTML version without ever hitting PHP or MySQL.

To enable Nginx FastCGI caching you'll need to adjust a few directives to your existing configs. The following should be added to the top of each virtual host file before the server block:

fastcgi_cache_path /path/to/cache/directory levels=1:2 keys_zone=acmepublishing.com:100m inactive=60m;

This creates the cache zone and indicates the directory where the cache should be stored (see this doc for more info on what the other arguments mean). Next, when proxying requests to PHP you can inform Nginx to first check that a cache key exists for the current request, before sending it off to PHP:

location ~ \.php$ {
    try_files $uri =404;
    include fastcgi.conf;

    fastcgi_pass  unix:/var/run/php/php7.3-fpm.sock;
    fastcgi_cache_bypass $skip_cache;
    fastcgi_no_cache $skip_cache;
    fastcgi_cache acmepublishing.com;
    fastcgi_cache_valid 60m;
}

The $skip_cache variable allows you to bypass the cache. A typical strategy is to only cache GET requests for non-logged in users. It's also common to skip requests which contain a query string:

# Don't skip cache by default
set $skip_cache 0;

# POST requests should always go to PHP
if ($request_method = POST) {
    set $skip_cache 1;
}

# URLs containing query strings should always go to PHP
if ($query_string != "") {
    set $skip_cache 1;

}

# Don't cache uris containing the following segments
if ($request_uri ~* "/wp-admin/|/wp-json/|/xmlrpc.php|wp-.*.php|/feed/|index.php|sitemap(_index)?.xml") {
    set $skip_cache 1;
}

# Don't use the cache for logged in users or recent commenters
if ($http_cookie ~* "comment_author|wordpress_[a-f0-9]+|wp-postpass|wordpress_no_cache|wordpress_logged_in|edd_items_in_cart|woocommerce_items_in_cart") {
    set $skip_cache 1;
}

The final piece of the caching puzzle is to ensure Nginx can cache requests which have Cache-Control and Set-Cookie headers. If WordPress uses one of these headers then Nginx might not be able to cache the request so we can tell Nginx to ignore them. We also need to set the cache key and tell Nginx how to handle cached entries which have expired:

fastcgi_cache_key "$scheme$request_method$host$request_uri";
fastcgi_cache_use_stale error timeout updating invalid_header http_500;
fastcgi_ignore_headers Cache-Control Expires Set-Cookie;

A basic Nginx config might look something like this:

fastcgi_cache_path /sites/example.com/cache levels=1:2 keys_zone=example.com:100m inactive=60m;

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name example.com;

    root /sites/example.com/public;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    index index.php;

    fastcgi_cache_key "$scheme$request_method$host$request_uri";
    fastcgi_cache_use_stale error timeout updating invalid_header http_500;
    fastcgi_ignore_headers Cache-Control Expires Set-Cookie;
    add_header Fastcgi-Cache $upstream_cache_status;

    # Don't skip cache by default
    set $skip_cache 0;

    # POST requests should always go to PHP
    if ($request_method = POST) {
        set $skip_cache 1;

    # URLs containing query strings should always go to PHP
    if ($query_string != "") {
        set $skip_cache 1;

    # Don't cache uris containing the following segments
    if ($request_uri ~* "/wp-admin/|/wp-json/|/xmlrpc.php|wp-.*.php|/feed/|index.php|sitemap(_index)?.xml") {
        set $skip_cache 1;

    # Don't use the cache for logged in users or recent commenters
    if ($http_cookie ~* "comment_author|wordpress_[a-f0-9]+|wp-postpass|wordpress_no_cache|wordpress_logged_in|edd_items_in_cart|woocommerce_items_in_cart") {
        set $skip_cache 1;

    include fastcgi-cache.conf;

    location / {
        try_files $uri $uri/ /index.php?$args;

    location ~ \.php$ {
        try_files $uri =404;
        include global/fastcgi-params.conf;

        fastcgi_pass   $upstream;
        fastcgi_cache_bypass $skip_cache;
        fastcgi_no_cache $skip_cache;
        fastcgi_cache example.com;
        fastcgi_cache_valid 60m;
    }
}

Benchmarks

Let's compare a few common caching solutions to see how they measure up. First I'll test WordPress without any caching, then a WordPress cache plugin (Simple Cache), followed by Nginx. I'll also include Varnish to demonstrate that you don't need additional server software to perform simple caching.

Let's use ApacheBench to simulate 10,000 requests, with a concurrency of 100 requests. Meaning, ApacheBench will send a total of 10,000 requests in batches of 100 at a time.

ab -n 10000 -c 100 https://siteunderload.com/

For the non-cached version, I will use a concurrency of 20 requests because WordPress will never be able to handle that amount of concurrency without caching.

ab -n 10000 -c 20 https://siteunderload.com/

Requests Per Second

Source: SpinupWP

As expected, WordPress doesn’t perform well because both PHP and MySQL are involved with handling the request. Simply taking the database server out of the equation by enabling a page cache plugin gives a 10x increase in requests. This is taken even further by using a server-side caching solution so that PHP is also bypassed.

Average Response Time (ms)

Source: SpinupWP

WordPress once again doesn't perform well because of the number of moving parts required in handling the request (Nginx, PHP and MySQL). Generally, the fewer moving parts you have in a request lifecycle, the lower the average response time will be. That’s why Nginx FastCGI caching performs so well because it only has to serve a static file from disk (which will likely be cached in memory due to the Linux Page Cache).

Conclusion

As you can see from the benchmarks, WordPress doesn't perform well under load. However, with a few simple modifications to your LEMP stack, you can improve the performance dramatically. Looking to take things further? Check out A CDN Isn’t a Silver Bullet for Performance or save yourself the hassle and spin up a server with SpinupWP.

About the Author

Ashley is a former SAC Technician who built servers for the Royal Air Force & a PHP developer with a fondness for hosting, server performance and security. He’s the author behind our popular Host WordPress Yourself article series as well as one of the developers behind SpinupWP, the new modern server control panel for WordPress.

Most of us are likely keeping it simple. Here's how I've typically exported a single database:

mysqldump some_database > some_database.sql

# Or with user auth
mysqldump -u some_user -p some_database > some_database.sql

# Or with gzip compression
mysqldump some_database | gzip > some_database.sql.gz

# Or with the "pv" tool, which let's us know how much data is
# flowing between our pipes - useful for knowing if the msyqldump
# has stalled
mysqldump some_database | pv | gzip > some_database.sql.gz
# 102kB 0:01:23 [1.38MB/s] [  <=>

However, it's worth digging into this command a bit to learn what's going on. If you're using mysqldump against a production database, it's usage can cause real issues for your users while it's running.

Defaults

First, let's cover mysqldump's defaults. Unless we explicitly tell it not to, mysqldump is using the --opt flag. The opt option is an alias for the following flags:

• --add-drop-table - Write a DROP TABLE statement before each CREATE TABLE statement, letting you re-use the resulting .sql file over and over with idempotence.
• --add-locks - This applies when you're importing your dump file (not when running mysqldump). Surrounds each table dump with LOCK TABLES and UNLOCK TABLES statements. This results in faster inserts when the dump file is reloaded. This means that while you're importing data, each table will be locked from reads and writes while it's (re-)creating a table.
• --create-options - Include all MySQL-specific table options in the CREATE TABLE statements. In testing this (turn it off using -create-options=false), I found that the main/most obvious difference was the absense of AUTO_INCREMENT on primary keys when setting this option to false.
• --disable-keys - This option is effective only for nonunique indexes of MyISAM tables. This makes loading the dump file faster (for MyISAM tables) because the indexes are created after all rows are inserted.
• --extended-insert - Write INSERT statements using multiple-row syntax that includes several VALUES lists. Not using this option may be required for tables with large columns (usually blobs) that cause queries to go higher than client/server "max_allowed_packet" configuration, but generally always use this option. Using a single-query per insert slows down imports considerably.
• --lock-tables - Unlike add-locks, this applies to when you're running mysqldump. This locks all tables for the duration of the mysqldump, making it a bad option to use on a live environment. Primarily it's used for protection of data integrity when dumping MyISAM tables. Since InnoDB is rightly the default table storage engine now-a-days, this option usually should be over-ridden by using --skip-lock-tables to stop the behavior and --single-transaction to run mysqldump within a transaction, which I'll cover in a bit.
• --quick - Reads out large tables in a way that doesn't require having enough RAM to fit the full table in memory.
• --set-charset - Write SET NAMES default_character_set to the output. This DOES NOT perform any character set conversion (mysqldump won't do with that any flag). Instead, it's just saying that you want the character set info added in so it's set when re-importing the dump file.

So the default are pretty good, with the exception of --lock-tables. This causes the database to become unusable while mysqldump is running, but it doesn't need to be this way!

We can use mysqldump more intelligently.

Mysqldump and Table Locks

When using mysqldump, there's a trade off to be made between halting/affecting database performance and ensuring data integrity. Your strategy will largely be determined by what storage engine(s) your using in your database tables.

Since each table can have a separate storage engine, this can get interesting :D

By default, mysqldump locks all the tables it's about to dump. This ensure the data is in a consistent state during the dump.

Data Consistency

A "consistent state" means that the data is in an expected state. More specifically, all relationships should match up. Imagine if mysqldump exports the first 5 tables out of 20. If table 1 and table 20 got new rows related to eachother by primary/foreign keys after mysqldump dumped table 1 but before it dumped table 20, then we're in an inconsistent state. Table 20 has data relating to a row in table 1 that did not make it into the dump file.

MyISAM tables require this locking because they don't support transactions. However, InnoDB (the default storage engine as of MySQL 5.5.5) supports transactions. Mysqldump defaults to a conservative setting of locking everything, but we don't need to use that default - we an avoid locking tables completely.

Mysqldump with Transactions

As a rule of thumb, unless you are using MyISAM for a specific reason, you should be using the InnoDB storage engine on all tables. If you've been porting around a database to various MySQL servers for years (back when MyISAM used to be the default storage engine), check to make sure your tables are using InnoDB.

This is the important one:

Assuming you are using InnoDB tables, your mysqldump should look something like this:

mysqldump --single-transaction --skip-lock-tables some_database > some_database.sql

The --single-transaction flag will start a transaction before running. Rather than lock the entire database, this will let mysqldump read the database in the current state at the time of the transaction, making for a consistent data dump.

The single-transaction options uses the default transaction isolation mode: REPEATABLE READ.

Note that if you have a mix of MyISAM and InnoDB tables, using the above options can leave your MyISAM (or Memory tables, for that matter) in an inconsistent state, since it does not lock reads/writes to MyISAM tables.

In that case, I suggest dumping your MyISAM tables separately from InnoDB tables.

However, if that still results in inconsistent state (if the MyISAM table has PK/FK relationships to InnoDB tables), then using the --lock-tables option becomes the only way to guarantee the database is in a consistent state when using mysqldump.

This means that in that situation, you'll have to be careful about when you run mysqldump on a live database. Perhaps run it on a replica database instead of a master one, or investigate options such as Xtrabackup, which copies the mysql data directory and does not cause down time.

Replication

If you're using replication, you already have a backup on your replica servers. That's awesome! However, off-site backups are still a good thing to have. In such a setup, I try to run mysqldump on the replica server instead of a master server.

In terms of mysqldump, this has as few implications:

1. Running mysqldump on a replica server means the data it receives might be slightly behind the master server.
   • For regular backups, this is likely fine. If you need the data to be at a certain point, then you need to wait until that data has reached the replica server.
2. Running mysqldump on a replica is prefered (IMO) since in theory, there is already a built-in assumption that the replica servers will be behind anyway - adding a bit of "strain" of a mysqldump shouldn't be a big deal.

In any case, there are some useful flags to use when replication is in place (or when binlogs are enabled in general).

Master Data

The --master-data flag adds output to a dump file which allows it to be used to set up another server as a replica of the master. The replica needs the master data to know where to start replication.

The --master-data option automatically turns off --lock-tables, since the included binlog position will say where to start replication off, letting you not lose queries if the dump ends up in an inconsistent state. (Again, that's only a consideration if you have MyISAM tables).

If --single-transaction is also used, a global read lock is acquired only for a short time at the beginning of the dump.

Use this when dumping from a master server.

Dump Replica

The --dump-slave option is very similar to the --master-data except it's use case is:

1. Instead of being a dump from the master server, it's meant to be a dump of a replica server
2. It will contain the same master information as the replica server being dumped, where as --master-data set itself as the master

Use this when dumping from a replica server.

From the docs: "This option should not be used if the server where the dump is going to be applied uses gtid_mode=ON and MASTER_AUTOPOSITION=1."

GTID is a newer way to do MySQL replication as of MySQL 5.6. It's a nicer method, so --dump-slave in theory can be one to ignore.

Dump more than one (all) database

I generally dump specific databases, which lets me more easily recover a specific database if I need to.

However you can dump multiple databases:

mysqldump --single-transaction --skip-lock-tables --databases db1 db2 db3 \
    > db1_db2_and_db3.sql

You can also dump specific tables from a single database:

mysqldump --single-transaction --skip-lock-tables some_database table_one table_two table_three \
    > some_database_only_three_tables.sql

You can also dump the entire database. Note that this likely includes the internal mysql database as well:

mysqldump --single-transaction --skip-lock-tables --flush-privileges --all-databases > entire_database_server.sql

The above command used the --all-databases option along with the --flush-privileges option.

Since we'll get the internal mysql database, which includes mysql users and privileges, the --flush-privileges option adds a FLUSH PRIVILEGES query at the end of the dump, needed since the dump may change users and privileges when being imported.

That's it!

There are many, many options you can use with mysqldump. However, we covered what I think are the most important for using mysqldump in a modern implementation of MySQL.

Side note, If you're interested in a service to help you manage MySQL-optimized, backup and (eventually) replication-enabled database servers, sign up here to let me know! The idea is to allow you to better manage your MySQL servers, taking advantage of many of MySQL's more advanced options, especially around backup and recovery.

? Nginx "map" is super useful!

? Nginx sets incoming headers to variables ($http_foo)

So, here we set X-Forwarded-Proto to the value of $cloudfront_proto that "map" creates by testing for two possible "proto" headers!https://t.co/VkNRMpDDqr pic.twitter.com/6CAXEhiA29

Tiny note here: This video's audio quality isn't as good as usual (and I apologize for my clicky keyboard! That won't be the usual :D

When we use our applications behind some sort of proxy, we usually need to make the application aware it's behind a proxy.

This lets the application know to use the Forwarded or the X-Forwarded-* headers to know the protocol/schema (http vs https), port, and real client IP address.

For Laravel, the TrustedProxy package does this. It uses the underlying Symfony HTTP Request class and sets a proxy as "trusted". If the proxy is trusted, and has either Forwarded or X-Forwarded-* headers set, then the application uses those headers.

The Problem

The problem is that Symfony (as of Symfony 4) currently only allows those two header sets to be used.

• The Forwarded header, which contains all the client information in the header value (client ip, protocol, port, host)
• The X-Forwarded-* headers (-Port, -Proto, -For, -Host)

However, we aren't always lucky enough to have these two headers be available to use. Notably, AWS Cloudfront only provides the Cloudfront-Forwarded-Proto header for passing along the schema (http vs https).

Cloudfront will, however, add the X-Forwarded-For header. I'm not sure why they strip out the other X-Forwarded-* headers. You can see Cloudfront's header behavior here.

The Solution

So, in our case, our application won't correctly read the Cloudfront-Forwarded-Proto header that our web server receives.

Luckily, we can use Nginx to remap the Cloudfront header to a header of our choosing!

We'll do this while still avoiding "if" statements inside of Nginx configuration.

Our tool of choice here will be Nginx's map feature.

The first thing to note is that map is in the http context, not within the server context, so we need to configure it outside of any particular server {...} block. This may mean that it could affect other or all server's configured within Nginx.

Map

Here's what it looks like!

upstream app {
    server 127.0.0.1:8080;
}

map $http_cloudfront_forwarded_proto $cloudfront_proto {
    default "http";
    https "https";
}

server {
    listen 80 default_server;

    root /var/www/html;

    index index.html index.htm;

    server_name front.example.org;

    charset utf-8;

    location / {
        include proxy_params;
        proxy_set_header X-Forwarded-Proto $cloudfront_proto;
        proxy_pass http://app;
        proxy_redirect off;

        # Handle Web Socket connections
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Here Nginx is proxying to an application listening on http port 8080.

Outside of the server {...} block (which is inside of Nginx's http {...} block, altho that's not necessariy obvious) we set a map:

map $http_cloudfront_forwarded_proto $cloudfront_proto {
    default "http";
    https "https";
}

The variable $http_cloudfront_forwarded_proto is provided for us. Nginx takes any HTTP headers, lower-cases them, and converts dashes to underscores. They become accessible as variables starting with $http_.

So, our map function here is reading values for HTTP header Cloudfront-Forwarded-Proto via $http_cloudfront_forwarded_proto. We're telling Nginx to map another value onto a new variable that we created named $cloudfront_proto.

Inside of the map, everything on the left are possible values for the $http_cloudfront_forwarded_proto variable. If one matches, then the value on the right is given to variable $cloudfront_proto.

Using map lets us:

1. Set a default
2. Arbitrarily set the value of our mapped variable

In this case, we're defaulting to http when Cloudfront-Forwarded-Proto is either missing or has a value other than https.

Passing the Header

In our server configuration, we pass that header off to our application via proxy_set_header:

location / {
    include proxy_params;
    proxy_set_header X-Forwarded-Proto $cloudfront_proto;
    proxy_pass http://app;
    proxy_redirect off;
}

We create header X-Forwarded-Proto (which our application will use!) and give it the value of our mapped/created variable $cloudfront_proto.

Edge Cases

One issue with our configuration above is that it would ignore any value of X-Forwaded-Proto if it was present!

To take advantage of the case where X-Forwarded-Proto was included (and so we don't ignore it), I use this more complex mapping:

map "$http_cloudfront_forwarded_proto:$http_x_forwarded_proto" $cloudfront_proto {
    default "http";
    ":http" "http";
    ":https" "https";
    "http:" "http";
    "https:" "https";
    "https:http" "https";
    "http:https" "https";
    "https:https" "https";
}

Some things to note:

1. We can create a string from multiple variables to map from. In this case, I combine X-Forwaded-Proto and Cloudfront-Forwarded-Proto, concatenating them together with a : in betwen.
2. I then test possible combinations of the resulting string, with a preference to use https in the cases where both headers are set but conflict with eachother.

Since our default is http, we can actually get rid of any of the combinations that result in the value http being used:

map "$http_cloudfront_forwarded_proto:$http_x_forwarded_proto" $cloudfront_proto {
    default "http";
    ":https" "https";
    "https:" "https";
    "https:http" "https";
    "http:https" "https";
    "https:https" "https";
}

It's still a bit ugly, but it works!

This can be be simplified greatly with the use of a regular expression:

map "$http_cloudfront_forwarded_proto:$http_x_forwarded_proto" $cloudfront_proto {
    default "http";
    "~https" "https";
}

That's much cleaner and provides the same functionality. Any instance of "https" in the header value will set the X-Forwarded-Proto header value to https.

FastCGI & PHP

In my example above, we had Nginx proxying over HTTP to our application code. What if we're using FastCGI instead (for example, to proxy to a PHP application using PHP-FPM)?

FastCGI in Nginx has no equivalent of proxy_set_header, since it doesn't actually send an HTTP request to PHP. Instead, Nginx (following FastCGI spec and PHP convention) converts headers to proxy_params, which get sent to PHP-FPM.

For PHP, we can set a new proxy param that would get read as an HTTP header by PHP. These all start with HTTP_ within PHP's global $_SERVER variable.

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass unix:/var/run/php/php7.2-fpm.sock;
    fastcgi_param HTTP_X_FORWARDED_PROTO $cloudfront_proto;
}

Here we used fastcgi_param to include what PHP will read as the HTTP header X-Forwarded-Proto!

We set X-Forwarded-Proto to the value of our mapped variable $cloudfront_proto via this line in our configuration:

fastcgi_param HTTP_X_FORWARDED_PROTO $cloudfront_proto;

Result

Now our application can read the X-Forwared-Proto header that it expects to find! We can use this technique to map any custom/unexpected headers to ones that are more commonly used/expected in our applications this way.

This is a video from the Scaling Laravel course's Load Balancing module.

Part of what I wanted to cover was how to use SSL certificates with a HAProxy load balancer. LetsEncrypt (certbot) is great for this, since we can get a free and trusted SSL certificate. Since we're using LetsEncrypt on a load balancer (HAProxy) which cannot serve the authorization HTTP requests that LetsEncrypt makes, we have some unique issues to get around. Let's see how!

Install LetsEncrypt

Let's get some boilerplate out of the way. Here's how I install LetsEncrypt (Certbot) on Ubuntu 16.04:

sudo add-apt-repository -y ppa:certbot/certbot
sudo apt-get update
sudo apt-get install -y certbot

As the video shows, this installer creates a CRON task (/etc/cron.d/certbot) to request a renewal twice a day. The certificate only gets renewed if it's under 30 days from expiration. Checking twice a day is a relatively safe way to check and get around potential timing bugs. This default is very handy for a typical installation.

However, since we have some unique needs with HAProxy, we'll use a slightly different CRON task for this use case.

The Problems

The first hurdle to get around arises because LetsEncrypt authorizes a certificate for a server by requesting a file via an HTTP(S) request. However, HAProxy is not a web server. It won't serve files by itself - it will only redirect a request to another location. Our application servers won't be able to handle this authorization request.

Since we want our SSL certificate on the load balancer (SSL Termination), our goal is to find a way to have HAProxy recognize a request from LetsEncrypt and route it to a web service that will respond with the response LetsEncrypt needs to authorize the certificate.

LetsEncrypt comes with it's own built-in web server listener for just such a use case, so we can accomplish this!

The second hurdle is that HAProxy expects an SSL certificate to all be in one file which includes the certificate chain, the root certificate, and the private key. HAProxy has the private key in a separate file, so our last step is to combine the files into something HAProxy can read.

Finally we'll also solve the issue of automating renewals given the above constraints.

The Workflow

There are two actions we ask of LetsEncrypt:

1. Request a new certificate
2. Renew an existing certificate

After each step above, we also need to combine the resulting certificate files into the format HAProxy wants.

Let's see those two scenarios, and then see how to combine the certificate into one file.

HAProxy Setup

When we request a new certificate, LetsEncrypt will request the authorization file (a URI like /.well-known/acme-challenge/random-hash-here). This request will happen over port 80, since there's presumably no certificate setup yet.

Interestingly, if HAProxy is listening on port 443, LetsEncrypt may attempt to authorize over it. So, when we create a new certificate, we need HAProxy to only be listening on port 80.

Another issue: HAProxy is listening on port 80. However, we need LetsEncrypt to setup it's stand-alone server to listen for authorization requests. It will default to port 80 as well, causing a conflict as only one process can listen on a port at a time. So we need to tell LetsEncrypt to listen on another port!

Within HAProxy, we can ask if the incoming HTTP request contains the string /.well-known/acme-challenge. In the coniguration below, if HAProxy sees that the request does include that URI, it will route the request to LetsEncrypt. Otherwise, it will route the request to any servers in the load balancer rotation as normal.

# The frontend only listens on port 80
# If it detects a LetsEncrypt request, is uses the LE backend
# Else it goes to the default backend for the web servers
frontend fe-scalinglaravel
    bind *:80

    # Test URI to see if its a letsencrypt request
    acl letsencrypt-acl path_beg /.well-known/acme-challenge/
    use_backend letsencrypt-backend if letsencrypt-acl

    default_backend be-scalinglaravel

# LE Backend
backend letsencrypt-backend
    server letsencrypt 127.0.0.1:8888

# Normal (default) Backend
# for web app servers
backend be-scalinglaravel
    # Config omitted here

Once that's setup within HAProxy, we can reload it (sudo service haproxy reload) and then move on to running LetsEncrypt.

New Certificates

The command to get a new certificate from LetsEncrypt that we will use is this:

sudo certbot certonly --standalone -d demo.scalinglaravel.com \
    --non-interactive --agree-tos --email admin@example.com \
    --http-01-port=8888

Lets roll through what this does:

1. --standalone - Create a stand-alone web server to listen for the cert authorization HTTP request
2. -d demo.scalinglaravel.com - The domain we're creating a cert for. You can use multiple -d flags for multiple domains for a single certificate. The domain(s) must route to the server we're creating a cert for (DNS must be setup for the domain).
3. --non-interactive --agree-tos --email admin@example.com - Make this non-interactive by saying as much, agreeing to the TOS, and informing LetsEncrypt of the email to use to send "YOUR CERT IS EXPIRING" notifications.
4. --http-01-port=8888 - The Magic™. This tells the stand-alone server to listen on port 8888. Note that LetsEncrypt will still send the authorization HTTP request over port 80. However the listener is expecting a proxy (such as our HAProxy server) to route the request to it over port 8888. The flag is http-01 because it expects an HTTP request, NOT an HTTPS request.

Renewing Certificates

If we are renewing a certificate, that likely means that there's a valid HTTPS certificate in use. We just need LetsEncrypt to do the same process as above to renew it. However, there's a few key differences:

1. HAProxy is presumably listening on port 443 for SSL connections, and LetsEncrypt is going to send an authorization request over HTTPS instead of HTTP.
2. The stand-alone server will expect an HTTPS (TLS, technically) request into it instead of a plain HTTP request.

So, the HAProxy setup will be almost the same, except this time it will be listening on port 443.

We'll cover setting up the HAProxy configuration for SSL in a bit.

frontend fe-scalinglaravel
    bind *:80

    # This is our new config that listens on port 443 for SSL connections
    bind *:443 ssl crt /etc/ssl/demo.scalinglaravel.com/demo.scalinglaravel.com.pem

    # New line to test URI to see if its a letsencrypt request
    acl letsencrypt-acl path_beg /.well-known/acme-challenge/
    use_backend letsencrypt-backend if letsencrypt-acl

    default_backend be-scalinglaravel

# LE Backend
backend letsencrypt-backend
    server letsencrypt 127.0.0.1:8888

# Normal (default) Backend
# for web app servers
backend be-scalinglaravel
    # Config omitted here

Note that LetsEncrypt's stand-alone server is still listening on port 8888, even though it's expecting a TLS connection. That's fine, the port number doesn't actually matter. The only change here is that HAProxy is listening for SSL connections as well.

Here's how to renew a certificate with LetsEncrypt:

sudo certbot renew --tls-sni-01-port=8888

That's it! We use renew, but this time we tell it to expect a tls connection and to contune listening for in on port 8888 (again).

SSL Certificates and HAProxy

HAProxy needs an ssl-certificate to be one file, in a certain format. To do that, we create a new directory where the SSL certificate that HAProxy reads will live. Then we output the "live" (latest) certificates from LetsEncrypt and dump that output into the certificate file for HAProxy to use:

sudo mkdir -p /etc/ssl/demo.scalinglaravel.com

sudo cat /etc/letsencrypt/live/demo.scalinglaravel.com/fullchain.pem \
    /etc/letsencrypt/live/demo.scalinglaravel.com/privkey.pem \
    | sudo tee /etc/ssl/demo.scalinglaravel.com/demo.scalinglaravel.com.pem

The /etc/letsencrypt/live/your-domain-here.tld directory will contain symlinks to your current, most up-to-date certificate.

So, we make sure a directory exists for our certificate, and then we concatenate the contents of the fullchain.pem file (certificate and certificate chain) and the private key privkey.pem file. We put the outputs into the file demo.scalinglaravel.com.pem. The order we concatenate the files matter (fullchain followed by private key).

The HAProxy configuration, as we saw, uses that new file:

frontend fe-scalinglaravel
    bind *:80

    # This is our new config that listens on port 443 for SSL connections
    bind *:443 ssl crt /etc/ssl/demo.scalinglaravel.com/demo.scalinglaravel.com.pem

    # omitting the rest of the config...

Automating Renewal

To automate renewal of our certificate, we need to repeat the above steps:

1. Get a new certificate
2. Create the new certificate file for HAProxy to use

By default, LetsEncrypt creates a CRON entry at /etc/cron.d/certbot. The entry runs twice a day (by default, LetsEncrypt will only renew the certificate if its expiring within 30 days).

What I like to do is to run a bash script that's run monthly, and to force a renewal of the certificate every time.

We can start by editing the CRON file to run a script monthly:

0 0 1 * * root bash /opt/update-certs.sh

That runs on the zeroth minute of the zeroth hour (midnight on whatever timezone your server is set to, likely UTC) on the first day of every month.

The bash file referenced in the CRON task (/opt/update-certs.sh) looks like this:

#!/usr/bin/env bash

# Renew the certificate
certbot renew --force-renewal --tls-sni-01-port=8888

# Concatenate new cert files, with less output (avoiding the use tee and its output to stdout)
bash -c "cat /etc/letsencrypt/live/demo.scalinglaravel.com/fullchain.pem /etc/letsencrypt/live/demo.scalinglaravel.com/privkey.pem > /etc/ssl/demo.scalinglaravel.com/demo.scalinglaravel.com.pem"

# Reload  HAProxy
service haproxy reload

This does all the steps we ran before. The only difference is that I use --force-renewal to have LetsEncrypt renew the certificate monthly. This way is a bit simpler to reason about and won't fall victim to potential timing bugs that running twice per day attempted to get around.

Enforcing HTTPS

This is not related to LetsEncrypt, but rather to your SSL implementation.

If you want to enforce SSL usage in HAProxy, you can also do that without affecing LetsEncrypt's ability to renew certificate:

frontend fe-scalinglaravel
    bind *:80
    bind *:443 ssl crt /etc/ssl/demo.scalinglaravel.com/demo.scalinglaravel.com.pem

    # Redirect if HTTPS is *not* used
    redirect scheme https code 301 if !{ ssl_fc }

    acl letsencrypt-acl path_beg /.well-known/acme-challenge/
    use_backend letsencrypt-backend if letsencrypt-acl

    default_backend be-scalinglaravel

This states that if the frontend connection was not using SSL, then return a 301 redirect to the same URI, but with "https".

docker run --it --rm -v $(pwd):/var/www/html \
    -w /var/www/html \
    shippingdocker/app:latest \
    composer create-project laravel/laravel application

This shares our current directory into the /var/www/html directory in the container, and then runs composer create project... to get Composer to add a Laravel project into a new directory named application.

We then update the application .env file to point MySQL to hostname mysql and run some migrations. It works!

The containers are both running within the same Docker network as described in the last video, and as described further in this video.

We can see we have php 7.0 available out of the box:

sudo apt-cache show php-cli

Instead of using that, we'll start by installing the latest PHP 7.1, via the populate PHP repository.

# Add repository and update local cache of available packages
sudo add-apt-repository -y ppa:ondrej/php
sudo apt-get update

# Search for packages starting with PHP, 
# we'll see php7.1-* packages available
sudo apt-cache search -n php*

# Install PHP-FPM, PHP-CLI and modules
sudo apt-get install -y php7.1-fpm php7.1-cli php7.1-curl php7.1-mysql php7.1-sqlite3 \
    php7.1-gd php7.1-xml php7.1-mcrypt php7.1-mbstring php7.1-iconv

Once that's installed, we can see some similar conventions from Nginx (and other software in Debian/Ubuntu).

SAPI

PHP on Debian/Ubuntu is divided by version and Server Application Programming Interface. A SAPI is the context in which PHP is run. The most common are:

• cli - when running on the command line
• fpm - when fulfilling a web request via fastcgi
• apache2 - when run in Apache's mod-php

Configuration

We can see the configuration split between version and SAPI by checking the file paths within /etc:

cd /etc/php
ls -lah

> ... 5.6/
> ... 7.0/
> ... 7.1/

cd 7.1
ls -lah

> ... cli/
> ... fpm/

Within each SAPI directory (e.g. cli or fpm), there is a php.ini file and a conf.d directory. We can edit php.ini per SAPI and use symlinks within the conf.d directory to enable or disable modules per SAPI.

Modules

PHP on Debian/Ubuntu use Symlinks to decide which ones are loaded per SAPI. All module configuration files are located in /etc/php/<version>/mods-available, and then loaded in via symlinks at /etc/php/<version>/<sapi>/conf.d.

Nginx

Once PHP is installed, we can configure Nginx to send PHP requests off to PHP-FPM:

server {
    listen 80;

    root /var/www/html;

    server_name _;

    index index.html index.htm index.debian-default.html index.php;

    location / {
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location ~ \.php$ {
        incude snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php7.1-fpm.sock;
    }
}

Once edits are complete we can test Nginx and reload:

sudo nginx -t
sudo service nginx reload

In the video, I show you some behavior around the above configuration. Most notably, the try_files configuration allows for "pretty URLs", meaning we don't need to add index.php into the URL within our browser for Nginx to use the index.php file.

The above configuration file will search for php files within the /var/www/html directory and send requests to PHP-FPM if a file is requested that ends in the .php extension.

First we installed Composer so we can get PHP dependencies:

# Become user root
sudo su

# Pipe the composer installer to php, and pass the installer some flags
curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

GitHub

Next, we want to get a Laravel project from Github.

We'll need access to Github. I chose to create a Deploy Key within Github, so the server has read-only access to a specific repository.

# Create an ssh key in /home/fideloper/.ssh
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -C "sfh-start-here"
cat ~/.ssh/id_rsa.pub
# Copy the output into a new Deploy key within Github, under the repository settings

# Test our connection to github
ssh -T git@github.com

We copy the contents of the public at/home/fideloper/.ssh/id_rsa.pub to Github while creating the Deploy key.

Then we can clone the repository. We clone it into user fideloper's home directory since we have permission to write new files there since we are logged in as user fideloper.

# Delete old webroot, which only had an index.php file in it
# We'll put our laravel application in this location
sudo rm -rf /var/www/html

# Ensure we have git
which git
git --version
# sudo apt-get install -y git

# Go to our home directory and clone the repository into a new directory named "html"
cd ~
git clone https://github.com/Servers-for-Hackers/server-start-here html

Nginx

Within the /etc/nginx/sites-available/default file, we update the root to point to the Laravel web root, which is the public directory.

Edit the file /etc/nginx/sites-available/default to update the root directive:

# Change:
root /var/www/html;

# To:
root /var/www/html/public;

Then test the change and reload Nginx:

sudo nginx -t
sudo service nginx reload

Application

We're ready to setup the application. First, we'll move it from user fideloper's home directory, to the /var/www/html location that Nginx expects web files to live in.

Since the Laravel application contains a public directory meant to be the web root, our change to the Nginx configuration will be correct when it points to /var/www/html/public.

# Put the application in the /var/www directory
sudo mv ~/html /var/www/

# Create  a new .env file
cd /var/www/html
cp .env.example .env

# Install zip/unzip so composer can get Git-based dependencies
# from "dist" instead of having to clone each repository (slow!)
sudo apt-get install -y zip unzip

# Install composer dependencies
composer install

# Generate a new application key in the .env file
php artisan key:generate

# Ensure files are writable (particularly `storage` and `bootstrap` need to be writable by Laravel!)
# Otherwise we'll get the blank white screen of death

# We can see that PHP is running as user/group "www-data"
ps aux | grep php

# So we change our web files to that user/group, thus letting PHP write to those locations
sudo chown -R www-data: /var/www/html

SSL Termination is a common setup, however there are setups that keep the connection encrypted all the way to the application servers.

We'll get an SLL certificate for free using Lets Encrypt.

So, first, we'll install Lets Encrypt!

Creating a certificiate here will work because we don't disallow access to directories that start with a period, but if you do like on many standard setups, see the video on using Lets Encrypt for more details.

cd /opt
sudo git clone https://github.com/certbot/certbot
cd certbot
./certbot-auto -h

OK, so, certbot is installed but if we have it attempt to connect to our server, Nginx will attempt to proxy the authentication request to our application servers, but we don't want that!

So, let's setup Nginx to work with Lets Encrypt requests:

upstream app {
    server 172.31.9.200:80;
    server 172.31.0.30:80;
}

server {
    listen 80 default_server;

    server_name lb.serversforhackers.com;    

    charset utf-8;

    # Requests to /.well-known should look for local files
    location /.well-known {
        root /var/www/html;
        try_files $uri $uri/ =404;
    }

    # All other requests get load-balanced
    location / {
        include proxy_params;
        proxy_pass http://app;
        proxy_redirect off;

        # Handle Web Socket connections
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

The details of what's going on here is explained more in the Let's Encrypt video! This includes how to have the certificate automatically update.

We need to test this config and have Nginx suck it in:

sudo nginx -t
sudo service nginx reload

Now we're ready to install our certificate!

cd /opt/certbot

# Let's create the cert
sudo ./certbot-auto certonly --webroot -w /var/www/html \
    -d lb.serversforhackers.com \
    --non-interactive --agree-tos --email admin@example.com

Finally, we can update our Nginx configuration to use the SSL (this is a bit different than the video, which doesn't cover ensuring Let's Encrypt continues to work after the SSL is installed):

upstream app {
    server IPHERE:80;
    server IPHERE:80;
}

server {
    listen 80 default_server;
    server_name lb.serversforhackers.com;

    # Requests to /.well-known should look for local files
    location /.well-known {
        root /var/www/html;
        try_files $uri $uri/ =404;
    }

    # All other requests get load-balanced
    location / {
        return 301 https://$server_name$request_uri;
    }
}

server {
    listen 443 ssl default_server;

    server_name lb.serversforhackers.com;

    ssl_protocols              TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers                ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS;
    ssl_prefer_server_ciphers  on;
    ssl_session_cache          shared:SSL:10m;
    ssl_session_timeout        24h;
    keepalive_timeout          300s;

    ssl_certificate      /etc/letsencrypt/live/lb.serversforhackers.com/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/lb.serversforhackers.com/privkey.pem;

    charset utf-8;

    location / {
        include proxy_params;
        proxy_pass http://app;
        proxy_redirect off;

        # Handle Web Socket connections
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

In this setup, all requests to port 80 are redirected to port 443 to use the SSL certificate. If a request on port 80 is sent to /.well-known, it should function.

Finally we can test that out and reload Nginx:

sudo nginx -t
sudo service nginx reload

We should then be able to access our server over SSL using https://lb.serversforhackers.com.

The environment:

Here's what we're using in the video

• Ubuntu 16.04 on AWS.
• Ubuntu 16.04 AMI's found here, if you're curious.
• Nginx
• Certbot (e.g. Letsencrypt)

I had a real domain pointing to this server: tutorial.serverops.io.

Initial Setup:

I ran the following just to get the server updated and nginx installed:

sudo apt update
sudo apt upgrade -y
sudo apt install -y nginx

When I went to http://tutorial.serverops.io in the browser, I could then see the default nginx site. Yay!

Nginx Security

Many people protect dot-files in your Nginx server configuration. This means access to any file or folder proceeded with a dot returns an access denied response. This rule in Nginx often looks like this:

location ~* (?:^|/)\. {
    deny all;
}

This protects url's such as: http://example.com/.git/... - which is good - that's likely not something you want exposed to the public internet!

LetsEncrypt, however, uses a folder named .well-known to validate that you have access to the domain you're attempting to create a certificate for. To allow the use of this directory while still protecting system directories, use the following two Nginx rules:

location ~* (?:^|/)\.well-known {
    allow all;
}

location ~* (?:^|/)\. {
    deny all;
}

Update: April 6, 2017 - Using Nginx 1.10.3 I had to use the following configuration to accomplish the above (Github issue reference):

location ^~ /.well-known/acme-challenge/ {
    allow all;
}

location ~* (?:^|/)\. {
    allow all;
}

Install Letsencrypt

Letsencrypt used to have you install a command line tool called, appropriately, "letsencrypt". It's since changed to the simpler "certbot".

Ubuntu 16.04 has a package for "letsencrypt" (currently for version 0.4.1-1):

$ apt show certbot # No results
$ apt show letsencrypt
Package: letsencrypt
Version: 0.4.1-1
Priority: optional
Section: universe/web
Source: python-letsencrypt
Origin: Ubuntu
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>
Original-Maintainer: Debian Lets Encrypt <letsencrypt-devel@lists.alioth.debian.org>
Bugs: https://bugs.launchpad.net/ubuntu/+filebug
Installed-Size: 24.6 kB
Depends: dialog, python-letsencrypt (= 0.4.1-1), python:any (>= 2.7~)
Suggests: python-letsencrypt-apache, python-letsencrypt-doc
Homepage: https://letsencrypt.org/
Download-Size: 10.9 kB
APT-Sources: http://us-east-1.ec2.archive.ubuntu.com/ubuntu xenial/universe amd64 Packages
Description: Lets Encrypt main client...

The latest certbot release as of this writing if 0.7.0. Let's not settle for an old version!

This was actually 0.8.0 the next day - development moves fast on it!

To install a newer version:

sudo apt install -y git
cd /opt
sudo git clone https://github.com/certbot/certbot
cd certbot
./certbot-auto -h

We'll use the certbot-auto command.

Install a Certificate

Letsencrypt has a few "modules" which basically boils down to "how do I setup an SSL certificate for you".

In all cases, letsencrypt needs to be able to ping your server over HTTP to confirm that your domain points to the server you're installing the certificate on.

Standalone

One way letsencrypt does this is with the "standalone" module, which spins up a web server listening on port 80. The issue there may or may not be obvious to you - We already have a web server bound to port 80. There can be only one.

This means turning off the web server, running lets encrypt, and then turning it back on. It's a viable option (and is the way I've done it in the passed), but let's do better.

Webroot

I'm going to go with the "webroot" module, which is similar to how Google webmaster tools proves ownership. It creates a file in your web root that letsencrypt can check for, which then proves that you are actually installing an SSL on the server it can reach from your domain.

Note that this gets the certificate but does not install it. There are apache and nginx modules that can do this. The Apache module seems stable, but they plaster a scary "experimental" warning on the Nginx module, so I haven't used it.

Following the docs on the webroot option, I use the following command:

# Don't forget we're in /opt
# and all files are owned by root currently
cd /opt/certbot

# Run as root, which avoids python dependencies
# from trying to install in /home/ubuntu as user root
sudo su

# Note that I know and am using Nginx's default webroot location
# which I grabbed from /etc/nginx/sites-available/default
# Also note that --non-interactive --agree-tos --email <email> is required
# to avoid prompts (great for automating this!)
# Also remember we're running as root
./certbot-auto certonly --webroot -w /var/www/html \
    -d tutorial.serverops.io \
    --non-interactive --agree-tos --email admin@example.com

I used tmux to split my terminal and ran sudo tail -f /var/log/nginx/access.log to see the access log as I ran the above command. I saw this:

66.133.109.36 - - [01/Jun/2016:15:30:25 +0000] "GET /.well-known/acme-challenge/-IeTRWj2zRKRxim2ngMPUP3_Nvt6DN_TR-fLXUQMfHk HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)"

And the command itself outputs this:

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at
   /etc/letsencrypt/live/tutorial.serverops.io/fullchain.pem. Your
   cert will expire on 2016-08-30. To obtain a new or tweaked version
   of this certificate in the future, simply run certbot-auto again.
   To non-interactively renew *all* of your ceriticates, run
   "certbot-auto renew"
 - If you lose your account credentials, you can recover through
   e-mails sent to admin@example.com.
 - Your account credentials have been saved in your Certbot
   configuration directory at /etc/letsencrypt. You should make a
   secure backup of this folder now. This configuration directory will
   also contain certificates and private keys obtained by Certbot so
   making regular backups of this folder is ideal.
 - If you like Certbot, please consider supporting our work by:

   Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
   Donating to EFF:                    https://eff.org/donate-le

We can check out that directory it mentions as well:

# Still running as user root
$ ls -lah /etc/letsencrypt/live/tutorial.serverops.io
total 8
drwxr-xr-x 2 root root 4096 Jun  1 15:30 ./
drwx------ 3 root root 4096 Jun  1 15:30 ../
lrwxrwxrwx 1 root root   45 Jun  1 15:30 cert.pem -> ../../archive/tutorial.serverops.io/cert1.pem
lrwxrwxrwx 1 root root   46 Jun  1 15:30 chain.pem -> ../../archive/tutorial.serverops.io/chain1.pem
lrwxrwxrwx 1 root root   50 Jun  1 15:30 fullchain.pem -> ../../archive/tutorial.serverops.io/fullchain1.pem
lrwxrwxrwx 1 root root   48 Jun  1 15:30 privkey.pem -> ../../archive/tutorial.serverops.io/privkey1.pem

Great, we can see those are symlinked to some other files. These get updated when we renew our certificates, but it's the symlink we use in our Nginx configuration, so we don't need to update web server configuration when we renew!

Nginx Configuration

Let's setup our Nginx configuration to use our new SSL certificate.

We'll edit /etc/nginx/sites-available/default and uncomment the SSL configuration portion.

server {
    listen 80 default_server;
    listen 443 ssl default_server;

    ssl_certificate      /etc/letsencrypt/live/tutorial.serverops.io/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/tutorial.serverops.io/privkey.pem;

    # Remaining removed for brevity

We use the fullchain.pem so we have the root certificate and the intermediary authorities. And of course we use the private key used to generate the certificate.

Once the changes are added, we can test Nginx and reload the configuration, assuming it doesn't find any issues.

sudo service nginx configtest
sudo service nginx reload

Now head to our domain with "https://" (https://tutorial.serverops.io) and we'll see the green lock of bliss!

Renewal

Letsencrypt certificates are good for only 90 days, so you need to renew periodically. This is hella easy.

# again, as user root
cd /opt/certbot
./certbot-auto renew --webroot -w /var/www/html

This will renew any certificates expiring within 30 days. You can set this as a cron task and run it as much as you'd like (altho I'd run it on the first of each month personally).

Here's an example /etc/cron.monthly/letsencrypt bash file (make sure it's executable - sudo chmod u=rwx,go=rx /etc/cron.monthly/letsencrypt):

#!/usr/bin/env bash

cd /opt/certbot
./certbot-auto renew --webroot \
    --noninteractive \
    -w /var/www/html \
    --post-hook "service nginx reload"

Update: I've found that in some cases, the certificate does not renew (due to how and when Certbot decides a certificate is not yet ready for renewal). To counter-act this, I just add the --force-renewal flag:

#!/usr/bin/env bash

cd /opt/certbot
./certbot-auto renew --webroot \
    --force-renewal \
    --noninteractive \
    -w /var/www/html \
    --post-hook "service nginx reload"

Then (noted above, but repeated here as well) we need to make sure the script is executable:

sudo chmod +x /etc/cron.monthly/letsencrypt

We use the webroot module again and let is know the webroot path. Then we also set a post-hook to reload Nginx, to ensure it sucks in the new certificate.

If you want to test the renewal immediately, add the --force-renewal flag!

That's it! Your certificates will get renewed.

1. Pass-thru any undefined commands to docker-compose
2. Run docker-compose ps if we don't pass any arguments to the develop script
3. Create a series of commands such as artisan, composer, yarn, and so on, setting the script up to allow us to pass in any arguments to those commands.

The commands we create all allow us to run the corresponding commands within our running containers!

#!/usr/bin/env bash

if [ $# -gt 0 ]; then

    if [ "$1" == "start" ]; then
        docker-compose up -d

    elif [ "$1" == "stop" ]; then
        docker-compose down

    elif [ "$1" == "artisan" ] || [ "$1" == "art" ]; then
        shift 1
        docker-compose exec \
            app \
            php artisan "$@"

    elif [ "$1" == "composer" ] || [ "$1" == "comp" ]; then
        shift 1
        docker-compose exec \
            app \
            composer "$@"

    elif [ "$1" == "test" ]; then
        shift 1
        docker-compose exec \
            app \
            ./vendor/bin/phpunit "$@"

    elif [ "$1" == "npm" ]; then
        shift 1
        docker-compose run --rm \
            node \
            npm "$@"

    elif [ "$1" == "yarn" ]; then
        shift 1
        docker-compose run --rm \
            node \
            yarn "$@"

    elif [ "$1" == "gulp" ]; then
        shift 1
        docker-compose run --rm \
            node \
            ./node_modules/.bin/gulp "$@"
    else
        docker-compose "$@"
    fi

else
    docker-compose ps
fi

We can use this helper script like so:

# Run docker-compose ps
./develop ps

# Run docker-compose exec app bash
./develop exec app bash

# Run docker-compose exec app php artisan make:controller SomeController
./develop art make:controller SomeController

# Run docker-compose exec app composer require predis/predis
./develop composer require predis/predis

# Run docker-compose exec app ./vendor/bin/phpunit
./develop test

# Run commands against the node container:
./develop yarn ...
./develop npm ...
./develop gulp ...

And of course you can make your own commands, or make it more complex. For example, Laravel Vessel runs exec if the containers are running and run if the containers are not running, among other more complex use cases.

This makes running command witin our Docker container super easy. Running all of those docker-compose commands are a real pain!

We also move our application files up a level so the Docker files are all within the same directory.

I don't show this in the repository for this video series, as I don't want to pin a specific Laravel version to it, but it's easy to change as I show in the video!

develop Script

We can make a bash helper, which I name develop:

touch develop
chmod +x develop

And we can start our develop helper with simply this:

#!/usr/bin/env bash

We'll add useful items to it in the next video.

version: '3'
services:
  app:
    build:
      context: ./docker/app
      dockerfile: Dockerfile
    image: shippingdocker/app:latest
    networks:
     - appnet
    volumes:
     - .:/var/www/html
    ports:
     - ${APP_PORT}:80
    working_dir: /var/www/html
  cache:
    image: redis:alpine
    networks:
     - appnet
    volumes:
     - cachedata:/data
  db:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: homestead
      MYSQL_USER: homestead
      MYSQL_PASSWORD: secret
    ports:
     - ${DB_PORT}:3306
    networks:
     - appnet
    volumes:
     - dbdata:/var/lib/mysql
  node:
    build:
      context: ./docker/node
      dockerfile: Dockerfile
    image: shippingdocker/node:latest
    networks:
     - appnet
    volumes:
     - .:/opt
    working_dir: /opt
    command: echo hi
networks:
  appnet:
    driver: bridge
volumes:
  dbdata:
    driver: local
  cachedata:
    driver: local

We build this image also, so we can add things like git and yarn to it. This uses the official node base image. Here's the Dockerfile:

FROM node:latest

LABEL maintainer="Chris Fidao"

RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - \
    && echo "deb http://dl.yarnpkg.com/debian/ stable main" > /etc/apt/sources.list.d/yarn.list \
    && apt-get update \
    && apt-get install -y git yarn \
    && apt-get -y autoremove \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

Docker Compose takes care of building this image for us when we first spin up the environment.

The syntax is: ${SOME_VAR_NAME}.

These specifically are environment variables.

First, let's set our docker-compose.yml file to read two variables:

version: '3'
services:
  app:
    build:
      context: ./docker/app
      dockerfile: Dockerfile
    image: shippingdocker/app:latest
    networks:
     - appnet
    volumes:
     - .:/var/www/html
    ports:
     - ${APP_PORT}:80
    working_dir: /var/www/html
  cache:
    image: redis:alpine
    networks:
     - appnet
    volumes:
     - cachedata:/data
  db:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: homestead
      MYSQL_USER: homestead
      MYSQL_PASSWORD: secret
    ports:
     - ${DB_PORT}:3306
    networks:
     - appnet
    volumes:
     - dbdata:/var/lib/mysql
  node:
    build:
      context: ./docker/node
      dockerfile: Dockerfile
    image: shippingdocker/node:latest
    networks:
     - appnet
    volumes:
     - .:/opt
    working_dir: /opt
    command: echo hi
networks:
  appnet:
    driver: bridge
volumes:
  dbdata:
    driver: local
  cachedata:
    driver: local

We have APP_PORT and DB_PORT.

We can set those in two ways:

First: We can export the variables so they're available to sub-processes:

export APP_PORT=8080
export DB_PORT=33060

# Our `docker-compose.yml` file will use the above variables
docker-compose up -d

Second: We can set them inline as we run the docker-compose command.

APP_PORT=8080 DB_PORT=33060 docker-compose up -d

.env File

We have another option too! Docker Compose will read a .env file and import variables from it!

Here's an example .env file:

APP_PORT=8080
DB_PORT=33060

If that's in the same directory as the docker-compose.yml file, then we can just run docker-compose commands, knowing it will pick up those variables:

docker-compose up -d

If our exec command doesn't work with a working directory setting, we can run a command that cd's into a directory and runs the command we want all in one shot:

docker exec -it app bash -c "cd /var/www/html && php artisan list"

We can update our docker-compose.yml file to add a working_dir. This should let us avoid doing the above "hack"!

version: '3'
services:
  app:
    build:
      context: ./docker/app
      dockerfile: Dockerfile
    image: shippingdocker/app:latest
    networks:
     - appnet
    volumes:
     - ./application:/var/www/html
    working_dir: /var/www/html
  cache:
    image: redis:alpine
    networks:
     - appnet
    volumes:
     - cachedata:/data
  db:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: homestead
      MYSQL_USER: homestead
      MYSQL_PASSWORD: secret
    networks:
     - appnet
    volumes:
     - dbdata:/var/lib/mysql
networks:
  appnet:
    driver: bridge
volumes:
  dbdata:
    driver: local
  cachedata:
    driver: local

Then commands like:

docker-compose exec app php artisan list

...should just work!

version: '3'
services:
  app:
    build:
      context: ./docker/app
      dockerfile: Dockerfile
    image: shippingdocker/app:latest
    networks:
     - appnet
    volumes:
     - ./application:/var/www/html
  cache:
    image: redis:alpine
    networks:
     - appnet
    volumes:
     - cachedata:/data
  db:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: homestead
      MYSQL_USER: homestead
      MYSQL_PASSWORD: secret
    networks:
     - appnet
    volumes:
     - dbdata:/var/lib/mysql
networks:
  appnet:
    driver: bridge
volumes:
  dbdata:
    driver: local
  cachedata:
    driver: local

version: '3'
services:
  cache:
    image: redis:alpine
    networks:
     - appnet
    volumes:
     - cachedata:/data
  db:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: homestead
      MYSQL_USER: homestead
      MYSQL_PASSWORD: secret
    networks:
     - appnet
    volumes:
     - dbdata:/var/lib/mysql
networks:
  appnet:
    driver: bridge
volumes:
  dbdata:
    driver: local
  cachedata:
    driver: local

Here we added the volumes: section to the cache and db services.

version: '3'
services:
  cache:
    image: redis:alpine
    networks:
     - appnet
  db:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: homestead
      MYSQL_USER: homestead
      MYSQL_PASSWORD: secret
    networks:
     - appnet
networks:
  appnet:
    driver: bridge
volumes:
  dbdata:
    driver: local
  cachedata:
    driver: local

Docker Compose lets us manage the life cycle of our Docker environment, including Volumes, Networks, and of course helping us manage multiple containers that can work together.

We'll start defining some simple thing in our docker-compose.yml file:

version: '3'
services:
networks:
  appnet:
    driver: bridge
volumes:
  dbdata:
    driver: local
  cachedata:
    driver: local

In the next video we'll begin to fill out the services section, where we define our containers.

List volumes:

docker volume ls

Create a volume named dbdata:

docker volume create dbdata

Then we can use this volume when we spin up a container, such as MySQL:

docker run --rm -d \
    --name=mysql \
    --network=appnet \
    -v dbdata:/var/lib/mysql \
    -e MYSQL_ROOT_PASSWORD=root \
    -e MYSQL_DATABASE=homestead \
    -e MYSQL_USER=homestead \
    -e MYSQL_USER_PASSWORD=secret \
    mysql:5.7

Here we used the -v flag and shared our named volume dbdata and bound it to /var/lib/mysql within the container.

We can create and destroy MySQL containers as much as we want. As long as we share the dbdata volume, that database data will persist (assuming, of course, we don't delete the volume via docker volume rm dbdata)!

Create a Network

We can create a network for containers to be added to:

# List networks
docker network ls

# Create a network
docker network create appnet

Then we can add containers to that network as we run them:

docker run --rm -d \
    --name=app \
    --network=appnet\
     shippingdocker/app:latest

docker run --rm -d \
    --name=mysql \
    --network=appnet \
    -e MYSQL_ROOT_PASSWORD=root \
    -e MYSQL_DATABASE=homestead \
    -e MYSQL_USER=homestead \
    -e MYSQL_USER_PASSWORD=secret \
    mysql:5.7

This creates two containers (see the videos for details on the MySQL container), and adds them into the new network appnet.

The containers then can reference eachother - the hostname for each container is taken from the --name given to the container. This lets the app container talk to mysql over hostname mysql.

Within a container, you can run getent hosts mysql to see the hostname resolution of hostname mysql.

Entrypoint Script

First, we make a script to act as our ENTRYPOINT:

#!/usr/bin/env bash

##
# Ensure /.composer exists and is writable
#
if [ ! -d /.composer ]; then
    mkdir /.composer
fi

chmod -R ugo+rw /.composer

##
# Run a command or start supervisord
#
if [ $# -gt 0 ];then
    # If we passed a command, run it
    exec "$@"
else
    # Otherwise start supervisord
    /usr/bin/supervisord
fi

This script allows us to do some pre-processing whenever a container is spun up. It defaults to running supervisord for us, but we also allow ourselves to run any command, just like we could before, by using the exec "$@" line if we pass any commands/arguments to the container.

Dockerfile

Then we use that in the Dockerfile by adding it to the image and setting it as our ENTRYPOINT script:

FROM ubuntu:18.04

LABEL maintainer="Chris Fidao"

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update \
    && apt-get install -y gnupg tzdata \
    && echo "UTC" > /etc/timezone \
    && dpkg-reconfigure -f noninteractive tzdata

RUN apt-get update \
    && apt-get install -y curl zip unzip git supervisor sqlite3 \
       nginx php7.2-fpm php7.2-cli \
       php7.2-pgsql php7.2-sqlite3 php7.2-gd \
       php7.2-curl php7.2-memcached \
       php7.2-imap php7.2-mysql php7.2-mbstring \
       php7.2-xml php7.2-zip php7.2-bcmath php7.2-soap \
       php7.2-intl php7.2-readline php7.2-xdebug \
       php-msgpack php-igbinary \
    && php -r "readfile('http://getcomposer.org/installer');" | php -- --install-dir=/usr/bin/ --filename=composer \
    && mkdir /run/php \
    && apt-get -y autoremove \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* \
    && echo "daemon off;" >> /etc/nginx/nginx.conf

RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

ADD default /etc/nginx/sites-available/default
ADD supervisord.conf /etc/supervisor/conf.d/supervisord.conf
ADD php-fpm.conf /etc/php/7.2/fpm/php-fpm.conf
ADD start-container.sh /usr/bin/start-container
RUN chmod +x /usr/bin/start-container

ENTRYPOINT ["start-container"]

And of course, we need to rebuild the image:

docker build -t shippingdocker/app:latest \
    -f docker/app/Dockerfile \
    docker/app

The only change we need to make:

PHP-FPM

In our php-fpm.conf file, adjust the error_log to error_log = /proc/self/fd/2.

Nginx

Nginx is easier - we can just adjust the Dockerfile by symlinking the nginx error and access logs to stdout and stderr:

FROM ubuntu:18.04

LABEL maintainer="Chris Fidao"

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update \
    && apt-get install -y gnupg tzdata \
    && echo "UTC" > /etc/timezone \
    && dpkg-reconfigure -f noninteractive tzdata

RUN apt-get update \
    && apt-get install -y curl zip unzip git supervisor sqlite3 \
       nginx php7.2-fpm php7.2-cli \
       php7.2-pgsql php7.2-sqlite3 php7.2-gd \
       php7.2-curl php7.2-memcached \
       php7.2-imap php7.2-mysql php7.2-mbstring \
       php7.2-xml php7.2-zip php7.2-bcmath php7.2-soap \
       php7.2-intl php7.2-readline php7.2-xdebug \
       php-msgpack php-igbinary \
    && php -r "readfile('http://getcomposer.org/installer');" | php -- --install-dir=/usr/bin/ --filename=composer \
    && mkdir /run/php \
    && apt-get -y autoremove \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* \
    && echo "daemon off;" >> /etc/nginx/nginx.conf

RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

ADD default /etc/nginx/sites-available/default
ADD supervisord.conf /etc/supervisor/conf.d/supervisord.conf
ADD php-fpm.conf /etc/php/7.2/fpm/php-fpm.conf

CMD ["nginx"]

And of course, we need to rebuild the image:

docker build -t shippingdocker/app:latest \
    -f docker/app/Dockerfile \
    docker/app

We grabbed a PHP-FPM file to put into Docker, and changed daemon to none. Here is file php-fpm.conf:

;;;;;;;;;;;;;;;;;;;;;
; FPM Configuration ;
;;;;;;;;;;;;;;;;;;;;;

; All relative paths in this configuration file are relative to PHP's install
; prefix (/usr). This prefix can be dynamically changed by using the
; '-p' argument from the command line.

;;;;;;;;;;;;;;;;;;
; Global Options ;
;;;;;;;;;;;;;;;;;;

[global]
; Pid file
; Note: the default prefix is /var
; Default Value: none
pid = /run/php/php7.2-fpm.pid

; Error log file
; If it's set to "syslog", log is sent to syslogd instead of being written
; into a local file.
; Note: the default prefix is /var
; Default Value: log/php-fpm.log
error_log = /proc/self/fd/2

; syslog_facility is used to specify what type of program is logging the
; message. This lets syslogd specify that messages from different facilities
; will be handled differently.
; See syslog(3) for possible values (ex daemon equiv LOG_DAEMON)
; Default Value: daemon
;syslog.facility = daemon

; syslog_ident is prepended to every message. If you have multiple FPM
; instances running on the same server, you can change the default value
; which must suit common needs.
; Default Value: php-fpm
;syslog.ident = php-fpm

; Log level
; Possible Values: alert, error, warning, notice, debug
; Default Value: notice
;log_level = notice

; If this number of child processes exit with SIGSEGV or SIGBUS within the time
; interval set by emergency_restart_interval then FPM will restart. A value
; of '0' means 'Off'.
; Default Value: 0
;emergency_restart_threshold = 0

; Interval of time used by emergency_restart_interval to determine when
; a graceful restart will be initiated.  This can be useful to work around
; accidental corruptions in an accelerator's shared memory.
; Available Units: s(econds), m(inutes), h(ours), or d(ays)
; Default Unit: seconds
; Default Value: 0
;emergency_restart_interval = 0

; Time limit for child processes to wait for a reaction on signals from master.
; Available units: s(econds), m(inutes), h(ours), or d(ays)
; Default Unit: seconds
; Default Value: 0
;process_control_timeout = 0

; The maximum number of processes FPM will fork. This has been designed to control
; the global number of processes when using dynamic PM within a lot of pools.
; Use it with caution.
; Note: A value of 0 indicates no limit
; Default Value: 0
; process.max = 128

; Specify the nice(2) priority to apply to the master process (only if set)
; The value can vary from -19 (highest priority) to 20 (lowest priority)
; Note: - It will only work if the FPM master process is launched as root
;       - The pool process will inherit the master process priority
;         unless specified otherwise
; Default Value: no set
; process.priority = -19

; Send FPM to background. Set to 'no' to keep FPM in foreground for debugging.
; Default Value: yes
daemonize = no

; Set open file descriptor rlimit for the master process.
; Default Value: system defined value
;rlimit_files = 1024

; Set max core size rlimit for the master process.
; Possible Values: 'unlimited' or an integer greater or equal to 0
; Default Value: system defined value
;rlimit_core = 0

; Specify the event mechanism FPM will use. The following is available:
; - select     (any POSIX os)
; - poll       (any POSIX os)
; - epoll      (linux >= 2.5.44)
; - kqueue     (FreeBSD >= 4.1, OpenBSD >= 2.9, NetBSD >= 2.0)
; - /dev/poll  (Solaris >= 7)
; - port       (Solaris >= 10)
; Default Value: not set (auto detection)
;events.mechanism = epoll

; When FPM is built with systemd integration, specify the interval,
; in seconds, between health report notification to systemd.
; Set to 0 to disable.
; Available Units: s(econds), m(inutes), h(ours)
; Default Unit: seconds
; Default value: 10
;systemd_interval = 10

;;;;;;;;;;;;;;;;;;;;
; Pool Definitions ;
;;;;;;;;;;;;;;;;;;;;

; Multiple pools of child processes may be started with different listening
; ports and different management options.  The name of the pool will be
; used in logs and stats. There is no limitation on the number of pools which
; FPM can handle. Your system will tell you anyway :)

; Include one or more files. If glob(3) exists, it is used to include a bunch of
; files from a glob(3) pattern. This directive can be used everywhere in the
; file.
; Relative path can also be used. They will be prefixed by:
;  - the global prefix if it's been set (-p argument)
;  - /usr otherwise
include=/etc/php/7.2/fpm/pool.d/*.conf

The important part is daemonize = no.

Then we can update the Dockerfile once again:

FROM ubuntu:18.04

LABEL maintainer="Chris Fidao"

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update \
    && apt-get install -y gnupg tzdata \
    && echo "UTC" > /etc/timezone \
    && dpkg-reconfigure -f noninteractive tzdata

RUN apt-get update \
    && apt-get install -y curl zip unzip git supervisor sqlite3 \
       nginx php7.2-fpm php7.2-cli \
       php7.2-pgsql php7.2-sqlite3 php7.2-gd \
       php7.2-curl php7.2-memcached \
       php7.2-imap php7.2-mysql php7.2-mbstring \
       php7.2-xml php7.2-zip php7.2-bcmath php7.2-soap \
       php7.2-intl php7.2-readline php7.2-xdebug \
       php-msgpack php-igbinary \
    && php -r "readfile('http://getcomposer.org/installer');" | php -- --install-dir=/usr/bin/ --filename=composer \
    && mkdir /run/php \
    && apt-get -y autoremove \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* \
    && echo "daemon off;" >> /etc/nginx/nginx.conf

ADD default /etc/nginx/sites-available/default
ADD supervisord.conf /etc/supervisor/conf.d/supervisord.conf
ADD php-fpm.conf /etc/php/7.2/fpm/php-fpm.conf

CMD ['supervisord']

Then we can rebuild the image again!

docker build -t shippingdocker/app:latest \
    -f docker/app/Dockerfile \
    docker/app