How to Grav

guide linux web

Figured I might document how I made this site, partially just for my future self.

Desirements for website

  • Not too hard to set up
  • Secure
  • Very easy to maintain
  • Pretty

Architecture

  • Grav running in docker container - can simply docker pull container to update.
  • All configuration and pages are stored in a NAS (Grav recommends against this for performance reason, but my NAS is on the same physical machine so it has a virtual 10 Gb network connection).

This means that all you have to do to set up a VM hosting grav is create a docker compose file and add an fstab entry for the NAS - done. This makes backups and redeploying extremely easy - if the VM died somehow I could probably have the site back up in a matter of minutes.

Installing Grav steps overview

  • Install docker compose on host
  • Configure grav container
  • Get certificates
  • Launch grav

Install docker compose on host

I'm using Debian so I just did this. If you're on Ubuntu, make sure to use the Ubuntu instructions.

Configure container

mkdir grav
nvim grav/compose.yml
nvim grav/restart.sh # useful to quickly force a grav restart when it doesn't detect file changes
# Optional add smb mount for grav data
nvim smb.credo
sudo nvim /etc/fstab # or your preferred editor

Using linuxserver's container:

compose.yml

services:
  grav:
    image: lscr.io/linuxserver/grav:latest
    container_name: grav
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - /mnt/smb/grav/config:/config
    ports:
      - 80:80
      - 443:443
    restart: unless-stopped

restart.sh

# could add user to docker group but it's safer not to
sudo docker compose down
sudo docker compose up -d # run in background

smb.credo

username=USERNAME
password=PASSWORD

Example fstab entry - I don't understand all the options, I just took this from stack overflow and am yet to tweak the options.

//NAS_SERVER_IP/grav/ /mnt/smb/grav cifs _netdev,x-systemd.automount,rw,mfsymlinks,seal,noatime,credentials=/home/user/smb.credo,uid=1000,gid=1000,file_mode=0770,dir_mode=0770 0 0
  • _netdev and x-systemd.automount needed to get mount to happen after network is online (theoretically only _netdev should be needed but that didn't work so x-systemd.automount gets it to automount again later)

Get certificates [technically optional but highly recommended]

If you skip this and try to access through HTTPS the browser will complain about self signed certificates. Follow the instructions here to get your certificates using certbot.

Copy certificate to Grav (nginx)

TODO automate this - this will need to be repeated every time the certificates expire but I can't be bothered to set that up until it breaks once

sudo cp /etc/letsencrypt/live/yoururl.com/privkey.pem /mnt/smb/grav/config/keys/
sudo cp /etc/letsencrypt/live/yoururl.com/fullchain.pem /mnt/smb/grav/config/keys/

It also seems that the automatic certificate renewal doesn't work while grav is up. Seeing as I can't be bothered to automate yet I just slapped this together

#!/bin/bash
cd ~/grav
sudo docker compose down && \ # bring down grav
sudo certbot renew && \ # update certs
sudo cp /etc/letsencrypt/live/middleearth.kozow.com/fullchain.pem /mnt/smb/grav/config/keys && \ # manually copy certs
sudo cp /etc/letsencrypt/live/middleearth.kozow.com/privkey.pem /mnt/smb/grav/config/keys
sudo docker compose up -d # bring grav back up regardless of whether certs were updated

Configure Grav (nginx) to use the certificate

nvim /mnt/smb/grav/config/nginx/ssl.conf

Replace the ssl_certificate lines as follows

#ssl_certificate /config/keys/cert.crt;
#ssl_certificate_key /config/keys/cert.key;
ssl_certificate /config/keys/fullchain.pem;
ssl_certificate_key /config/keys/privkey.pem;

Launch Grav

cd grav
sudo docker compose up -d
# if you have problems this is a good place to Start
sudo docker compose logs

Once you forward ports 80 and 443 to the machine running Grav you should be able to navigate to yoururl.com and see the default Grav homepage! (If you don't know how to forward ports you should go learn about the implications of port forwarding and ensure you understand the risks before doing so.)

  • restart: unless-stopped ensures that Grav will automatically start when the machine is rebooted, however on my install for some reason the /etc/fstab entry isn't automounting on boot - will update once I fix that. - fixed this by adding _netdev,x-systemd.automount to fstab entry.

Future post idea - how to configure Grav to get to a website like this (hint).

Next Post