Drupal Pi

Drupal on Docker on a Raspberry Pi

This project is an offshoot of the Rasbperry Pi Dramble project, which helps install Drupal on a cluster ('Bramble') of Raspberry Pi computers.

This playbook/project makes setting up Drupal on a single Raspberry Pi a very easy/simple operation using Nginx and Docker Compose.

Set up the Raspberry Pi

Drupal requires as good a Raspberry Pi as you can afford. While Drupal will run okay on any Raspberry Pi, it's best to use a model 2 B or later (newer models have a snappy four-core processor and at least 1GB RAM).

Once you have your Raspberry Pi and a good microSD card (the fastest/best one you can get—see microSD Card Benchmarks!), you will need to do a few things to set up the Raspberry Pi and get it ready to run Drupal.

Set up on Raspberry Pi with Raspbian / GUI

These directions assume you're working directly on your Raspberry Pi, running Raspbian, with a keyboard and monitor attached:

1. Download the latest 'Raspbian' image from the Raspberry Pi Downloads page†.
2. Follow the image installation guide to transfer the image to your microSD card:
   1. Unmount the microSD card: diskutil unmountDisk /dev/disk2
   2. Write the image to the microSD card: pv yyyy-mm-dd-raspbian-stretch.img | sudo dd bs=1m of=/dev/rdisk2
3. Once Raspbian is loaded on the card, insert the card in your Pi, and plug in your Pi to boot it up.
4. Boot up the Raspberry Pi. Once booted, open the "Raspberry Pi Configuration" tool in Menu > Preferences.
   1. Change the pi user account password.
   2. Click OK, then reboot the Raspberry Pi.
5. Once rebooted, connect the Pi to your local network either via WiFi or wired ethernet.
6. Open the Terminal application (in the launcher or in Menu > Accessories > Terminal).
7. Install Ansible: sudo apt-get update && sudo apt-get install -y python3-dev python3-pip libyaml-dev libffi-dev && sudo pip3 install ansible
8. Test the Ansible installation: ansible --version (should output the Ansible version).

† If you plan on using your Pi as a headless Drupal server, you don't need all the extra software included with the default Raspbian image. I recommend you use the official 'Raspbian Lite' image instead; see the next section.

Set up on Raspberry Pi with Raspbian Lite / CLI

These directions assume you're working either directly on your Raspberry Pi, running Raspbian Lite, or remotely logged into the Pi via SSH:

1. Download the latest 'Raspbian Lite' image from the Raspberry Pi Downloads page†.
2. Follow the image installation guide to transfer the image to your microSD card:
   1. Unmount the microSD card: diskutil unmountDisk /dev/disk2
   2. Write the image to the microSD card: pv yyyy-mm-dd-raspbian-stretch-lite.img | sudo dd bs=1m of=/dev/rdisk2
   3. Ensure SSH is enabled by adding an 'ssh' file to the boot volume: touch /Volumes/boot/ssh
   4. If you need to enable WiFi headlessly, add a wpa_supplicant.conf file to the boot volume as well:
      1. Create the file: touch /Volumes/boot/wpa_supplicant.conf
      2. Add the contents:

         ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
         update_config=1
         country=US
         
         network={
             ssid="your-network-name"
             psk="your-network-password"
             key_mgmt=WPA-PSK
         }
         

3. Once Raspbian Lite is loaded on the card, insert the card in your Pi, and plug in your Pi to boot it up.
4. Boot up the Raspberry Pi. Once booted, log in (default username is pi and default password is raspberry), and run sudo raspi-config.
   1. Set a better password for the Pi's default user account.
   2. Scroll down to 'Finished', hit return, and reboot the Raspberry Pi.
5. Once rebooted, connect the Pi to your local network either via WiFi or wired ethernet.
6. Log back in (either on the Pi directly or via SSH).
7. Install Ansible: sudo apt-get update && sudo apt-get install -y python3-dev python3-pip libyaml-dev libffi-dev git && sudo pip3 install ansible
8. Test the Ansible installation: ansible --version (should output the Ansible version).

Install LEMP software stack and Drupal with Ansible and Docker

Installing using the Raspberry Pi

You need to download this repository to the Pi and run the included playbook to install and configure everything.

1. Clone the drupal-pi project: git clone https://github.com/geerlingguy/drupal-pi.git && cd drupal-pi
2. Copy example.inventory to inventory.
3. (Optional) Create a config.yml and override any settings from default.config.yml as needed.
4. Install required Ansible roles: ansible-galaxy install -r requirements.yml
5. Run the Ansible playbook: ansible-playbook -c local main.yml

After a few minutes, the playbook should complete successfully, and you should have Drupal running on your Raspberry Pi, accessible via http://localhost/

To be able to access the site from other computers on your network (e.g. by accessing http://www.drupalpi.test/, add an entry to your local hosts file like [ip-of-raspberry-pi] www.drupalpi.test.

NOTE: For best security, you should create a config.yml file and at least override any password settings from the default.config.yml file (e.g. drupal_database_password).

Installing using another host with Ansible installed

You can run the Ansible playbook from another host (instead of from within the VM—this also allows you to do everything without installing pip and ansible on the Raspberry Pi itself!).

1. Change the inventory file to use the Pi's IP address instead of 127.0.0.1.
2. Make sure you have your SSH private key configured for the pi account on the Pi (I use ssh-copy-id to copy my ID to the Pi).
3. Install required Ansible roles: ansible-galaxy install -r requirements.yml
4. Run the Ansible playbook: ansible-playbook main.yml

Note: If you have a headless Raspberry Pi and would like to find it's IP address, one way of doing so is to use a tool like Fing).

Advanced Usage

Adding your own Ansible tasks

If you need to add some additional automation, there is a concept of 'hook' files which will get called at different stages of the build if they are present (in the root directory of this project):

• hook-pre-tasks.yml: Gets called in the pre_tasks section of the playbook before any Ansible roles or tasks are applied.
• hook-tasks.yml: Gets called at the start of the tasks section of the playbook (after roles are applied).

One use of these hooks would be to do extra steps to deploy your own container and codebase, without having to use a private registry. See an example which I use to build and deploy one of my Drupal codebases: hook-tasks.yml example for Drupal for Kubernetes.

Updating your Pi (for future versions of Drupal Pi)

If you need to update Drupal Pi, do the following:

1. cd into the project directory: cd /path/to/drupal-pi
2. Pull the latest changes: git pull
3. Update all required Ansible roles (and install new ones): sudo ansible-galaxy install -r requirements.yml --force
4. Run the Ansible playbook: ansible-playbook -i inventory -c local main.yml

Note: Remove -c local if running from another host.

Resetting the Drupal Install

There is a reset.yml playbook included that will reset the environment so you can install a fresh copy of Drupal. To run the playbook, enter the following command in the same directory as this README:

ansible-playbook -i inventory -c local reset.yml

Note: Remove -c local if running from another host.

After it finishes resetting the environment, you can run the main.yml playbook again to rebuild the Drupal site.

Enabling Proxy Caching

The Drupal Pi includes a basic proxy cache configuration which uses Nginx to reverse proxy and cache all requests which do not include a Drupal session cookie. This can increase the speed of page delivery by 60x or more, meaning your little Pi could serve up more traffic than most home Internet uplinks could handle!

To enable Nginx's proxy cache, set the following value in your config.yml and run the main playbook:

nginx_proxy_cache: true

Using Drupal Pi as a load balancer for Pi Dramble

This project can also switch from running a site locally to being used as a load balancer for the Pi Dramble Cluster. All you have to do is set nginx_use_as_lb: true in your config.yml, make sure all the Pis which are responding to requests are in the nginx_lb_backends list, and run the playbook to redeploy the Nginx configuration.

Then point the domain you would normally point at the Pi Dramble cluster (e.g. cluster.pidramble.test) at the IP of the single Drupal Pi instead!

Author

This project was started in 2015 by Jeff Geerling, author of Ansible for DevOps.