let's encrypt

Creating your own OER Foundation-style Libre Self-hosting Infrastructure with Docker Compose and Ubuntu LTS

dave — Thu, 12 Oct 2023 00:12:25 +0000

Creating your own OER Foundation-style Libre Self-hosting Infrastructure with Docker Compose and Ubuntu LTS

Blog tags

ubuntu linux

nginx

let's encrypt

postfix

docker compose

dave Thu 12/10/2023 - 13:12

Tips for this tutorial
Create a Virtual Private Server
- VPS Properties:
Key variables for you VPS
- Get your Domain lined up
Editing files
- Set up an unprivileged user for yourself
Configure the VPS
- Configuring your firewall
- Install the Nginx
Outgoing VPS Email (optional)
Installing the Docker Engine, Docker Compose, and Let's Encrypt
- Backwards compatibility for Docker Compose
- Docker use by non-root user
Setting up places for your Docker configurations and persistent Data
Configuring Nginx reverse proxy for your service
Let's Encrypt setup
- Requesting Let's Encrypt certificates

Tips for this tutorial

This tutorial is aimed at adventuresome would-be system administrators. I try not to assume any specialised knowledge on your part, and try to provide useful tips and explanation along the way to help you build a valid mental model of what you're doing. At the same, this is not a trivial process. Luckily, if you try it out, and decide not to follow through, so long as you delete your VPS, you should not be out-of-pocket by more than a few cents.

With this tutorial, I'm assuming you've got a computer with an Internet connection, that can run SSH (all modern systems should do that) and you can copy-and-paste stuff from this tutorial (in your browser) into either a terminal window (in which you're SSH'd into your VPS) or into a text editor. Note, if you find it difficult to paste into a terminal window, try using CTRL+SHIFT+V (CTRL+V is already used as a short-cut for something else in UNIX terminals since long before the Windows world started using CTRL+C and CTRL+V).

When I provide files you need to copy, look for the 'tokens' or placeholders with values you need to substitute (search-and-replace) in square brackets like this, [token name], with your own values. Any text editor worth using should let you do that!

Create a Virtual Private Server

The first step is to create a place to host instances of your own LibreSoftware services.

You can use a local piece of computing hardware of sufficient capacity in your own home or organisation (e.g. a redundant depreciated desktop should be sufficiently powerful), recognising that it needs to be reliable because anyone using your solution will not be able to access it if it's not running. But, doing that is no joke - making reliable systems is hard.

The more cost-effective self-hosting approach in our experience is to lease a low cost commodity Linux Virtual Private Server (aka a VPS) running Ubuntu Linux 22.04 (or the latest "Long Term Support" version - the next one, 24.04, will be released in April 2024). That's what we assume you're running for all our recent tutorials.

We have used quite a few Linux VPSs commodity providers. Known good options include Digital Ocean, Linode, Vultr, Hetzner, and TurnkeyLinux. There are many (hundreds of) other credible options. We recommend you find one hosted in the network epicentre (which isn't necessarily the same as the 'geographic' epicentre) of your audience. In the past year, we shifted almost all of our hosting to Hetzner as they've got the benefit of not being US-owned (They're German, and are therefore less likely to expose us to the egregiously over-reaching US Cloud and Patriot Acts). Shifting to Hetzner also reduced our infrastructure costs by about 50% compared to Digital Ocean. It also represents a 95% savings over Amazon AWS or Microsoft Azure hosting (can't imagine how anyone could justify hosting with either of them).

If you have trouble getting a VPS, you might find this video I created for provisioning a VPS, using Digital Ocean as an example, useful. In my experience, the process for provisioning VPSs on other platforms is very similar. You'll find this process much easier than using either Microsoft Azure or Amazon AWS, which we strongly recommend against using.

VPS Properties:

We recommend that you provision a VPS with the following spec - these will suffice capacity-wise for all the tutorials we provide, although depending on your load, you might want to beef them up, which you can do as the need arises - ou should be able to upgrade those specs in real time if required, except for your disk space. You can, however, provision a secondary storage space (you can start small and increase it as you need to). I will cover setting this up, as it'll make your life far far easier in the medium-long term.

4-8 GB RAM - system volatile memory for running applications
2-4 Virtual CPUs - processing capacity
80-160 GB Disk space (NVMe storage is faster than SSD which is faster than spinning disk space) - long term storage for data
running Ubuntu Linux 22.04 (the current Long Term Support version) - the operating system
extra storage - 20-40GB extra space (can be expanded on fairly short notice) - a long term storage option separate to your operating system drive - this is very very useful in the event that your app inadvertently fills your hard drive. You'll thank yourself for doing this (I an assure you from bitter experience). It's always a good idea to learn from others' past mistakes rather than repeat them!

You'll need to create an account for yourself on your chosen hosting provider (it's a good idea to use Two Factor Authentication, aka 2FA, on your hosting account so that no one can log in as you and, say, delete your server unexpectedly - you'll find instructions on how to set up 2FA on your hosting provider's site) and create an Ubuntu 22.04 (or the most recent 'Long Term Support' (LTS) version) in the 'zone' nearest to you (or your primary audience, if that's different).

If you don't already have an SSH key on your computer, I encourage you to create one and specify the public key in the process of creating your server - specifying the 'public key' of your SSH identity during the server creation process that should allow you to log in without needing a password!

You'll need to note the server's IPv4 address (it'll be a series of 4 numbers, 0-254, separated by full stops, e.g. 103.99.72.244), and you should also be aware that your server will have a newer IPv6 address, which will be a set of 8 four hex character values (each hex character can have one of 16 values: 0-9,A-F) separated by colons, e.g. 2604:A880:0002:00D0:0000:0000:20DE:9001. With one or the other of those IPs, you should be able to log into your new server via SSH. If you're on a UNIX command line (e.g. a Linux or MacOS desktop), do this in a terminal (On Windows, I understand people use a tool called Putty for SSH, in which case follow the app's instructions - or you'll find many tutorials on using it with a quick web search):

ssh [your server IPv4 or IPv6]

followed by the ENTER key (that'll be true for any line of commands I provide).

In some cases, depending on your hosting provider, you'll have a password to enter, or if you've specified your pre-existing public SSH key, you shouldn't need to enter a password at all, you should be logged in. To check what user you care, you can type

whoami

If it returns root (there's also a convention of using a '#' as the command prompt), you're the root or super-admin of the server. If not, you're a normal user (some hosting providers have a convention of giving you a default user called "ubuntu" or perhaps "debian") with a prompt that is, by convention, a '$'.

Now that you're logged in, it's worth doing an upgrade of your server's Ubuntu system! Do that as follows (this works regardless of whether your a root user or an unprivileged user with 'sudo' ability):

sudo apt update && sudo apt dist-upgrade

Usually the user, even if it's not the root user, will have the ability to use the sudo command modifier - that means "do this action as the root (aka the 'Super User', thus 'su' in 'sudo' for short) user" - if you're a non-root user, you'll likely be asked to enter your password as a security precaution the first time you run a command prefaced by sudo. Enter it, and it should run the command. Plus, the system shouldn't bother you for it again unless you leave your terminal unused for a while (usually 5 minutes) and come back to it.

At this point, I also like to install a cool software package called 'etckeeper' which records configuration changes on your VPS for future reference (it can be life-saving if trying to recover from an administrative mess-up!):

sudo apt install etckeeper git

which will also install some dependencies, including the very important (and relevant later on) 'git' version control system.

Key variables for you VPS

To set up your services, you'll need a few crucial bits of information related to your system's identity and external systems you'll need it to interact with. For example, as mentioned before, you'll need a domain name. For the rest of this tutorial, we'll use the convention of representing those variables as a name inside [], for example, the domain name you've picked, [domain name].

Here's a list of variables you'll need to know to complete the rest of this tutorial:

[ipv4] and [ipv6] - your VPS' IPv4 and IPv6 addresses (the latter can be ignored if your cloud provider doesn't support IPv6 addresses) as described above.
[domain name] - the fully qualified domain names or subdomains of a base [domain name] by which you want your services to be accessed. You must have full domain management ability on this domain. Example: nextcloud.oeru.org - that's the nextcloud subdomain of the oeru.org domain.
Authenticating SMTP details - this is required so your services can send emails to users - crucial things like email address validation and password recovery emails...
- [smtp server] - the domain name or IPv4 or IPv6 address of an SMTP server
- [smtp port] - the port number on the server that is listening for your connection. By convention it's likely to be 465 or 587, or possibly 25.
- [smtp reply-to-email] - a monitored email to which people can send email related to this WordPress site, e.g. notifications@[domain name]
- [smtp user] - the username (often an email address) used to authenticate against your SMTP server, provided by your email provider.
- [smtp password] - the accompanying password, provided by your email provider.
[your email] - an email address to which system-related emails can be sent to you, perhaps something like webmaster@[domain name].
[vps username] - the username you use on your server (by convention, these are one word, and all lower case).

Get your Domain lined up

You will want to have a domain to point at your server, so you don't have to remember the IP number. There're are thousands of domain "registrars" in the world who'll help you do that... You just need to "register" a name, and you pay yearly fee (usually between USD10-30 depending on the country and the "TLD" (Top Level Domain. There're national ones like .nz, .au, .uk, .tv, .sa, .za, etc., or international domains (mostly associated with the US) like .com, .org, .net, and a myriad of others. Countries decide on how much their domains wholesale for and registrars add a margin for the registration service).

Here in NZ, I use the services of Metaname (they're local to me in Christchurch, and I know them personally and trust their technical capabilities). If you're not sure who to use, ask your friends. Someone's bound to have recommendations (either positive or negative, in which case you'll know who to avoid).

Once you have selected and registered your domain, you can 'manage your Zone' to set up (usually through a web interface provided by the registrar) an A Record which associates your website's name to the IPv4 address of your server. So you should just be able to enter your server's IPv4 address, the domain name (or sub-domain) you want to use for the web service you want to set up.

Nowadays, if your Domain Name host offers it (some don't, meaning you might be better off with a different one), it's also important to define an IPv6 record, which is called an AAAA Record... you put in your IPv6 address instead of your IPv4 one.

You might be asked to set a "Time-to-live" (which has to do with the length of time Domain Name Servers are asked to "cache" the association that the A Record specifies) in which case you can put in 3600 seconds or an hour depending on the time units your registrar's interface requests... but in most cases that'll be set to a default of an hour automatically.

Editing files

In the rest of this tutorial, we're going to be editing quite a few files via the command line. If you're new to this, I recommend using the 'nano' text editor which is installed by default on Ubuntu Linux systems. It's fairly simple, and all of its options are visible in the text-based interface. I tend to use a far more powerful but far less beginner-friendly editor called 'vim'. There're other editors people might choose, too. To use your preferred editor for the rest of the tutorial, enter the following to set an environment variable EDIT, specifying your preferred editor, e.g.:

EDIT=$(which nano)

or, if you're like me

EDIT=$(which vim)

so that subsequent references to $EDIT will invoke your preferred editor. Note the command $(which nano) is a script which finds the full path to the named command, in this case 'nano'. Putting a command inside the $() means 'replace with the value the script returns', so it sets the value of EDIT to the path of the nano command in this case. On my current machine, the value it returns is /usr/bin/nano, which is pretty typical.

To test (at any time) whether you session still knows your $EDIT command, run

echo $EDIT

if it returns the path to your preferred editor, you're good to go. If not, just reassert (run again) the EDIT= line from above!

Note: if you log out and back in again, change users, or create a new terminal tab/session, you'll need to reassert the EDIT value.

Set up an unprivileged user for yourself

This will log you into your server as it did the first time, either as 'root' or the default unprivileged user. It's not considered good practice to access your server as root (it's too easy to completely screw it up by accident). It's a good idea to create your own separate 'non-root' user who has 'sudo' privileges and the ability to log in via SSH. If you are currently logged in as 'root', you can create a normal user for yourself via (replace [vps username] with your chosen username - in my case, I'd use U=dave):

U=[vps username]
adduser $U
adduser $U ssh
adduser $U admin
adduser $U sudo

You'll also want to a set a password for user [vps username] (we have a tutorial on creating good passwords):

passwd $U

then become that user temporarily (note, the root user can 'become' another user without needing to enter a password) and create an SSH key and, in the process, the .ssh directory (directories starting with a '.' are normally 'hidden' - you can show them in a directory listing via ls -a) for the file into which to put your public SSH key:

su $U

after which you need to re-run your EDIT command: EDIT=$(which nano)

and then run ssh-keygen -t rsa -b 2048
$EDIT ~/.ssh/authorized_keys

and in that file, copy and paste (without spaces on either end) your current computer's public ssh key (never publish your private key anywhere!), save and close the file.

and then leave the 'su' state, back to the superuser:

CTRL+D or type exit

From that point, you should be able to SSH to your server via ssh [vps username]@[domain name] without needing to enter a password.

These instructions use 'sudo' in front of commands because I assume you're using a non-root user. The instructions will still work fine even if you're logged in as 'root' (the 'sudo' will be ignored as it's unnecessary).

Configure the VPS

First things first. Let's make sure you've got the time zone set appropriately for your instance. It'll probably default to 'UTC' (Greenwich Mean Time). For our servers, I tend to pick 'Pacific/Auckland' which is our time zone. Run this

sudo dpkg-reconfigure tzdata

and pick the appropriate timezone. You can just leave it running UTC, but you might find it tricky down the track if, for example, you're looking at logs and having to constantly convert the times into your timezone.

Configuring your firewall

In the name of safety from the get-go, let's configure our firewall. We work on the basis of explicitly allowing in only what we want to let in (i.e. a 'default deny' policy).

First we'll enable the use of SSH through the firewall (not doing this could lock us out of your machine!)

sudo ufw allow ssh

while we're here, we'll also enable data transfer from the internal (to the VPS) Docker virtual network and the IP range it uses for Docker containers:

sudo ufw allow in on docker0
sudo ufw allow from 172.0.0.0/8 to any

Then we'll enable forwarding from internal network interfaces as required for Docker containers to be able to talk to the outside world:

sudo $EDIT /etc/default/ufw

and copy the line DEFAULT_FORWARD_POLICY="DROP" tweak it to look like this (commenting out the default, but leaving it there for future reference!):

#DEFAULT_FORWARD_POLICY="DROP"
DEFAULT_FORWARD_POLICY="ACCEPT"

and then save and exit the file (CTRL-X and then 'Y' if your editor is nano).

You also have to edit /etc/ufw/sysctl.conf

sudo $EDIT /etc/ufw/sysctl.conf

and remove the "#" at the start of the following lines, so they look like this:

# Uncomment this to allow this host to route packets between interfaces
net/ipv4/ip_forward=1
net/ipv6/conf/default/forwarding=1
net/ipv6/conf/all/forwarding=1

Then we need to restart the network stack to apply that configuration change

sudo systemctl restart systemd-networkd

(on older Ubuntu systems this would have been done via sudo service networking restart...)

Next we have to enable the (default on Ubuntu) UFW firewall to start at boot time to keep your machine relatively safe.

sudo $EDIT /etc/ufw/ufw.conf

And set the ENABLED variable near the top:

ENABLED=yes

Now you can formally start UFW now:

sudo ufw enable

Install the Nginx

Next we need to install the Nginx web server and reverse-proxy, as well as the Let's Encrypt SSL certificate generator, both of which are crucial for any secure web services you might want to host. Nginx is a more efficient and flexible alternative to the older Apache web server you might've seen elsewhere (Nginx recently surpassed Apache as the most widely used web server on the Internet).

sudo apt install nginx-full letsencrypt ssl-cert

You'll get a couple pop-up windows in your terminal, just hit ENTER to accept the defaults. Having installed it, we need to create firewall rules to allow external services to see it:

sudo ufw allow 'Nginx Full'

You can check if the firewall rules you requested have been enabled:

sudo ufw status

Outgoing VPS Email (optional)

Although it's not absolutely necessary (you can do this section later if you're in a big hurry), it's very useful for your server to be able to send out emails, like status emails to administrators (perhaps you) about things requiring their attention, e.g. the status of backups, pending security updates, expiring SSL certificates, etc.

To do this, we'll set up the industrial strength Postfix SMTP server, which is pretty quick and easy. First we install Postfix and a command line mail client for testing purposes.

sudo apt install postfix bsd-mailx

During the install, you'll be asked to select a bunch of configuration parameters. Select the defaults except:

Select "Internet Site with Smarthost",
fill in the domain name for your server [domain name],
the [smtp server] name and [smtp port] (in the form [smtp server]:[smtp port], e.g. smtp.oeru.org:587 ) of your "smarthost" who'll be doing the authenticating SMTP for you, and
the email address to which you want to receive system-related messages, [your email].

After that's done, we set a default address for the server to mail to, to [your email] selected above. First

sudo $EDIT /etc/aliases

We need to make sure the "root" user points to a real email address. Add a line at the bottom which says (replacing [your email] with your email :) )

root: [your email]

After which you'll need to convert the aliases file into a form that postfix can process, simply by running this:

sudo newaliases

Then we have to define the authentication credentials required to convince your mail server that you're you!

sudo $EDIT /etc/postfix/relay_password

and enter a single line in this format:

[smtp server] [smtp user]:[smtp password]

as an example, this is more or less what I've got for my system. Note that the [smtp user] in my case is an email address (this is common with many smtp system - the user is the same as the email address):

smtp.oeru.org smtp-work@fossdle.org:YourObscurePassw0rd

then save the file and, like the aliases file, run the conversion process (which uses a slightly different mechanism):

sudo postmap /etc/postfix/relay_password

Finally, we'll edit the main configuration file for Postfix to tell it about all this stuff:

sudo $EDIT /etc/postfix/main.cf

If your SMTP server uses port 25 (the default for unencrypted SMTP) you don't have to change anything, although most people nowadays prefer to use StartTLS or otherwise encrypted transport to at least ensure that your SMTP authentication details (at least) are transferred encrypted. That means using port 587 or 465. If you're using either of those ports, find the "relayhost = [your server name]" line... and add your port number after a colon, like this

relayhost = [smtp server]:[smtp port]

or, for example:

relayhost = smtp.oerfoundation.org:465

Then we have to update the configuration for Postfix to ensure that it knows about the details we've just defined (this command will automatically back up the original default configuration so you can start from scratch with the template below):

sudo mv /etc/postfix/main.cf /etc/postfix/main.cf.orig && sudo $EDIT /etc/postfix/main.cf

You can just copy-and-paste the following into it, substituting your specific values for the [tokens]. Note: the IPv6 designations in the line mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 are not tokens - you can leave those unchanged.

# See /usr/share/postfix/main.cf.dist for a commented, more complete version
 
# Debian specific:  Specifying a file name will cause the first
# line of that file to be used as the name.  The Debian default
# is /etc/mailname.
#myorigin = /etc/mailname
 
smtpd_banner = $myhostname ESMTP $mail_name (Ubuntu)
biff = no
 
# appending .domain is the MUA's job.
append_dot_mydomain = no
 
# Uncomment the next line to generate "delayed mail" warnings
#delay_warning_time = 4h
readme_directory = no
 
# See http://www.postfix.org/COMPATIBILITY_README.html -- default to 3.6 on
# fresh installs.
compatibility_level = 3.6
 
# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
smtpd_tls_security_level=may
 
smtp_tls_CApath=/etc/ssl/certs
#smtp_tls_security_level=may
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache
 
smtpd_relay_restrictions = permit_mynetworks permit_sasl_authenticated defer_unauth_destination
myhostname = [domain name]
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
myorigin = /etc/mailname
mydestination = $myhostname, localhost
relayhost = [smtp server]:[smtp port]
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128
mailbox_size_limit = 0
recipient_delimiter = +
inet_interfaces = all
inet_protocols = all
 
# added to configure accessing the relay host via authenticating SMTP
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/relay_password
smtp_sasl_security_options = noanonymous
smtp_tls_security_level = encrypt
 
# if you're using Ubuntu prior to 20.04, uncomment (remove the #) the
# earlier line smtp_tls_security_level = may to save errors in 'postfix check'
# and comment this line (by adding a # at the start)
smtp_tls_wrappermode = yes

Once you've created that main.cf file, you can double check that your config is valid:

sudo postfix check

and if it's all ok, you can get Postfix to re-read its configuration:

sudo postfix reload

You can then try sending an email so see if it works!

By default, a command line application called "mail" is installed as part of the bsd-mailx package we installed alongside postfix. You can use it to send test email from the command line on your host to verify you've got things working correctly! The stuff in <> are the keys to hit at the end of the line...

mail you@email.domain<ENTER>

Subject: Testing from your.relay.server.domain<ENTER>
Testing postfix remote host<ENTER>
<CTRL-D>
Cc:<ENTER>

Typing (hold down the Control or Ctrl key on your keyboard and press the "d" key) will finish your message, showing you a "CC:" field, in which you can type in other email addresses if you want to test sending to multiple addresses. When you then hit , it will attempt to send this email. It might take a few minutes to work its way through to the receiving email system (having to run the gauntlet of spam and virus filters on the way).

You can also always check the postfix system logs to see what postfix thinks about it using the command:

sudo less +G /var/log/mail.log

if your system doesn't have a /var/log/mail.log, never fear! Try this instead:

sudo less +G /var/log/syslog

In either case, hit to have the log update in real time.

Installing the Docker Engine, Docker Compose, and Let's Encrypt

First let's install the Docker Engine, which (these days) comes with Docker Compose and the Let's Encrypt scripts that let you procure no-cost Secure Sockets Layer certificates to secure access to your server. You can follow the official Docker Engine install instructions, but I've summarised them here (If the following doesn't work for you, go back to the official instructions, because something might've changed since I wrote this).

First we want to make sure no old Docker engines are installed on this server (this probably won't do anything, but no harm in running it):

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done

Second, we want to set up Docker's 'APT' repository, so you can keep Docker up-to-date with their latest versions (usually more up-to-date than those shipped with Ubuntu):

First we Add Docker's official GPG key (copy and paste all of this at your command line):

sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

Then we have to add the repository to Apt our system's sources and install the Docker Engine:

echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

With this approach, any updates made by the Docker community will be installed as part of your regular server upgrades.

Having installed the most recent release of the Docker engine, you should find that you've now got Docker Compose built in. Test that by running

docker compose version

which should return something like

Docker Compose version v2.18.1

If that's the case, superb, everything's great.

Backwards compatibility for Docker Compose

Since version 2 of the Docker Engine, the 'Docker Compose' capability has been incorporated into the base system. Prior to version 2, using Docker Compose required installing a separate app, and it was run by typing docker-compose rather than docker compose... so something I do now, to accommodate my muscle memory of typing docker-compose is to create a tiny script that lets me keep using that command, but have it call, instead, the new docker compose functionality. I do this via

sudo $EDIT /usr/local/bin/docker-compose

into which I put the following:

#!/bin/bash
D=`which docker`
$D compose "$@"

After saving that, we have to make the script 'executable' via

sudo chmod a+x /usr/local/bin/docker-compose

So you should now be able to run

docker-compose version

and get the same result that you did above for docker compose version...

Docker use by non-root user

If the above docker commands didn't work for you... and if you want to run Docker commands without being the root user or using sudo, as we usually do, you need to do a few more steps...

create a 'docker' group on your system (this might already exist, but doing this again won't hurt): sudo groupadd docker
add your user to it: sudo usermod -aG docker $USER
refresh your shell so that it recognises your user's membership in the docker group: newgrp docker

You should now be to run a test as a non-root user docker run hello-world

Setting up places for your Docker configurations and persistent Data

The next step is to set up the file structure for holding your Docker configurations and the data your Docker containers will access. This is my convention, so you're welcome to do things different, but this is a 'known good' approach.

Now we create the set of directories I use for holding Docker Compose configurations (/home/docker) and the persistent data the Docker containers create (/home/data)

D=[domain]
sudo mkdir -p /home/data/$D
sudo mkdir -p /home/docker/$D

It's helpful to make sure that your non-root user can also read and write files in these directories:

U=[vps username]
sudo chown -R $U /home/docker
sudo chown -R $U /home/data

Configuring Nginx reverse proxy for your service

Above, we installed Nginx as well as the Let's Encrypt scripts. Now we'll configure them as it's useful to have them working before you set up your services.

In order for you, outside of your server, to see your specific LibreSoftware services, you will need to set up a secure external 'reverse proxy' on your host VPS which will accept requests for each of those services from the Internet and pass those requests securely to the two sets of Docker containers providing the services. These will answer to https://[domain name], noting that a given VPS can answer on behalf of more than one domain name or subdomain name, where each references a different instance of a service or altogether different services. For example, a given VPS could host multiple services, like, say, a password manager, a WordPress blog, a Mautic email automation system, an Authentik Single-Sign On service, and a Discourse forum, where each has a separate domain name (or sub domain name) and each has an Nginx reverse proxy configuration that directs requests to the appropriate domain to the appropriate set of Docker containers.

We use Let's Encrypt to provide the SSL certificates (each is a file with a specially generated, very long string) which we use to limit access to our services to encrypted (secure) connections (protecting both our users and ourselves from external enemies), usually one for each service domain name and corresponding Nginx configuration file. Some Nginx configurations will have multiple domains names for which a given service accepts connections, but it consolidates them to the 'canonical' (official) domain name. For example, the OER Foundation's WordPress website will respond to any of the following:

but all requests to any of those 4 options (note the difference between http:// and https:// where 's' refers to 'Secure' or encrypted) will all be redirected - transparently by the Nginx configuration, which will be reflected in your browser's address bar - to the canonical web address (or URL), https://oerfoundation.org, that we've chosen because it's short and secure.

Nginx will not run unless the SSL certificates you reference in your configurations are valid. Given that we need to request them with a working Nginx prior to them being created puts us in an awkward position. We use a trick to get around it: we temporarily reference the default 'self-signed' SSL certificates (sometimes called 'Snakeoil certs' because that's the placeholder name they're given) that every new Linux system generates when it's installed, that are valid certificates (and thus acceptable to Nginx) but *they won't work with our domains, as they're generic and not 'signed' by an external party, like Let's Encrypt, meaning that your browser won't like them. But that's ok, as you browser will never need to see them, and Let's Encrypt's systems won't look at them either. We'll swap the Snakeoil certs out as soon as we've successfully created the Let's Encrypt ones, and your browser will be happy, and all will be well with the world.

This should happen automatically when you install the Let's Encrypt packages, but just to be sure, run this (it won't harm anything if you run it more than once):

sudo make-ssl-cert generate-default-snakeoil

which creates your default 'Snakeoil' certificates. They are technically valid certificates, but they aren't signed by any

Let's Encrypt setup

Step one of using Let's Encrypt is to make sure the Let's Encrypt scripts are installed (note: sometimes they're referred to as 'certbot' - it's the same code):

sudo apt install letsencrypt

Let's Encrypt and Nginx need to work together. Nginx stores all of its configuration in the directory /etc/nginx. The first thing we'll do is create a place for Let's Encrypt Nginx-specific configuration details:

sudo mkdir /etc/nginx/includes

Then we create that configuration file itself:

sudo $EDIT /etc/nginx/includes/letsencrypt.conf

into which we copy-and-paste the following (no [tokens] to replace in this one!)

# Rule for legitimate ACME Challenge requests
location ^~ /.well-known/acme-challenge/ {
    default_type "text/plain";
    # this can be any directory, but this name keeps it clear
    root /var/www/letsencrypt;
}
 
# Hide /acme-challenge subdirectory and return 404 on all requests.
# It is somewhat more secure than letting Nginx return 403.
# Ending slash is important!
location = /.well-known/acme-challenge/ {
    return 404;
}

As described in the file we've just created, Let's Encrypt will look for a secret code we create to verify that we own the domain we're requesting an SSL certificate for, so we have to make sure it exists:

sudo mkdir /var/www/letsencrypt

You will need to install an Nginx reverse proxy configuration file for each web-based service you run on your VPS, but those will usually be service-specific in their make up, so I won't discuss them here.

But, for the record (to make your lives a bit easier), this is what you'll do after you've got a suitable Nginx reverse proxy configuration in place and ready to run to acquire a Let's Encrypt SSL certificate.

Requesting Let's Encrypt certificates

To request Let's Encrypt SSL certificates for your service, run the following, replacing the [domain name] reference with the address you've selected for your service. Note that 'certbot' is the script provided by the Let's Encrypt package - historically, it could also be called via 'letsencrypt', although apparently the latter is now deprecated:

sudo certbot --webroot -w /var/www/letsencrypt -d [domain name]

Note - if you want to address your instance from multiple domains, use one (or more) -d [another domain] - just make sure that

all those domains already point to your VPS, and
those domains are included in the Nginx proxy configuration above.

otherwise the Let's Encrypt certbot request will fail!

Here's what you're likely to see as output from the first run of the letsencrypt script - note that it will ask you for an email address (so it can send you warnings if your certificate is going to expire, e.g. due to a problem with renewal (like if you make a configuration change that breaks the renewal process)).

Saving debug log to /var/log/letsencrypt/letsencrypt.log
Enter email address (used for urgent renewal and security notices)
 (Enter 'c' to cancel): webmaster@fossdle.org
 
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.3-September-21-2022.pdf. You must
agree in order to register with the ACME server. Do you agree?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: y
 
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you be willing, once your first certificate is successfully issued, to
share your email address with the Electronic Frontier Foundation, a founding
partner of the Let's Encrypt project and the non-profit organization that
develops Certbot? We'd like to send you email about our work encrypting the web,
EFF news, campaigns, and ways to support digital freedom.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: y
Account registered.
Requesting a certificate for [domain name]
 
Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/[domain name]/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/[domain name]/privkey.pem
This certificate expires on (some future date).
These files will be updated when the certificate renews.
Certbot has set up a scheduled task to automatically renew this certificate in the background.
 
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Ideally, you'll see a message like the above. If not, and there's an error, the error messages they provide are usually very useful and accurate. Fix the problem and try again. Note, your SSL certificate will have the name of your [domain name], even if it also provide support for [second domain name] (or third, fourth, etc.).

Once you have a Let's Encrypt certificate, you can update our Nginx configuration:

sudo $EDIT /etc/nginx/sites-available/[domain name]

and swap all occurrences of

    ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
    ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
#    ssl_certificate /etc/letsencrypt/live/[domain name]/fullchain.pem;
#    ssl_certificate_key /etc/letsencrypt/live/[domain name]/privkey.pem;

#    ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
#    ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
    ssl_certificate /etc/letsencrypt/live/[domain name]/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/[domain name]/privkey.pem;

which enables your new domain-specific SSL certificate. Check that Nginx is happy with your change:

sudo nginx -t

and if so,

sudo service nginx reload

You domain should now be enabled for https:// access. Note that going to http://[domain name] should automatically redirect you to https://[domain name] because you care about your user's security!

And that's it - your server is now ready to receive specific configurations for a myriad of Libre web services! Have a look around this site and check out some of the other tutorials - for many of them, you'll now be able to skip to near the end, as you've done most of the groundwork already!

Add new comment

Install NextCloud Hub and OnlyOffice on Ubuntu 22.04 with Docker Compose

dave — Sun, 28 May 2023 23:50:43 +0000

Install NextCloud Hub and OnlyOffice on Ubuntu 22.04 with Docker Compose

Blog tags

ubuntu linux

mariadb

docker

docker-compose

nextcloud

onlyoffice

nginx

let's encrypt

redis

productivity

dave Mon 29/05/2023 - 11:50

This is another update of my previous posts (installing NextCloud with Collabora Office Online on Ubuntu 16.04 and then NextCloud with OnlyOffice on Ubuntu 18.04). I'm updating it thanks to my colleague in edtech, Stephen Downes' heroic videos showing how he went through this process using my 18.04 instructions on 22.04, running into a few minor issues... this update seeks to remedy the problems he encountered with the older tutorial. Remember, all these Free and Open Source Software projects are progressing and improving relentlessly, which means the they way they behaved a few years ago is not likely to be exactly the way they behave now. In particular, NextCloud is leaping from strength to strength, benefiting from the well-founded concern held by many in the EU about data sovereignty and the market domination (and exploitation) of US-based multinationals like Amazon, Google, Microsoft, Dropbox, and others.

There're a few productivity packages that can be used in conjunction with NextCloud to provide comparable functionality to, for example, GoogleDocs + GoogleDrive or Microsoft Office 365 + Microsoft OneDrive, including Collabora Office (which we've used in the past). But the best companion productivity suite for NextCloud, in my opinion, is OnlyOffice. The application itself (for the tech focused reader, they've built an entirely new application ecosystem primarily using modern Javascript frameworks) is impressive in both capabilities and polish. The only real caveat I've come across is that it uses, by default, the 'fauxpen' standard formats developed by Microsoft rather than the true open standard formats of OpenDocumentFormat. But in a world where, sadly, most people don't even know what a file format is, any software that doesn't read and write the incumbent monopolist's format with great fidelity is dead in the water. On that count, OnlyOffice is impressive. NextCloud + OnlyOffice - even better together (without a single US multinational tech giant involved. NextCloud development is led from Germany, OnlyOffice's development is led by a team in Latvia)!

The beauty of the open source software model is that we can connect complementary applications, like NextCloud and OnlyOffice - developed by completely separate communities - to create a tightly integrated, highly functional, diverse computing platform. This combination, along with a bunch of other NextCloud "apps", is the equal of something like Google Apps (which includes Google Docs and Google Drive), but is under your control, not Google's. To me, that's a crucial difference.

With the release of NextCloud 26.0 (current as of this writing), NextCloud has the option of installing NextCloud Office (which is just a bundled OnlyOffice installation) alongside it, creating something called "NextCloud Hub". It's pretty impressive, but I've found that managing the OnlyOffice install is problematic and somewhat inflexible, so I've opted to stay with having an independent (rather than bundled) OnlyOffice instance, but it's on the same server but managed as a different service. That's what we'll be setting up here!

Tips for this tutorial
Create a Virtual Private Server
- VPS Properties:
Key variables for you NextCloud and OnlyOffice instances
- Get your Domain lined up
Editing files
- Set up an unprivileged user for yourself
Configure the VPS
- Configuring your firewall
- Install the Nginx
Outgoing VPS Email (optional)
Installing Docker Compose and Let's Encrypt
Installing MariaDB
Configuring Nginx reverse proxy for NextCloud and OnlyOffice
Let's Encrypt setup
- NextCloud Proxy Configuration
- OnlyOffice Proxy Configuration
- Requesting Let's Encrypt certificates
Prepare your Docker Compose host
NextCloud Install
- Install the NextCloud Docker recipe
- The NextCloud Nginx configuration
- The OnlyOffice Docker configuration
Firing up your NextCloud!
- The NextCloud source code (if necessary)
Configuring database access
Configuring the Admin user
Configuring Outgoing Email
Setting up OnlyOffice
Configuring OnlyOffice Integration with NextCloud
Keeping the whole thing up-to-date
Backing up NextCloud
Backup OnlyOffice

Tips for this tutorial

This tutorial is aimed at adventuresome would-be system administrators. I endeavour not to assume any specialised knowledge on your part, and try to provide useful tips and exposition along the way to help you build a valid mental model of what you're doing. At the same, this is not a trivial process. Luckily, if you try it out, and decide not to follow through, so long as you delete your VPS, you should not be out-of-pocket by more than a few cents.

If this is your first attempt at 'self-hosting', and you do follow through, this could be the start of a new era in your technical status - you could realised that self-hosting 'agency' you always wanted. People with that skill set are in hot demand among most organisations, especially in the NGO/charitable spaces. Plus, I'll be very impressed by your moxie!

When I provide files you need to copy, look for the placeholders with values you need to substitute (search-and-replace) in square brackets - [] - with your own values. I assume you'll be able to do that in a text editor on your desktop.

Create a Virtual Private Server

The first step is to create a place to host the NextCloud and OnlyOffice instances. You can run them on a local piece of hardware of sufficient capacity, but make sure you've got a fast and symmetrical (as fast to upload as to download!) connection. If (as with most residential Internet services) your upload is much slower than your download (often 1:10 ratio) your server is going to be very slow for external people, especially if streaming video. Also, don't undertake this unless you have a flat-rate data connection.

The more cost-effective approach in our experience, is to secure a low cost commodity Linux Virtual Private Server running Ubuntu Linux 22.04 (the latest "Long Term Support" version). That's what we'll assume you're running for this tutorial. We have used quite a few Linux VPSs commodity providers. Known good options are Digital Ocean (who recently raised their prices significantly), Linode, Vultr, Hetzner, and TurnkeyLinux. There are many (hundreds) of other credible options. We recommend you find one hosted in the network epicentre (which isn't necessarily the same as the 'geographic' epicentre) of your audience. For the record, we've just shifted our hosting to Hetzner as they've got the benefit of not being US-owned (They're German, and therefore don't expose us to the egregiously over-reaching US Cloud and Patriot Acts) and their pricing is pretty unbeatable.

If you have trouble getting a VPS, you might find this video I created for provisioning a VPS, using Digital Ocean as an example. In my experience, the process for provisioning VPSs on other platforms is very similar. You'll find this process much easier than using either Microsoft Azure or Amazon AWS, which we do not recommend. Their systems are unnecessarily complex, proprietary (they will lock you in), and 10-20 times more expensive than commodity hosting options already listed.

VPS Properties:

We recommend that, for a NextCloud instance of modest size (say up to 50 users) you provision a VPS with the following spec. You should be able to upgrade those specs in realtime if required, except for your disk space. You can, however, provision a secondary storage space (you can start small and increase it as you need to). I will cover setting this up, as it'll make your life far far easier in the medium-long term.

4-8 GB RAM
2-4 Virtual CPUs
80-160 GB Disk space (NVME disk is faster than SSD which is faster than spinning disk space)
running Ubuntu Linux 22.04 (the current Long Term Support version)
extra storage - 20-40GB extra space (can be expanded on fairly short notice)

You'll need to create an account for yourself on your chosen hosting provider (it's a good idea to use Two Factor Authentication, aka 2FA, on your hosting account so that no one can log in as you and, say, delete your server unexpectedly - you'll find instructions on how to set up 2FA on your hosting provider's site) and create an Ubuntu @2.04 (or the most recent 'Long Term Support' (LTS) version) - 24.04 is likely to come out in April 2024) in the 'zone' nearest to you (or your primary audience, if that's different).

You'll need to note the server's IPv4 address (it'll be a series of 4 numbers, 0-254, separated by full stops, e.g. 103.99.72.244), and you should also be aware that your server will have a newer IPv6 address, which will be a set of 8 four hex character values (each hex character can have one of 16 values: 0-9,A-F) separated by colons, e.g. 2604:A880:0002:00D0:0000:0000:20DE:9001. With one or the other of those IPs, you should be able to log into your new server via SSH. If you're on a UNIX command line (e.g. a Linux or MacOS desktop), do this in a terminal. On Windows, I understand people use a tool called Putty for SSH, in which case follow the app's instructions.

ssh [your server IPv4 or IPv6]

followed by the ENTER key (that'll be true for any line of commands I provide).

whoami

sudo apt update && sudo apt dist-upgrade

sudo apt install etckeeper

which will also install some dependencies, including the very important (and relevant later on) 'git' version control system.

Key variables for you NextCloud and OnlyOffice instances

To set up your services, you'll need a few crucial bits of information related to your system's identity and external systems you'll need it to interact with. For example, as mentioned before, you'll need a domain name. For the rest of this tutorial, we'll use the convention of representing those variables as a name inside [], or, for the domain name you've picked, [domain name].

Here's a list of variables you'll need to know to complete the rest of this tutorial:

[ipv4] and [ipv6] - your VPS' IPv4 and IPv6 addresses (the latter can be ignored if your cloud provider doesn't support IPv6 addresses) as described above.
[nextcloud domain] and [onlyoffice domain] - the fully qualified domain names or subdomains of a base [domain name] by which you want your services to be accessed. You must have full domain management ability on this domain. Example: nextcloud.oeru.org - that's the nextcloud subdomain of the oeru.org domain. *Authenticating SMTP details - this is required so your services can send emails to users - crucial things like email address validation and password recovery emails...
- [smtp server] - the domain name or IPv4 or IPv6 address of an SMTP server
- [smtp port] - the port number on the server that is listening for your connection. By convention it's likely to be 465 or 587, or possibly 25.
- [smtp reply-to-email] - a monitored email to which people can send email related to this WordPress site, e.g. notifications@[domain name]
- [smtp user] - the username (often an email address) used to authenticate against your SMTP server, provided by your email provider.
- [smtp password] - the accompanying password, provided by your email provider.
[your email] - an email address to which system-related emails can be sent to you, perhaps something like webmaster@[domain name].
[vps username] - the username you use on your server (by convention, these are one word, and all lower case).
[redis password] - this is a random secret that secure access to your webserver's cached data - I use a randomly generated alphanumeric password.
[onlyoffice secret] - this comes from your actual install, and you can get it when the time comes.
The MariaDB credentials for your NextCloud system (which stores a lot of stuff in MariaDB or MySQL by default)
- [db name] - the name of your MariaDB database for NextCloud - usually 'nextcloud'.
- [db user] - the user who can manage your database.
- [db password] - the user's password.

Get your Domain lined up

Editing files

EDIT=$(which nano)

or, if you're like me

EDIT=$(which vim)

To test (at any time) whether you session still knows your $EDIT command, run

echo $EDIT

if it returns the path to your preferred editor, you're good to go. If not, just reassert the EDIT= line from above!

Note: if you log out and back in again, change users, or create a new terminal tab/session, you'll need to reassert the EDIT value.

Set up an unprivileged user for yourself

U=[vps username]
adduser $U
adduser $U ssh
adduser $U admin
adduser $U sudo

You'll also want to a set a password for user [vps username] (we have a tutorial on creating good passwords):

passwd $U

su $U

after which you need to re-run your EDIT command: EDIT=$(which nano)

and then run ssh-keygen -t rsa -b 2048
$EDIT ~/.ssh/authorized_keys

and in that file, copy and paste (without spaces on either end) your current computer's public ssh key (never publish your private key anywhere!), save and close the file.

and then leave the 'su' state, back to the superuser:

CTRL+D or type exit

From that point, you should be able to SSH to your server via ssh [vps username]@[domain name] without needing to enter a password.

Configure the VPS

sudo dpkg-reconfigure tzdata

Configuring your firewall

In the name of safety from the get-go, let's configure our firewall. We work on the basis of explicitly allowing in only what we want to let in (i.e. a 'default deny' policy).

First we'll enable the use of SSH through the firewall (not doing this could lock us out of your machine!)

sudo ufw allow ssh

while we're here, we'll also enable data transfer from the internal (to the VPS) Docker virtual network and the IP range it uses for Docker containers:

sudo ufw allow in on docker0
sudo ufw allow from 172.0.0.0/8 to any

Then we'll enable forwarding from internal network interfaces as required for Docker containers to be able to talk to the outside world:

sudo $EDIT /etc/default/ufw

and copy the line DEFAULT_FORWARD_POLICY="DROP" tweak it to look like this (commenting out the default, but leaving it there for future reference!):

#DEFAULT_FORWARD_POLICY="DROP"
DEFAULT_FORWARD_POLICY="ACCEPT"

and then save and exit the file (CTRL-X and then 'Y' if your editor is nano).

You also have to edit /etc/ufw/sysctl.conf and remove the "#" at the start of the following lines, so they look like this:

sudo $EDIT /etc/ufw/sysctl.conf

# Uncomment this to allow this host to route packets between interfaces
net/ipv4/ip_forward=1
net/ipv6/conf/default/forwarding=1
net/ipv6/conf/all/forwarding=1

Then we need to restart the network stack to apply that configuration change

sudo systemctl restart systemd-networkd

(on older Ubuntu systems this would have been done via sudo service networking restart...)

Next we have to enable the UFW firewall to start at boot time.

sudo $EDIT /etc/ufw/ufw.conf

And set the ENABLED variable near the top:

ENABLED=yes

Now you can formally start UFW now:

sudo ufw enable

Install the Nginx

sudo apt install nginx-full letsencrypt ssl-cert

You'll get a couple pop-up windows in your terminal, just hit ENTER to accept the defaults. Having installed it, we need to create firewall rules to allow external services to see it:

sudo ufw allow 'Nginx Full'

You can check if the firewall rules you requested have been enabled:

sudo ufw status

Outgoing VPS Email (optional)

sudo apt install postfix bsd-mailx

During the install, you'll be asked to select a bunch of configuration parameters. Select the defaults except:

Select "Internet Site with Smarthost",
fill in the domain name for your server [domain name],
the [smtp server] name and [smtp port] (in the form [smtp server]:[smtp port], e.g. smtp.oeru.org:587 ) of your "smarthost" who'll be doing the authenticating SMTP for you, and
the email address to which you want to receive system-related messages, [your email].

After that's done, we set a default address for the server to mail to, to [your email] selected above. First

sudo $EDIT /etc/aliases

We need to make sure the "root" user points to a real email address. Add a line at the bottom which says (replacing [your email] with your email :) )

root: [your email]

After which you'll need to convert the aliases file into a form that postfix can process, simply by running this:

sudo newaliases

Then we have to define the authentication credentials required to convince your mail server that you're you!

sudo $EDIT /etc/postfix/relay_password

and enter a single line in this format:

[smtp server] [smtp user]:[smtp password]

smtp.oerfoundation.org smtp-work@fossdle.org:SomeObscurePassw0rd

then save the file and, like the aliases file, run the conversion process (which uses a slightly different mechanism):

sudo postmap /etc/postfix/relay_password

Finally, we'll edit the main configuration file for Postfix to tell it about all this stuff:

sudo $EDIT /etc/postfix/main.cf

relayhost = [smtp server]:[smtp port]

or, for example:

relayhost = smtp.oerfoundation.org:465

sudo mv /etc/postfix/main.cf /etc/postfix/main.cf.orig && sudo $EDIT /etc/postfix/main.cf

You can just copy-and-paste the following into it, substituting your specific values for the [tokens].

# See /usr/share/postfix/main.cf.dist for a commented, more complete version
 
# Debian specific:  Specifying a file name will cause the first
# line of that file to be used as the name.  The Debian default
# is /etc/mailname.
#myorigin = /etc/mailname
 
smtpd_banner = $myhostname ESMTP $mail_name (Ubuntu)
biff = no
 
# appending .domain is the MUA's job.
append_dot_mydomain = no
 
# Uncomment the next line to generate "delayed mail" warnings
#delay_warning_time = 4h
readme_directory = no
 
# See http://www.postfix.org/COMPATIBILITY_README.html -- default to 3.6 on
# fresh installs.
compatibility_level = 3.6
 
# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
smtpd_tls_security_level=may
 
smtp_tls_CApath=/etc/ssl/certs
#smtp_tls_security_level=may
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache
 
smtpd_relay_restrictions = permit_mynetworks permit_sasl_authenticated defer_unauth_destination
myhostname = [domain name]
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
myorigin = /etc/mailname
mydestination = $myhostname, localhost
relayhost = [smtp server]:[smtp port]
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128
mailbox_size_limit = 0
recipient_delimiter = +
inet_interfaces = all
inet_protocols = all
 
# added to configure accessing the relay host via authenticating SMTP
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/relay_password
smtp_sasl_security_options = noanonymous
smtp_tls_security_level = encrypt
 
# if you're using Ubuntu prior to 20.04, uncomment (remove the #) the
# earlier line smtp_tls_security_level = may to save errors in 'postfix check'
# and comment this line (by adding a # at the start)
smtp_tls_wrappermode = yes

Once you've created that main.cf file, you can double check that your config is valid:

sudo postfix check

and if it's all ok, you can get Postfix to re-read its configuration:

sudo postfix reload

You can then try sending an email so see if it works!

mail you@email.domain<ENTER>

Subject: Testing from your.relay.server.domain<ENTER>
Testing postfix remote host<ENTER>
<CTRL-D>
Cc:<ENTER>

You can also always check the postfix system logs to see what postfix thinks about it using the command:

sudo less +G /var/log/mail.log

if your system doesn't have a /var/log/mail.log, never fear! Try this instead:

sudo less +G /var/log/syslog

In either case, hit to have the log update in real time.

Installing Docker Compose and Let's Encrypt

First let's install Docker Compose (and its dependencies, like the whole Docker subsystem) and the Let's Encrypt scripts that let you procure no-cost Secure Sockets Layer certificates to secure access to your server.

sudo apt install docker-compose letsencrypt

Now we create the set of directories I use for holding Docker Compose configurations (/home/docker) and the persistent data the Docker containers create (/home/data)

D=[nextcloud domain]
sudo mkdir -p /home/data/$D
sudo mkdir -p /home/docker/$D

followed by

D=[onlyoffice domain]
sudo mkdir -p /home/data/$D
sudo mkdir -p /home/docker/$D

It's helpful to make sure that your non-root user can also read and write files in these directories:

U=[vps username]
sudo chown -R $U /home/docker
sudo chown -R $U /home/data

Installing MariaDB

MariaDB is effectively a drop-in alternative to MySQL and we prefer it because it's not controlled by Oracle and has a more active developer community. On Ubuntu, MariaDB pretends to be MySQL for compatibility purposes, so don't be weirded out by the interchangeable names below. Install the server and the client like this.

sudo apt install mariadb-server mariadb-client

You should now be able to type sudo mysql at the command prompt, and it'll log you into the MariaDB console (to get out type \q or exit)

Tweak the configuration so that it's listening on

sudo vim /etc/mysql/mariadb.conf.d/50-server.cnf

and copy the bind-address line and adjust so it looks like this - we want MariaDB to be listening on all interfaces, not just localhost (127.0.0.1)...

# Instead of skip-networking the default is now to listen only on
# localhost which is more compatible and is not less secure.
#bind-address           = 127.0.0.1
bind-address            = 0.0.0.0

Then restart MariaDB:

sudo service mysql restart

It should now be listening on port 3306 on all interfaces, i.e. 0.0.0.0. Your instance will be protected from anyone outside of your VPS connecting to it by the fact that external access to port 3306 isn't allowed by your ufw firewall.

To check it's running, you can run

sudo netstat -punta | grep 3306

and you should see something like

tcp 0 0 0.0.0.0:3306 0.0.0.0:* LISTEN 8459/mysqld

which is the 'mysqld' (the MySQL-compatible database daemon provided by MariaDB).

Now set up the database which will hold NextCloud's data. Log into the MySQL client on the host:

sudo mysql

You'll need to gin up a password for your "nextcloud" database user. I usually use pwgen (sudo apt install pwgen) - for example running this command will give you a single 19 character password without special characters (just numbers and letters):

pwgen -s 19 1

Giving you something like this (but if it's truly random, almost certainly not exactly this):

bYIOSrvR9aGwL5FRGFU

At the prompt (which will look something like MariaDB [(none)]>) enter the following lines (putting your password in place of [passwd]):

CREATE DATABASE nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER "nextcloud"@"%" IDENTIFIED BY "[passwd]";
GRANT ALL ON nextcloud.* to "nextcloud"@"%";
FLUSH PRIVILEGES;

Then enter \q to exit.

Configuring Nginx reverse proxy for NextCloud and OnlyOffice

Above, we installed Nginx as well as the Let's Encrypt scripts. Now we'll configure them as it's useful to have them working before you set up your services.

In order for you, outside of your server, to see the NextCloud and OnlyOffice services, you will need to set up a secure external 'reverse proxy' on your host VPS which will accept requests for those two services from the Internet and pass those requests securely to the two sets of Docker containers providing the services. These will answer to https://[nextcloud domain] (for NextCloud) and https://[onlyoffice domain] for OnlyOffice.

Let's Encrypt will provide the SSL certificates (each is a file with a specially generated, very long string) which we use to limit access to our services to encrypted (secure) connections (protecting both our users and ourselves from external enemies).

Note: many thanks to Stephen Harlow (who crash-tested this tutorial!) for pointing out that you might need to run the following if you're not finding the 'Snakeoil certs' on your system (running them just to be safe shouldn't cause any issues):

sudo make-ssl-cert generate-default-snakeoil

Let's Encrypt setup

sudo mkdir /etc/nginx/includes

Then we create that configuration file itself:

sudo $EDIT /etc/nginx/includes/letsencrypt.conf

into which we copy-and-paste the following (no [tokens] to replace in this one!)

# Rule for legitimate ACME Challenge requests
location ^~ /.well-known/acme-challenge/ {
    default_type "text/plain";
    # this can be any directory, but this name keeps it clear
    root /var/www/letsencrypt;
}
 
# Hide /acme-challenge subdirectory and return 404 on all requests.
# It is somewhat more secure than letting Nginx return 403.
# Ending slash is important!
location = /.well-known/acme-challenge/ {
    return 404;
}

sudo mkdir /var/www/letsencrypt

NextCloud Proxy Configuration

To configure the NextCloud proxy, you need to create this configuration file in your /etc/nginx/sites-available/ directory.

Create a file with a meaningful name for your NextCloud Proxy, something like "nextcloud" (I use the domain name I've chosen, e.g. for docs.oeru.org I call the proxy file "docs.oeru.org" - keeps everything clear, and I can have multiple instances on the same server if I want...). Let's go with in this instance (change it if you prefer)

sudo $EDIT /etc/nginx/sites-available/nextcloud

with the following contents, replacing [nextcloud domain] with your selected domain name, but leave off the [ ] (those are just there to make sure nginx errors if you've missed replacing any) - and the port number 8080 if you've opted to change to a different one!:

server {
    listen 80;
    listen [::]:80;
 
    # note, you can add additional domain names, separated by a space, to which this config will answer.
    server_name [nextcloud domain];
 
    include includes/letsencrypt.conf;
 
    # enforce https
    location / {
        return 302 https://$server_name$request_uri;
    }
}
 
server {
    listen 443 ssl;
    listen [::]:443 ssl;
 
    # note, you can add additional domain names, separated by a space, to which this config will answer.
    server_name [nextcloud domain];
 
    ## Access and error logs.
    access_log /var/log/nginx/[nextcloud domain]_access.log;
    error_log /var/log/nginx/[nextcloud domain]_error.log;
 
    # these are temporary certificates, used only long enough to secure Let's Encrypt certs as below.
    ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
    ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
 
    # these need to be commented out until after the Let's Encrypt
    # certificates have been acquired
    #ssl_certificate /etc/letsencrypt/live/[nextcloud domain]/fullchain.pem;
    #ssl_certificate_key /etc/letsencrypt/live/[nextcloud domain]/privkey.pem;
 
    # from http://axiacore.com/blog/enable-perfect-forward-secrecy-nginx/
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout  10m;
    # limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s;
    # forward secrecy settings
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_prefer_server_ciphers on;
    ssl_ciphers "EECDH+ECDSA+AESGCM EECDH+aRSA+AESGCM EECDH+ECDSA+SHA384 EECDH+ECDSA+SHA256 EECDH+aRSA+SHA384 EECDH+aRSA+SHA256 EECDH+aRSA+RC4 EECDH EDH+aRSA RC4 !aNULL !eNULL !LOW !3DES !MD5 !EXP !PSK !SRP !DSS !RC4";
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
 
    # The following 2 rules are only needed for the user_webfinger app.
    # Uncomment it if you're planning to use this app.
    rewrite ^/.well-known/host-meta /public.php?service=host-meta last;
    rewrite ^/.well-known/host-meta.json /public.php?service=host-meta-json last;
 
    # The following rule is only needed for the Social app.
    # Uncomment it if you're planning to use this app.
    rewrite ^/.well-known/webfinger /public.php?service=webfinger last;
 
    location ^~ / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $http_host;
        proxy_read_timeout 36000s;
        proxy_buffering off;
        proxy_max_temp_file_size 15000m;
    }
    client_max_body_size 1G;
    fastcgi_buffers 64 4K;
    add_header Strict-Transport-Security "max-age=31536000; includeSubdomains;";
    # Remove X-Powered-By, which is an information leak
    fastcgi_hide_header X-Powered-By;
}

Note: you'll need to create the file cited in the proxy configuration: /etc/ssl/certs/dhparam.pem

You can do this as follows (install the necessary software, backup any possible existing version as a matter of prudence, and create a new one):

sudo apt update && sudo apt install openssl
sudo [ -f "/etc/ssl/certs/dhparam.pem" ] && sudo mv /etc/ssl/certs/dhparam.pem /etc/ssl/certs/dhparam.pem.bak
sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

Once those are created, you have to make sure that they're "enabled" (replacing with your file names, of course):

cd /etc/nginx/sites-enabled sudo ln -sf ../sites-available/nextcloud .

To confirm that there aren't any typos or issues that might make nginx unhappy, run

sudo nginx -t

If all's well, get nginx to reread its configuration with the new files (if not, it might be because you missed replacing one of the [tokens]):

sudo service nginx reload

OnlyOffice Proxy Configuration

The OnlyOffice proxy configuration uses a very similar process to the one above. You just need to create another configuration file:

upstream docservice {
   server 127.0.0.1:9880;
}
 
map $http_host $this_host {
   "" $host;
   default $http_host;
}
 
map $http_x_forwarded_proto $the_scheme {
   default $http_x_forwarded_proto;
   "" $scheme;
}
 
map $http_x_forwarded_host $the_host {
    default $http_x_forwarded_host;
    "" $this_host;
}
 
map $http_upgrade $proxy_connection {
  default upgrade;
  "" close;
}
 
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $proxy_connection;
proxy_set_header X-Forwarded-Host $the_host;
proxy_set_header X-Forwarded-Proto $the_scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 
server {
    listen 80;
    listen [::]:80;
 
    server_name [onlyoffice domain];
 
    # for let's encrypt renewals!
    include /etc/nginx/includes/letsencrypt.conf;
 
    ## Access and error logs.
    access_log /var/log/nginx/[onlyoffice domain]_access.log;
    error_log /var/log/nginx/[onlyoffice domain]_error.log;
 
    # redirect all HTTP traffic to HTTPS.
    location / {
        return  302 https://$server_name$request_uri;
    }
}
 
# This configuration assumes that there's an nginx container talking to the mautic PHP-fpm container,
# and this is a reverse proxy for that Mautic instance.
server {
    listen 443 ssl;
    listen [::]:443 ssl;
 
    server_name [onlyoffice domain];
 
    ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
    ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
    #ssl_certificate /etc/letsencrypt/live/[onlyoffice domain]/fullchain.pem;
    #ssl_certificate_key /etc/letsencrypt/live/[onlyoffice domain]/privkey.pem;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    # to create this, see https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
    keepalive_timeout 20s;
    # for let's encrypt renewals!
    include /etc/nginx/includes/letsencrypt.conf;
 
    proxy_http_version 1.1;
    proxy_buffering off;
 
    ## Access and error logs.
    access_log /var/log/nginx/[onlyoffice domain]_access.log;
    error_log /var/log/nginx/[onlyoffice domain]_error.log;
 
    add_header Strict-Transport-Security max-age=31536000;
    # add_header X-Frame-Options SAMEORIGIN;
    add_header X-Content-Type-Options nosniff;
 
    # see https://github.com/ONLYOFFICE/document-server-proxy/blob/master/nginx/proxy-https-to-http.conf
    location / {
        proxy_pass http://docservice;
        proxy_http_version 1.1;
    }
}

After that's done, we'll repeat what we did for the NextCloud config:

sudo cd /etc/nginx/sites-enabled sudo ln -sf ../sites-available/onlyoffice . sudo nginx -t

and, if there're no errors, run

sudo service nginx reload

Now we're ready to request Let's Encrypt certificates.

Requesting Let's Encrypt certificates

To request Let's Encrypt SSL certificates for your NextCloud and OnlyOffice services, run the following, replacing the [token], of course (note that 'certbot' is the script provided by the Let's Encrypt package - historically, it could also be called via 'letsencrypt', although apparently the latter is now deprecated):

sudo certbot --webroot -w /var/www/letsencrypt -d [nextcloud domain]

Note - if you want to address your instance from multiple domains, use one (or more) -d [another domain] - just make sure that

all those domains already point to your VPS, and
those domains are included in the Nginx proxy configuration above.

otherwise the Let's Encrypt certbot request will fail!

Saving debug log to /var/log/letsencrypt/letsencrypt.log
Enter email address (used for urgent renewal and security notices)
 (Enter 'c' to cancel): webmaster@fossdle.org
 
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.3-September-21-2022.pdf. You must
agree in order to register with the ACME server. Do you agree?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: y
 
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you be willing, once your first certificate is successfully issued, to
share your email address with the Electronic Frontier Foundation, a founding
partner of the Let's Encrypt project and the non-profit organization that
develops Certbot? We'd like to send you email about our work encrypting the web,
EFF news, campaigns, and ways to support digital freedom.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: y
Account registered.
Requesting a certificate for [nextcloud domain]
 
Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/[nextcloud domain]/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/[nextcloud domain]/privkey.pem
This certificate expires on (some future date).
These files will be updated when the certificate renews.
Certbot has set up a scheduled task to automatically renew this certificate in the background.
 
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Ideally, you'll see a message like the above. If not, and there's an error, the error messages they provide are usually very useful and accurate. Fix the problem and try again. Note, your SSL certificate will have the name of your [nextcloud domain], even if it also provide support for [second domain name] (or third, fourth, etc.).

Once you have a Let's Encrypt certificate, you can update our NGINX configuration:

sudo $EDIT /etc/nginx/sites-available/[nextcloud domain]

and swap all occurrences of

    ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
    ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
#    ssl_certificate /etc/letsencrypt/live/[nextcloud domain]/fullchain.pem;
#    ssl_certificate_key /etc/letsencrypt/live/[nextcloud domain]/privkey.pem;

#    ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
#    ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
    ssl_certificate /etc/letsencrypt/live/[nextcloud domain]/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/[nextcloud domain]/privkey.pem;

which enables your new domain-specific SSL certificate. Check that NGINX is happy with your change:

sudo nginx -t

and if so,

sudo service nginx reload

You domain should now be enabled for https:// access. Note that going to http://[nextcloud domain] should automatically redirect you to https://[nextcloud domain] because you care about your user's security! :grin:

Now you'll have to repeat the same process for the [onlyoffice domain]. When that's done... Onward!

Prepare your Docker Compose host

We make use of the NextCloud community's stable Docker container which they keep (more or less) up-to-date. Similarly, the OnlyOffice developers maintain a Docker container, too. We will run them both on this same server as separate services via Docker Compose. The two sets of Docker containers will look like this:

a suite of NextCloud containers:

the main PHP-FPM container (which provides most of the functionality for NextCloud using the PHP scripting engine,
an identical container to the PHP one which runs the cron service (which does periodic administrative tasks relevant to NextCloud)
a Redis container (which provides performance improving caching for NextCloud), and
an Nginx webserver container which makes it easier to manage the configuration and paths of the NextCloud instance. It means that on the hosting server, we only need to run a proxying web server, which is easy.

the single OnlyOffice container which, despite the Docker convention of each container running only a single services, runs the whole OnlyOffice stack, which includes PostgreSQL, Nginx, Rabbit-MQ, Python, and NodeJS.

The way I prefer to implement this set of containers is to use:

sudo apt install docker-compose

to set up the entire Docker and Docker Compose system on your server. If you desire, you can also set up a newer version of Docker Compose, namely the 2.x series. The command line interface and feedback on actions is nicer with this newer version, but otherwise, there's little difference (a few other services I run require 2.x, like Mailcow, so I've had experience with both).

Then set up a place for your Docker containers and the associated persistent data (your Docker containers should hold no important data - you should be able to delete and recreate them entirely without losing any important data or configuration):

sudo mkdir /home/docker
sudo mkdir /home/docker/nextcloud
sudo mkdir /home/docker/onlyoffice
sudo mkdir /home/data
sudo mkdir /home/data/nextcloud
sudo mkdir /home/data/nextcloud/nginx
sudo mkdir /home/data/onlyofficesudo
chown -R ${USER}:${USER} /home/docker /home/data

My personal convention is to name both docker and data directories after the specific domain name of the service to which they apply - makes it easier when, for example, I have multiple instances of NextCloud on a single server. The above is intended to be straight forward for folks only running one of each - but feel free to modify for your requirements. If you do so, remember to ripple that through the rest of these instructions!

NextCloud Install

Install the NextCloud Docker recipe

Now we have a place to put the really key bit - the code for running NextCloud and OnlyOffice via Docker Compose. First, let's set up NextCloud (this also installs the OnlyOffice server):

cd /home/docker/nextcloud

You'll have to create a file, e.g via

$EDIT docker-compose.yml

and fill it with this (substituting the values in [] to suit your details - and changing the paths in /home/data if you've used something different than the default above!):

version: '3'
services:
  nginx:
    container_name: nginx-server
    image: nginx
    ports:
      - 127.0.0.1:8080:80
    volumes:
      - /home/data/nextcloud/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - /home/data/nextcloud/nextcloud:/var/www/html
    links:
      - app
    environment:
      - VIRTUAL_HOST
    restart: unless-stopped
  app:
    container_name: app-server
    image: nextcloud:fpm
    stdin_open: true
    tty: true
    links:
      - redis
    expose:
      - '80'
      - '9000'
    volumes:
      - /home/data/nextcloud/nextcloud:/var/www/html
    environment:
      - REDIS_HOST=redis
      - REDIS_HOST_PASSWORD=[redis password]
    extra_hosts:
      - '[onlyoffice domain]:[ipv4]'
    restart: unless-stopped
  cron:
    image: nextcloud:fpm
    volumes:
      - /home/data/nextcloud/nextcloud:/var/www/html
    user: www-data
    entrypoint: |
      bash -c 'bash -s <<EOF
      trap "break;exit" SIGHUP SIGINT SIGTERM
      while /bin/true; do
        /usr/local/bin/php /var/www/html/cron.php
        sleep 900
      done
      EOF'
    restart: unless-stopped
  redis:
    image: redis:alpine
    command: redis-server --requirepass [redis password]
    volumes:
      - /home/data/nextcloud/redis:/data
    restart: unless-stopped

The "port" specified above, 8080, for nginx is arbitrary - I picked it to ensure it doesn't don't conflict with ports being used by other containers on my server - you can use this value if you want, or use sudo netstat -punta (you might need to install the package that provides netstat first, sudo apt install net-tools) to see what ports are currently claimed by other services on your server (if there are any) and pick one that doesn't clash! If it scroll past too fast, you can pipe it into less to allow you to scroll and search like this: sudo netstat -punta | less - hit "q" to exit or "/" to initiate a text search. Or, if you want verify that a specific port is not already being used, you can do this (in this case for port 8080) via sudo netstat -punta | grep 8080 - if it returns any results, something is already listening on that port. If not, it's available.

The NextCloud Nginx configuration

You will also need to provide the "nginx.conf" file referenced in the nginx section of the Docker Compose configuration. Do that via

$EDIT /home/data/nextcloud/nginx/nginx.conf

and copy-and-paste the following incantation (you shouldn't need to change anything in this one) - there're notes in it offering some explanations:

worker_processes auto;
 
error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;
 
 
events {
    worker_connections  1024;
}
 
 
http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
 
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
 
    access_log  /var/log/nginx/access.log  main;
 
    sendfile        on;
    #tcp_nopush     on;
 
    keepalive_timeout  65;
 
    set_real_ip_from  10.0.0.0/8;
    set_real_ip_from  172.16.0.0/12;
    set_real_ip_from  192.168.0.0/16;
    real_ip_header    X-Real-IP;
 
    #gzip  on;
 
    map $http_host $this_host {
        "" $host;
        default $http_host;
    }
 
    map $http_x_forwarded_proto $the_scheme {
        default $http_x_forwarded_proto;
        "" $scheme;
    }
 
    map $http_x_forwarded_host $the_host {
        default $http_x_forwarded_host;
        "" $this_host;
    }
 
    upstream php-handler {
        server app-server:9000;
    }
 
    server {
        listen 80;
 
        # Add headers to serve security related headers
        # Before enabling Strict-Transport-Security headers please read into this
        # topic first.
        #add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;
        #
        # WARNING: Only add the preload option once you read about
        # the consequences in https://hstspreload.org/. This option
        # will add the domain to a hardcoded list that is shipped
        # in all major browsers and getting removed from this list
        # could take several months.
        add_header Referrer-Policy "no-referrer" always;
        add_header X-Content-Type-Options "nosniff" always;
        add_header X-Download-Options "noopen" always;
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header X-Permitted-Cross-Domain-Policies "none" always;
        add_header X-Robots-Tag "noindex, nofollow" always;
        add_header X-XSS-Protection "1; mode=block" always;
 
        # Remove X-Powered-By, which is an information leak
        fastcgi_hide_header X-Powered-By;
 
        # Path to the root of your installation
        root /var/www/html;
 
        location = /robots.txt {
            allow all;
            log_not_found off;
            access_log off;
        }
 
        # The following 2 rules are only needed for the user_webfinger app.
        # Uncomment it if you're planning to use this app.
        #rewrite ^/.well-known/host-meta /public.php?service=host-meta last;
        #rewrite ^/.well-known/host-meta.json /public.php?service=host-meta-json last;
 
        # The following rule is only needed for the Social app.
        # Uncomment it if you're planning to use this app.
        #rewrite ^/.well-known/webfinger /public.php?service=webfinger last;
 
        location = /.well-known/carddav {
            return 301 $scheme://$host:$server_port/remote.php/dav;
        }
 
        location = /.well-known/caldav {
            return 301 $scheme://$host:$server_port/remote.php/dav;
        }
 
        # set max upload size
        client_max_body_size 10G;
        fastcgi_buffers 64 4K;
 
        # Enable gzip but do not remove ETag headers
        gzip on;
        gzip_vary on;
        gzip_comp_level 4;
        gzip_min_length 256;
        gzip_proxied expired no-cache no-store private no_last_modified no_etag auth;
        gzip_types application/atom+xml application/javascript application/json application/ld+json application/manifest+json application/rss+xml application/vnd.geo+json application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/bmp image/svg+xml image/x-icon text/cache-manifest text/css text/plain text/vcard text/vnd.rim.location.xloc text/vtt text/x-component text/x-cross-domain-policy;
 
        # Uncomment if your server is build with the ngx_pagespeed module
        # This module is currently not supported.
        #pagespeed off;
 
        location / {
            rewrite ^ /index.php;
        }
 
        location ~ ^\/(?:build|tests|config|lib|3rdparty|templates|data)\/ {
            deny all;
        }
        location ~ ^\/(?:\.|autotest|occ|issue|indie|db_|console) {
            deny all;
        }
 
        location ~ ^\/(?:index|remote|public|cron|core\/ajax\/update|status|ocs\/v[12]|updater\/.+|oc[ms]-provider\/.+)\.php(?:$|\/) {
            fastcgi_split_path_info ^(.+?\.php)(\/.*|)$;
            set $path_info $fastcgi_path_info;
            try_files $fastcgi_script_name =404;
            include fastcgi_params;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            fastcgi_param PATH_INFO $path_info;
            # fastcgi_param HTTPS on;
 
            # Avoid sending the security headers twice
            fastcgi_param modHeadersAvailable true;
 
            # Enable pretty urls
            fastcgi_param front_controller_active true;
            fastcgi_pass php-handler;
            fastcgi_intercept_errors on;
            fastcgi_request_buffering off;
        }
 
        location ~ ^\/(?:updater|oc[ms]-provider)(?:$|\/) {
            try_files $uri/ =404;
            index index.php;
        }
 
        # Adding the cache control header for js, css and map files
        # Make sure it is BELOW the PHP block
        location ~ \.(?:css|js|woff2?|svg|gif|map)$ {
            try_files $uri /index.php$request_uri;
            add_header Cache-Control "public, max-age=15778463";
            # Add headers to serve security related headers (It is intended to
            # have those duplicated to the ones above)
            # Before enabling Strict-Transport-Security headers please read into
            # this topic first.
            #add_header Strict-Transport-Security "max-age=15768000; includeSubDomains; preload;" always;
            #
            # WARNING: Only add the preload option once you read about
            # the consequences in https://hstspreload.org/. This option
            # will add the domain to a hardcoded list that is shipped
            # in all major browsers and getting removed from this list
            # could take several months.
            add_header Referrer-Policy "no-referrer" always;
            add_header X-Content-Type-Options "nosniff" always;
            add_header X-Download-Options "noopen" always;
            add_header X-Frame-Options "SAMEORIGIN" always;
            add_header X-Permitted-Cross-Domain-Policies "none" always;
            add_header X-Robots-Tag "noindex, nofollow" always;
            add_header X-XSS-Protection "1; mode=block" always;
 
            # Optional: Don't log access to assets
            access_log off;
        }
 
        location ~ \.(?:png|html|ttf|ico|jpg|jpeg|bcmap|mp4|webm)$ {
            try_files $uri /index.php$request_uri;
            # Optional: Don't log access to other assets
            access_log off;
        }
        add_header Strict-Transport-Security "max-age=31536000; includeSubdomains;";
    }
}

That should be all the configuration you need to make the NextCloud Docker containers go.

The OnlyOffice Docker configuration

We also need to something similar (but easier) for OnlyOffice. This is the docker-compose.yml that I use:

cd /home/docker/onlyoffice $EDIT docker-compose.yml

and copy-and-paste this into it (replacing the []):

version: '3'
services:
  onlyoffice:
    image: onlyoffice/documentserver:latest
    restart: unless-stopped
    ports:
      - 127.0.0.1:9880:80
    environment:
#      - JWT_SECRET=[onlyoffice secret]
    volumes:
      - /home/data/onlyoffice/data:/var/www/onlyoffice/Data
      - /home/data/onlyoffice/logs:/var/log/onlyoffice
      - /home/data/onlyoffice/lib:/var/lib/onlyoffice
      - /home/data/onlyoffice/db:/var/lib/postgresql
    extra_hosts:
      - "[nextcloud domain]:[ipv4]"

Now, we can fire it up provisionally:

docker-compose up -d && docker-compose logs -f

We'll find the value of [onlyoffice secret] a bit later, below.

To get back to a command prompt without killing the running Docker container execute a CTRL-C.

Firing up your NextCloud!

Phew - congratulations on getting here! We've reached the moment of truth where we need to see if this whole thing will work!

We need to make sure we're back in the NextCloud Docker directory we set up:

cd /home/docker/nextcloud

Then you can run:

docker-compose up -d && docker-compose logs -f

This will trigger the initial download of the docker container images you've specified in your docker-compose.yml file. All going well, after a few minutes (longer or shorter depending on the speed of your server's connection) you should have download the Nginx, Redis, and NextCloud Docker images, and then the script will attempt to start them (bringing them "up" in daemon mode with the -d, meaning they'll keep running even if you log out) and then, if successful, the logs -f command will run and show you a stream of log messages from the containers, each preceded by the container name to which it corresponds. This should help you debug any problems that occur during the process (ideally, none).

Once you see log messages streaming past, and no obvious "container exited" or other error messages (which will usually contain the word "error" a lot), you should be able to point your browser at your selected domain name and have your fist visit to your NextCloud in your browser! Just point your web browser at https://[nextcloud domain] (replacing with your domain, of course. You should also try going to http://[nextcloud domain] (note the missing 's' from http) which should automatically redirect you to https://[nextcloud domain] as the reverse proxy file instructs.

Again, to get back to a command prompt without killing the running Docker containers execute a CTRL-C.

The NextCloud source code (if necessary)

Normally the source code for NextCloud's current stable version is transparently downloaded and installed by the NextCloud Docker container the first time it's instantiated. If it is, you'll see a bunch of files and directories in your /home/data/nextcloud/nextcloud folder. If so, you're fine and you can move on to the next step.

If not, you can always find the most recent stable release's source code here. I tend to prefer the .tar.bz2 archive format, so I get it from this link: https://download.nextcloud.com/server/releases/latest.tar.bz2 (which, fingers crossed, should remain valid indefinitely - if not, check the previous link or look for 'Download' on the NextCloud website.).

We need to get that file and extract it in /home/data/nextcloud, so do the following (if wget isn't already installed, get it via sudo apt install wget):

cd /home/data/nextcloud
wget https://download.nextcloud.com/server/releases/latest.tar.bz2
tar xvfj latest.tar.bz2

which will create a directory 'nextcloud' with the latest (stable) version of the NextCloud source code in that directory.

Then reassert the file permissions just to be sure

sudo chown -R www-data nextcloud

After that, you should be able to point your browser at your domain (the containers are already running) and see if it starts the install process as it should. [/code]

You can figure out what version that is by running:

cat nextcloud/version.php | grep VersionString

With my latest install, I get the result:

$OC_VersionString = '26.0.2';

Note, I tend to hold on to install archives for safety's sake, so I generally do the following to tidy up (still in the nextcloud data directory), replacing [version] with the advertised most recent stable version of NextCloud (26.0.2 in my case):

mkdir attic
mv latest.tar.bz2 attic/nextcloud_[version].tar.bz2

Now you've got the source code for NextCloud where you containers are configured to look for it!

Configuring database access

On doing so, if all is well, you should be directed through the database set up process for your NextCloud instance. You'll be asked for your database details, which should be:

database IP: 172.17.0.1 - this is the default IP of the Docker host server.
database name: [db name]
database user: [db user]
database password: [db password]

Configuring the Admin user

Once that's set and working, NextCloud will install all the relevant database tables and initial data. You'll be asked to set up an admin user account, which can be "admin" and some strong password you create (you can use the pwgen utility you used earlier) - I'd recommend recording it somewhere. I would not recommend making your own account, in your name, the main admin account. Instead, I recommend creating a second account, with administrator privileges, for yourself, but leave the admin account purely for administrative activities.

Configuring Outgoing Email

To allow your NextCloud instance to send outgoing email, so that your site can alert you to security updates that need to be applied, or so that any of your NextCloud users can request a password reset if they've forgot theirs. For this, you'll need the authenticating SMTP account details from the start of this process. You'll need:

SMTP server : an IP address or a domain name
SMTP username: a username or an email address
SMTP password: a strong password already configured for the username on that server
SMTP login security: whether login is via TLS, SSL, or unsecure (!!), and
SMTP login method: plain, encrypted, "login" or some other value.

You should be able to test your email settings to make sure the details you've entered are valid. If you need to adjust these settings later, you can go to the admin menu (top right of the web browser interface) and go to Admin->Basic Settings - should have a path of https://[nextcloud domain]/settings/admin.

Setting up OnlyOffice

The OnlyOffice server should already be running - if you point your browser at https://[onlyoffice domain] you should see a page like the attached screenshot with the OnlyOffice Logo and a title of "OnlyOffice Docs Community Edition".

Configuring OnlyOffice Integration with NextCloud

To configure your NextCloud to use your OnlyOffice, the OnlyOffice will require that NextCloud knows its "secret". To generate the secret, run this in /home/docker/onlyoffice:

docker-compose exec onlyoffice /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

The resulting secret string, which will look something like QC7QmEqUpXmmnwXZcvBQ needs to be added to your OnlyOffice docker-compose.yml file to ensure that the same code is used everytime you start OnlyOffice (if it isn't set, it'll be generated each time you restart OnlyOffice and your NextCloud will need a different 'secret' each time - a major inconvenience).

$EDIT /home/docker/onlyoffice/docker-compose.yml

Add it in place of [onlyoffice secret] and also remove the '#' that's commenting out the line - again, thanks to Stephen Harlow for pointing out that this is required! Then restart OnlyOffice via

docker-compose up -d

Docker will see that the container's configuration has changed and will restart the container.

Next you need to be logged into your NextCloud as an administartive user (your own user is fine if you've given it admin privileges).

You should have an "admin" menu (assuming you've created your user with Administrator privileges) at the top right of the web interface. If you go to Apps, you can install the new "Hub bundle" available under the "App bundles" option (see attached image). If you don't want the whole bundle you can just use the search box to search for "OnlyOffice" or go to the "Office & text" App category and enable the OnlyOffice "official" app, at which point it will automatically download the latest version of the connector app and install it (it should appear in your /home/data/nextcloud/apps directory)

Once you've done that, go to your top right menu again, selecting Admin, and you should see "OnlyOffice" as an option in the left column (which starts with "Basic settings"). Selecting that, you'll need to enter the following:

"Document Editing Service address": https://[onlyoffice domain]
"Secret key": [onlyoffice secret]

You don't need the 'advanced settings'.

When you're done, click "Save".

You can also select formats you'd like OnlyOffice to open and edit files of those types are clicked or created. I've selected the following: doc, docx, odp, ods, odt, ppt, pptx, xls, xlsx, and in the second section: csv and txt.

You can also make other editor customisations as you desire. The only Editor customisation setting I haven't selected is "Display Chat menu button" because NextCloud Hub provides an integrated Chat service, making this one within OnlyOffice an unnecessary distraction.

Once finished configuring, you should have the ability to go back to the home of your NextCloud install, which should show you your top-level folders. If you click the "+" next to the home icon (top left of the folder pane) you should now have the option to create (in addition to "Upload file", "New folder", "New text file") a "New Document", "New Spreadsheet", and "New Presentation". Clicking those should give you the OnlyOffice interface for the designated content type.

Similarly, you can use the "Upload file" to upload a document in a format that is supported by OnlyOffice. Once uploaded, clicking on the filename should open it for editing in the appropriate OnlyOffice interface.

It is saved as it is changed, so you shouldn't need to save it explicitly.

Keeping the whole thing up-to-date

So, as you're no doubt aware, both NextCloud and OnlyOffice are always being improved and updated. I certainly encourage you to keep your installations up-to-date.

While you'll periodically be alerted that NextCloud apps have available updates (these can be upgraded through the browser interface) updates to the NextCloud and OnlyOffice systems themselves need to be undertaken by upgrading their containers. Luckily it's easy to do although I strongly urge you to ensure you have a very recent backup of both database and uploaded files - they're the files in /home/data/nextcloud/data and /home/data/onlyoffice/ (note, backups of OnlyOffice are complicated somewhat by the fact that you can't reliably back up running PostgreSQL instance simply by backing up its files - see a solution below). Prior to updating my containers, I normally create an archive of my NextCloud code in the event the upgrade goes wrong and I need to recover quickly. I do it like this. In my /home/data/nextcloud directory, I create a new 'attic' directory:

cd /home/data/nextcloud && sudo mkdir attic

then I create an archive of my entire NextCloud source directory in the attic directory:

DATE=date +%Y%m%d && sudo tar cvfz attic/nextcloud-${DATE}.tgz --exclude "data" nextcloud

If you need to recover files from it, you can untar it (assuming you have sufficient disk space! Best to be mindful of that!) via

sudo mkdir tmp && cd tmp && tar xvfz ../attic/nextcloud-${DATE}.tgz

although if you're doing it in a different SSH session (e.g. after the fact) you might have to manually enter the DATE part of the filename.

Once you've got a backup of your NextCloud source code, updating the container should be as easy as either doing another

docker-compose pull

and then restarting the service with the new containers via

docker-compose up -d

which will remove any old containers (this won't remove any data you want to save if you followed the directions above! But remember to do it in the right directory!) and start up the new versions you've just pulled.

Use docker-compose logs -f to watch the logs - you'll likely see useful debugging information in the unlikely event that something goes wrong in the upgrade process.

Backing up NextCloud

To back up your instance on your server, you need two things: a file system backup of your /home/data/nextcloud directory, and database dumps of your database.

There're lots of ways to back up your files (I've recently updated to using a system called Restic to make off-server incremental encrypted backups - I plan to document this in a future howto! - although there're other documented approaches - leave a comment below if you'd like to learn more about my approach!).

Backing up your MariaDB databases is as easy installing automysqlbackups:

sudo apt install automysqlbackups

You'll find daily versioned dumps of your MariaDB database(s) in /var/lib/automysqlbackups on your VM host's filesystem. To run an ad hoc backup (which will replace the previous backup from that day, if there is one) just run

sudo automysqlbackups

Backup OnlyOffice

Along with backing up the files in your /home/data/onlyoffice directory, you'll also want a proper "dump" of your PostgreSQL backup (you can write simple bash scripts to do this regularly, automatically), particularly prior to doing an upgrade (to allow for recovery if something goes badly wrong, which is always possible). You can achieve this by going to

cd /home/docker/onlyoffice

and running this

DATE=$(date +%Y%m%d) && FILE=/home/data/onlyoffice/backup/fullbackup-${DATE}.sql && docker-compose exec onlyoffice sudo -u postgres pg_dumpall > ${FILE} && gzip ${FILE}

which will assign the current date to DATE, the relevant filename to FILE, and then put the backup SQL into a dated file called $FILE and compress the result with gzip :)

At some point, I'll modify my normal versioned PostgreSQL-in-a-Docker-Container dated database backup scripts to cater for this solution and make the result available on https://git.oeru.org - it'll probably be a small modification to this script: https://git.oeru.org/oeru/docker-compose-dbbackup in case someone wants to beat me to it!

Add new comment

Installing and Upgrading Moodle with Docker Compose on Ubuntu 22.04

dave — Sun, 22 May 2022 23:13:24 +0000

Installing and Upgrading Moodle with Docker Compose on Ubuntu 22.04

Blog tags

ubuntu linux

22.04

docker compose

docker

mysql

mariadb

nginx

let's encrypt

dave Mon 23/05/2022 - 11:13

Note: work in progress

Moodle is probably (there's little agreement among the pundits) the market-leading Free and Open Source Software (FOSS) Learning Management System (LMS). It's pretty much everywhere. Here's how you can set up and maintain your own Moodle instance(s).

Prerequisites
Installing Moodle on Ubuntu 22.04 with Docker Compose
Backing up your data
- MariaDB database dumps
Upgrading Moodle with Git

Prerequisites

If you would like to host your own (and we certainly encourage it!) using the same approach we use at the OER Foundation here is how you get started:

Set up a Virtual Private Server (VPS) and configure it to run Ubuntu Linux and Docker Compose.
Make sure any administrative users can log into the VPS securely via Secure Shell (SSH).

From that point, use the following process.

Installing Moodle on Ubuntu 22.04 with Docker Compose

The process for completing the install involves

setting up a domain name (or subdomain) to point at the server so people can easily find the Moodle site,
installing all the relevant code via 'Git' on the VPS' file system,
configuring the Docker Compose file, defining the set of Docker containers comprising this site's moving parts, and 'pulling' the component containers (to download the current versions of each to our VPS),
adding the 'default configuration' for the Dockerised NGINX instance, so it knows how to server Moodle from the adjacent containers,
configuring the NGINX webserver running on the VPS to act as a 'reverse proxy' as well as using to generate a Let's Encrypt Secure Sockets Layer (SSL) certificate to encrypt and otherwise secure users' interactions with the Moodle instance, and finally
configuring the Moodle instance itself.

Configure a domain name

Configuring a domain name requires us to register a domain with a 'domain registrar' - we use one called Metaname, based here in Christchurch, New Zealand - and using the registrar's browser based configuration system to create a 'zone file' which defines the server to which the domain points. Each registrar is likely to have their own bespoke zone file configuration tools, so consider this to be just one example.

Our convention at the OERF is to allocate a default domain name to each VPS we create. Each one hosts one or more Free and Open Source Software services. Each of those services has its own domain name. Usually we designate "A" and "AAAA" records for the default domain name pointing to the IPv4 and IPv6 addresses given to the VPS by the cloud services provider.

For the purposes of this tutorial, we'll create a site called moodletest.milll.ws which is the moodletest subdomain of the milll.ws (Ministry for Education, Sport, and Culture's 'innovative Lifelong Learning Lab', aka MiLLL, in (western) Samoa). We use a "CNAME" to point the subdomain at the VPS' official name, sandbox.milll.ws, which is how its A and AAAA records identify it (via its IPv4 and IPv6 addresses).

So our "Fully Qualified Domain Name" (FQDN) is moodletest.milll.ws.

To prepare for the rest of this tutorial, we're going to set a variable for your selected domain name. Do that by typing this at your command prompt. It will set this variable ''for this session'':

FQDN=your domain name

in our case, it'd be

FQDN=moodletest.milll.ws

The following will assuming that this value is set correctly.

Install the Moodle source code

Before we can install the Moodle source code, we have to prepare a sensible place for it to live. We do that by creating suitable directories for both the Docker configurations and the Moodle instance data and configuration as follows:

sudo mkdir -p /home/docker/${FQDN} /home/data/${FQDN}

That creates two directories as you can see. We need to go into the data directory:

cd /home/data/${FQDN}

and in there, we'll execute this git command to download the entire Moodle codebase:

sudo git clone https://github.com/moodle/moodle.git src

When that finishes, go into the source directory:

cd src

Here, we'll have to execute this new command, which we use to declare this a 'safe' git directory, which helps protect us from nefarious parties running git commands in dangerous places if they can get access to our server via some other security vulnerability...

sudo git config --global --add safe.directory /home/data/${FQDN}

Then we can run this comman:

git branch -a

This should give you a list of all the Moodle repository version 'tags'.

In this case, we're going to install a stable (but not the latest) version of Moodle - to do that we tell git what tag we're going to track:

sudo git branch --track MOODLE_310_STABLE origin/MOODLE_310_STABLE

And then, to make sure that our Docker container's nginx webserver can read these files (they need to be owned by the www-data users, and I (user 'dave') can run git commands without needing to use sudo. Replace with your own user name here!

sudo chown -R www-data:dave ../src
sudo chmod -R g+w ../src
ls -l
git status
git checkout MOODLE_310_STABLE

Configure Docker Compose to host Moodle

The first step to running anything with Docker Compose - which helps you combine a set of Docker containers together into a useful, maintainable service - is to create docker-compose.yml file. It usually contains the full 'recipe' for the service.

Go to the relevant docker directory and create and edit the file:

cd /home/docker/${FQDN}

sudo nano docker-compose.yml

And copy and past in this content (with FQDN occurrences and [secret password] placeholders to be replaced appropriately, of course):

version: '3'
 
services:
    mariadb:
        image: mariadb:10
        container_name: db
        environment: 
            MYSQL_RANDOM_ROOT_PASSWORD: 1
            MYSQL_DATABASE: moodle
            MYSQL_USER: moodle
            MYSQL_PASSWORD: [secret MariaDB password]
        volumes:
            - /home/data/FQDN/mariadb:/var/lib/mysql
    moodle:
        image: oeru/moodle:php74-fpm
        environment:
            MOODLE_DOMAIN: FQDN
            MOODLE_DB_HOST: mariadb
            MYSQL_PORT_3306_TCP: 3306
            MOODLE_DB_NAME: moodle
            MOODLE_DB_USER: moodle
            MOODLE_DB_PASSWORD: [secret MariaDB password]
        volumes:
            - /home/data/FQDN/src:/var/www/html
            - /home/data/FQDN/data:/var/www/moodledata
        restart: unless-stopped
        depends_on:
            - mariadb
    cron:
        image: oeru/moodle-cron:php74-fpm
        environment:
            MOODLE_DOMAIN: FQDN
            MOODLE_DB_HOST: mariadb
            MYSQL_PORT_3306_TCP: 3306
            MOODLE_DB_NAME: moodle
            MOODLE_DB_USER: moodle
            MOODLE_DB_PASSWORD: [secret MariaDB password]
        volumes:
            - /home/data/FQDN/src:/var/www/html
            - /home/data/FQDN/data:/var/www/moodledata
        restart: unless-stopped
        depends_on:
            - mariadb
    nginx:
        image: nginx
        depends_on:
            - moodle
        ports:
            - 127.0.0.1:8080:80
        volumes:
            - /home/data/FQDN/nginx:/etc/nginx/conf.d
            - /home/data/FQDN/src:/var/www/html
        restart: unless-stopped

And, naturally, save the file.

Note, the last stanza of the docker-compose.yml file, defining the NGINX component, specifies a port number on the host machine (i.e. 'localhost' or 127.0.0.1) of 8080, which in turn points to port 80 on the NGINX container. If this is the only Docker Compose configuration on your server, then 8080 is probably an avaiable port to use, but if you server has lots of other Docker Compose (or other sorts of services on it) port 8080 might not be available. You can check by running

sudo netstat -punta

If netstat isn't installed, you can install it via sudo apt install net-tools.

Running this command will give output that looks something like this:

Active Internet connections (servers and established)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name    
tcp        0      0 0.0.0.0:80              0.0.0.0:*               LISTEN      11199/nginx: master 
tcp        0      0 0.0.0.0:25              0.0.0.0:*               LISTEN      60021/master        
tcp        0      0 0.0.0.0:22              0.0.0.0:*               LISTEN      59473/sshd: /usr/sb 
tcp        0      0 127.0.0.53:53           0.0.0.0:*               LISTEN      11263/systemd-resol 
tcp        0      0 127.0.0.1:8080          0.0.0.0:*               LISTEN      94497/docker-proxy  
tcp        0      0 127.0.0.1:6010          0.0.0.0:*               LISTEN      13691/sshd: dave@pt 
tcp        0      0 127.0.0.1:6011          0.0.0.0:*               LISTEN      13097/sshd: dave@pt 
tcp        0      0 147.182.232.12:22       203.118.159.63:39248    ESTABLISHED 13044/sshd: dave [p 
tcp        0      0 147.182.232.12:22       202.4.38.248:54655      ESTABLISHED 94900/sshd: william 
tcp        0      0 147.182.232.12:22       202.4.38.248:53108      ESTABLISHED 91961/sshd: sialofi 
tcp        0     52 147.182.232.12:22       203.118.159.63:39650    ESTABLISHED 13638/sshd: dave [p 
tcp        0      0 147.182.232.12:22       202.4.38.248:62921      ESTABLISHED 92704/sshd: eleanor 
tcp6       0      0 :::80                   :::*                    LISTEN      11199/nginx: master 
tcp6       0      0 :::25                   :::*                    LISTEN      60021/master        
tcp6       0      0 :::22                   :::*                    LISTEN      59473/sshd: /usr/sb 
tcp6       0      0 ::1:6010                :::*                    LISTEN      13691/sshd: dave@pt 
tcp6       0      0 ::1:6011                :::*                    LISTEN      13097/sshd: dave@pt 
udp        0      0 127.0.0.53:53           0.0.0.0:*                           11263/systemd-resol

You'll notice that in this case, the 7th line says

tcp 0 0 127.0.0.1:8080 0.0.0.0:* LISTEN 94497/docker-proxy

which means that port 8080 is already in use with 127.0.0.1 on the server and trying to start my containers with that port defined would result in a 'port unavailable' error.

Here's a quick one-liner allowing you to check whether any particular port is in use right now (replace '8080' with whatever port number you're checking):

sudo netstat -punta | grep '8080'

if it returns nothing, that port is ''currently'' unused. If it returns a line like

tcp 0 0 127.0.0.1:8080 0.0.0.0:* LISTEN 94497/docker-proxy

it's in use and you'll need to choose another port, e.g. 8081 or 8070 or something else. Ports over 8000 are unlikely to be used by most normal software so should be fair game. You can verify that your selected port is available before launching your containers.

Download your containers from Docker Hub

You should then be able to 'pull' the relevant Docker images (might take a while depending on your server's location and available bandwidth):

sudo docker-compose pull

Once that's done, we need to make sure that our container running NGINX webserver has a valid Moodle-specific configuration.

Configure NGINX container for Moodle

To do that, we're going to create an NGINX default configuration for the Moodle containers by creating and editing the file:

sudo nano /home/data/${FQDN}/nginx/default.conf

copying and pasting in the following content. It shouldn't require any changes.

# This configuration is used by a Docker container running nginx, and is not intended to be
# directly connected to the Internet (for that we recommend using SSL on port 443).
# You should reverse proxy this container on the Docker host using whatever webserver
# you have running there.
#
server {
    listen 80 default_server;
 
    # default path to Mautic - from the point of view of the docker container
    root /var/www/html;
    index index.php index.html index.htm;
    fastcgi_keep_conn on; # keep alive to the FCGI upstream
    location / {
        # First attempt to serve request as file
        try_files $uri $uri/index.php;
 
        # moodle rewrite rules
        rewrite ^/(.*.php)(/)(.*)$ /$1?file=/$3 last;
    }
    # php parsing
 
    location ~ ^(.+\.php)(.*)$ {
        fastcgi_split_path_info  ^(.+\.php)(.*)$;
        fastcgi_index index.php;
        fastcgi_pass moodle:9000;
        include /etc/nginx/mime.types;
        include fastcgi_params;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_buffer_size 128k;
        fastcgi_buffers 256 4k;
        fastcgi_busy_buffers_size 256k;
        fastcgi_temp_file_write_size 256k;
        client_max_body_size 100M;
    }
    add_header 'Access-Control-Allow-Origin' "*";
}

Once this is in place, you can start up the Docker containers like this (as your own user!):

docker-compose up -d && docker-compose logs -f

which will start the containers (the up -d) in 'daemon mode', where they continue to run even if you log out of the server, and then show you the logging from the containers (the logs -f) part. To exit the log view (which will update automatically as more log messages are created), hit the CTRL-C key combination. If there're any errors from your individual containers, they should visible here.

That's it, your Docker containers should be running. Once you're out of the log view, you can always check on your containers by going into the /home/docker/FQDN directory and executing:

docker-compose ps

which should show you a list of the currently running containers and their states. Here's an example:

           Name                         Command               State           Ports         
--------------------------------------------------------------------------------------------
db                           docker-entrypoint.sh mariadbd    Up      3306/tcp              
moodletestmilllws_cron_1     /entrypoint.sh /bin/sh -c  ...   Up      9000/tcp              
moodletestmilllws_moodle_1   /entrypoint.sh php-fpm           Up      9000/tcp              
moodletestmilllws_nginx_1    /docker-entrypoint.sh ngin ...   Up      127.0.0.1:8080->80/tcp

or, to get a bit more info, you can run

docker-compose top

which should show you a bit more information about the different running containers and their active processes. Here's an example:

db
UID    PID    PPID    C   STIME   TTY     TIME       CMD   
-----------------------------------------------------------
lxd   12056   12035   0   May23   ?     00:04:06   mariadbd
 
moodletestmilllws_cron_1
UID     PID    PPID    C   STIME   TTY     TIME                         CMD                     
------------------------------------------------------------------------------------------------
root   12244   12201   0   May23   ?     00:00:00   /bin/sh -c cron && tail -f /var/log/cron.log
root   12651   12244   0   May23   ?     00:00:02   cron                                        
root   12652   12244   0   May23   ?     00:00:13   tail -f /var/log/cron.log                   
 
moodletestmilllws_moodle_1
  UID       PID    PPID    C   STIME   TTY     TIME                              CMD                         
-------------------------------------------------------------------------------------------------------------
root       12250   12173   0   May23   ?     00:00:12   php-fpm: master process (/usr/local/etc/php-fpm.conf)
www-data   37755   12250   2   01:46   ?     00:00:00   php-fpm: pool www                                    
www-data   37757   12250   1   01:46   ?     00:00:00   php-fpm: pool www                                    
www-data   37758   12250   1   01:46   ?     00:00:00   php-fpm: pool www                                    
www-data   37759   12250   0   01:46   ?     00:00:00   php-fpm: pool www                                    
 
moodletestmilllws_nginx_1
  UID       PID    PPID    C   STIME   TTY     TIME                        CMD                    
--------------------------------------------------------------------------------------------------
root       13207   13179   0   May23   ?     00:00:00   nginx: master process nginx -g daemon off;
systemd+   13333   13207   0   May23   ?     00:00:01   nginx: worker process                     
systemd+   13334   13207   0   May23   ?     00:00:00   nginx: worker process

So, now we should have all the relevant containers for your Moodle instance running... Al that's left to do is hook up the reverse proxy configuration creating that last vital link: between your browser's request and the Moodle service (secured by Let's Encrypt)!

Create a secure reverse-proxy configuration

The first step to doing that is to create a reverse proxy configuration:

sudo nano /etc/nginx/sites-available/${FQDN}

Copy and paste the following into the file. Of course, you will want to replace every occurrence of 'FQDN' with your own domain name.

server {
    # add [IP-Address:]80 in the next line if you want to limit this to a single interface
    listen 80;
    listen [::]:80;
 
    server_name FQDN;
 
    root /var/www/html;
 
    # for let's encrypt renewals!
    include includes/letsencrypt.conf;
 
    access_log /var/log/nginx/FQDN_access.log;
    error_log /var/log/nginx/FQDN_error.log;
 
    # redirect all HTTP traffic to HTTPS.
    location / {
       return  302 https://$server_name$request_uri;
    }
}
 
# This configuration assumes that there's an nginx container talking to the moodle PHP-fpm container,
# and this is a reverse proxy for that Moodle instance.
fastcgi_cache_path /etc/nginx/cache levels=1:2 keys_zone=moodle:100m inactive=1d max_size=100m;
fastcgi_cache_key "$scheme$request_method$host$request_uri";
 
server {
    # add [IP-Address:]443 in the next line if you want to limit this to a single interface
    listen 443 ssl;
    listen [::]:443 ssl;
 
    ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
    ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
#    ssl_certificate /etc/letsencrypt/live/FQDN/fullchain.pem;
#    ssl_certificate_key /etc/letsencrypt/live/FQDN/privkey.pem;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
 
    # A strong ssl_dhparam will help secure your server from certain kinds of attacks. 
    # It is commented out unless you've created it (if it's uncommented but doesn't exist
    # nginx won't start). To create one, see 
    # https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html
    # note: it can take 5-30 minutes to create one.
    #ssl_dhparam /etc/ssl/certs/dhparam.pem;
    #ssl_stapling on;
    #ssl_stapling_verify on;
 
    ssl_session_tickets off;
    resolver_timeout 5s;
    keepalive_timeout 20s;
 
    server_name FQDN;
 
    # for let's encrypt renewals!
    include includes/letsencrypt.conf;
 
    access_log /var/log/nginx/FQDN_access.log;
    error_log /var/log/nginx/FQDN_error.log;
 
    client_max_body_size 100M;
 
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;
    }
}

Once you've saved that file, we need to make sure NGINX can see the configuration - we do that by creating a 'symbolic link' between our configuration file in the sites-available directory and the sites-enabled directory as follows:

sudo ln -sf /etc/nginx/sites-available/${FQDN} /etc/nginx/sites-enabled/

Before we can restart NGINX with this new configuration, we have to make sure that the 'letsencrypt.conf' cited in our configuration file exists. We do that by creating a new directory:

sudo mkdir /etc/nginx/includes

and creating the letsencrypt.conf file:

sudo nano /etc/nginx/includes/letsencrypt.conf

into which we copy and paste the following:

#############################################################################
# Configuration file for Let's Encrypt ACME Challenge location
# This file is already included in listen_xxx.conf files.
# Do NOT include it separately!
#############################################################################
#
# This config enables to access /.well-known/acme-challenge/xxxxxxxxxxx
# on all our sites (HTTP), including all subdomains.
# This is required by ACME Challenge (webroot authentication).
# You can check that this location is working by placing ping.txt here:
# /var/www/letsencrypt/.well-known/acme-challenge/ping.txt
# And pointing your browser to:
# http://xxx.domain.tld/.well-known/acme-challenge/ping.txt
#
# Sources:
# https://community.letsencrypt.org/t/howto-easy-cert-generation-and-renewal-with-nginx/3491
#
# Rule for legitimate ACME Challenge requests
location ^~ /.well-known/acme-challenge/ {
    default_type "text/plain";
    # this can be any directory, but this name keeps it clear
    root /var/www/letsencrypt;
}
# Hide /acme-challenge subdirectory and return 404 on all requests.
# It is somewhat more secure than letting Nginx return 403.
# Ending slash is important!
location = /.well-known/acme-challenge/ {
    return 404;
}

In turn, we also have to make sure that the directory stipulated in the letsencrypt.conf file exists - we'll attempt to create the directory, which won't hurt anything if it already exists:

sudo mkdir /var/www/letsencrypt

With that done, we can test NGINX's configuration:

sudo nginx -t

If it's free of errors (there might be a warning related to the snakeoil ''temporary'' certificates we've specified. That's ok - we just specified them so that we can get NGINX restarted in a way that let's us request an SSL certificate from Let's Encrypt!), we can get NGINX to reload its configuration, so that it'll know how to respond to requests for the FQDN domain!

sudo service nginx reload

If that returns without errors, we're in business! It's time to make our Let's Encrypt certificate. Creating one is easy:

sudo letsencrypt certonly --webroot -w /var/www/letsencrypt -d ${FQDN}

In our case, it's:

sudo letsencrypt certonly --webroot -w /var/www/letsencrypt -d moodletest.milll.ws

Running that should trigger output like this:

Saving debug log to /var/log/letsencrypt/letsencrypt.log
Enter email address (used for urgent renewal and security notices)
 (Enter 'c' to cancel): webmaster@milll.ws
 
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf. You must
agree in order to register with the ACME server. Do you agree?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: y
 
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you be willing, once your first certificate is successfully issued, to
share your email address with the Electronic Frontier Foundation, a founding
partner of the Let's Encrypt project and the non-profit organization that
develops Certbot? We'd like to send you email about our work encrypting the web,
EFF news, campaigns, and ways to support digital freedom.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: y
Account registered.
Requesting a certificate for moodletest.milll.ws
 
Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/moodletest.milll.ws/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/moodletest.milll.ws/privkey.pem
This certificate expires on 2022-08-21.
These files will be updated when the certificate renews.
Certbot has set up a scheduled task to automatically renew this certificate in the background.
We were unable to subscribe you the EFF mailing list because your e-mail address appears to be invalid. You can try again later by visiting https://act.eff.org.
 
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

... which means you've successfully received a new certificate! Now you can update your NGINX reverse proxy configuration:

sudo nano /etc/nginx/sites-available/${FQDN}

to change it as follows (again, make sure you've replaced FQDN with your actual domain name!)

#    ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
#    ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
    ssl_certificate /etc/letsencrypt/live/FQDN/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/FQDN/privkey.pem;

Once you've saved the file you can test your NGINX configuration:

sudo nginx -t

and if it doesn't return any errors (nor should it return warnings), you can reload NGINX's config to make your new secure configuration live!

sudo service nginx reload

Installing Moodle

Now that we've filled in all the parts of the tool-chain, your server is ready to receive requests for your Moodle site! You should be able to go to your web browser on your local computer and enter the URL, replacing FQDN with your domain name of course:

https://FQDN

(and entering http://FQDN should automatically redirect to https://FQDN - feel free to test it!)

And if all is well, your Docker Compose stack running Moodle should respond by serving you up a page that looks like the attached "Install page" screenshot.

You'll probably notice it looks a bit rough, as, for the moment at least, the Cascading Style Sheets (aka CSS, the code that determines how web content looks) won't be loading correctly. We'll address that shortly.

We need to get through the installation of Moodle first, during which time, the Moodle system creates your config.php file in the /home/data/${FQDN}/src/ directory. Once that's created, you'll be able to edit the file and make the tweaks to fix this problem.

But first you'll need to proceed with the installation process - you'll be asked to select your language. And then you can click 'next' to continue. You'll be asked to specify your database (pick 'MariaDB' in this case) and then you'll be asked for the database details, as showing in the attached screenshot.

Your host will be db, your database name and user will both be moodle (case sensitive!) and you'll have to enter the database password you put into your docker-compose.yml file.

Then you should get a page showing you that your setup meets Moodle's requirement for installation (see attached screenshot), and finally you'll be asked to proceed with the install. Do so!

The installation will create the relevant database tables in the moodle database via the MariaDB container, and Moodle will create the aforementioned config.php file. The next thing to do is edit that file:

sudo nano /home/data/${FQDN}/src/config.php

where you'll tweak the configuration file so that the line

$CFG->wwwroot = 'http://moodletest.milll.ws';

looks like (note the shift from ''http'' to ''https''):

$CFG->wwwroot = 'https://moodletest.milll.ws';

And add this line above the final comment (the lines starting with '//')

$CFG->sslproxy=true;

which informs the Moodle system that it's sitting behind an SSL reverse proxy so it can adjust its behaviour accordingly.

So it should look something like this:

<?php  // Moodle configuration file

unset($CFG);
global $CFG;
$CFG = new stdClass();

$CFG->dbtype    = 'mariadb';
$CFG->dblibrary = 'native';
$CFG->dbhost    = 'db';
$CFG->dbname    = 'moodle';
$CFG->dbuser    = 'moodle';
$CFG->dbpass    = '[your super-secret db password]';
$CFG->prefix    = 'mdl_';
$CFG->dboptions = array (
  'dbpersist' => 0,
  'dbport' => 3306,
  'dbsocket' => '',
  'dbcollation' => 'utf8mb4_general_ci',
);

$CFG->wwwroot   = 'https://moodletest.milll.ws';
$CFG->dataroot  = '/var/www/moodledata';
$CFG->admin     = 'admin';

$CFG->directorypermissions = 0777;

$CFG->sslproxy=true;

require_once(__DIR__ . '/lib/setup.php');

// There is no php closing tag in this file,
// it is intentional because it prevents trailing whitespace problems!
?>

Save your updated config.php file, and return to the installation process - after the next button press, when the Moodle installer page loads, you should suddenly see the interface look all beautiful and tidy as the CSS suddenly loads.

You'll be asked set some properties for your site, like giving it a name, and finally, you'll have to provide the details of an 'admin' user - I recommend creating a default admin user, 'admin', with a very strong password. You'll log in with that admin user (and provide the details to your organisation so that there's a bit of succession planning, if you're not available at some point) just this once, and immediately create a new user for ''yourself'' with your preferred details, which you'll then elevate to 'administrator' privileges, and then do all your administration of the site via your own user.

Once you've successfully completed defining an admin user, you'll end up at the admin 'dashboard', where you can create the personal administrator user for yourself. And then you can log out as 'admin' and log in as yourself... at which point, you're done! Moodle is installed. Hazzah!

Backing up your data

The way we run Docker Compose, all the files we want to preserve are stored on the VPS's own filesystem. The Docker containers only store 'volatile' data. That means we can literally remove the Docker containers at any time, and it won't (under normal circumstances) affect our precious data. The only time it ''might'' is when data, e.g. in the database, is held in system memory rather than being written to disk.

That means that making backups of our data can be achieve simply by copying files on the hard disk - and if we're really interested in preserving that data, we'll send it somewhere else - on a different computer, in a different geographic region, and ideally managed by a different company - to achieve suitable diversity.

MariaDB database dumps

The only element of our stack which isn't amenable to this file copying is the data managed by MariaDB. It is ''not'' generally safe to copy the files of a running database and to expect that restarting the database with those copied files will result in an uncorrupted data set. To safely backup a database, you either have to shut it down (which is disruptive and inelegant) or you have to get it do a database 'dump' while it's running (which it can usually do very quickly, without noticable impact on the performance of the database.

A database 'dump' is a frozen snapshot of the data in a generic form, usually SQL. It allows us to restore the database tables, the data they contain, and the relationships (indices, foreign keys, etc.) between the tables. It usually even lets us take data from an older version of MariaDB and import it into a newer version (which is very handy!).

So we need a method for periodically - and automatically - creating database dumps of our MariaDB Moodle database. Luckily, it's not too hard. I've created this script to do it.

Upgrading Moodle with Git

Add new comment

Installing BigBlueButton on an OERu Docker Server

dave — Wed, 10 Nov 2021 02:42:41 +0000

Installing BigBlueButton on an OERu Docker Server

Blog tags

BigBlueButton

ubuntu linux

20.04

docker

docker-compose

postgresql

postfix

nginx

let's encrypt

dave Wed 10/11/2021 - 15:42

This tutorial was developed for the Samoan Knowledge Society Initiative, in which the OER Foundation is very pleased to be involved. (Update 2022-02-10: we have also created a video tutorial based on this written tutorial)

BigBlueButton (BBB) is a full-featured video conferencing system designed for large scale remote learning at the university level. In some ways, BBB goes beyond feature parity with widely used proprietary video conferencing systems like Zoom or Microsoft Teams, Webex, or Google Hangouts. It's main differences are that BBB

was designed from the gound up for educational use, and
is Free and Open Source Software (FOSS) and anyone can install it (as we describe in this tutorial) at no cost other than whatever cost you pay for hosting the application and a bit of your time.

You can read all about BigBlueButton and how it works using the excellent documentation provided by its development community.

There are no per-user license fees (or any fees), and your users don't need to install special software, vastly simplifying its adoption: BBB works brilliantly on any desktop computer, laptop, or mobile device (tablet or phone) with a modern web browser that implements the WebRTC open web standard (which is all modern browsers).

The source code for BBB's internal components, and its many ancillary tools is available for anyone to learn from or improve - that's the fundamental benefit of FOSS. Since the outbreak of COVID19, the team at a small Ottowa, Canada-based company, Blindside Networks, has been working tirelessly with the BBB community to improve the BBB code, which is being used all over the world by millions of people every day.

This tutorial walks you through provisioning and building your own BigBlueButton instance on a server running Ubuntu GNU/Linux - version 20.04 is the Long Term Support (LTS) version as of this writing - using Docker containers for the various software services and components, with the containers managed by Docker Compose.

Table of contents

Introduction
- References
- Copying and pasting
Information you need to know
Preferences
Set up your virtual server
Configure your Domain to point at your Server
- Best Practice: access your server as a non-root user
A few post-install updates
- Update the server's hosts file
Firewall Configuration
Install Postfix so the server can send email
- Email test
Install Nginx webserver and Let's Encrypt tools
Set up COTURN certificates
Set up Nginx Reverse Proxy Configuration
- Extra security with dhparam.pem
Install Docker
Install Docker-compose
Git-Clone BBB Docker repository
Configure your BBB
- Fix minor configuration error that blocks JODConverter
Build your BBB
Visit your new BBB
Create an admin user:
Run your first conference
Next Steps

Introduction

References

For this tutorial, we are using a Digital Ocean 'Droplet' as our cloud server. You can use an almost identical process to provision a server from any one of a thousand other commodity GNU/Linux cloud hosting providers.

To demonstrate the process of defining a sub domain and its IPv4 and IPv6 addresses (via A and AAAA records respectively) I'm using my preferred local domain registrar Metaname (based here in Christchurch, New Zealand, as am I. I know the developer/owner of the service and I trust him). You can use any domain registrar that gives you the ability to configure your 'DNS zone file'. Some of might have your own DNS server or institutional name servers, in which case you might have to request these changes be made on your behalf.

Copying and pasting

We will be providing a bunch of command lines that you can copy and paste into a terminal on the computer you're using to access your virtual server. Links like

this one

are intended for you to copy and paste into the command line. On Linux, please note that in some cases if "CTRL-V" doesn't work to paste, try using "CTRL+SHIFT+V" (that's because in some terminals, "CTRL+V" had a pre-existing purpose as terminals have been around since long before desktops and 'copy-paste" were invented and the arbitrary CTRL-C, CTRL-X, CTRL-V key combos were chosen by Microsoft without any consideration for prior art). Similarly, if you want to copy from a terminal, you might need to use "CTRL+SHIFT+C". Try it.

When we ask you edit a file (using the editor you choose to assign to the EDIT shell variable below), we expect you to complete the recommended changes, and then save the file and exit back to the command line.

We'll aim to show you what to change using a 'code' box:

Like this one
which is suitable
for multi-line
content (like what you 
find in a file)

Information you need to know

Info you need to have handy to complete this tutorial:

You need to know the IPv4 address of your server. Token: [IPv4] - it'll be in the form of nnn.nnn.nnn.nnn where nnn = 0-254, example value 143.110.228.88
If your server has one, you need to know its IPv6 address. Token: [IPv6] - it'll be in the form of hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh where h = 0-9a-f, i.e. a hex value, example 2604:a880:4:1d0::402:b000
You need to have a domain name (or a sub domain name) to point at your server's IPv4 and IPv6. Token: [Domain], example domain bbbtest.milll.ws (in this case, bbbtest is the subdomain of the milll.ws domain)
The email address your server should send status or admin-related email to. Token [Admin email], example webmaster@[Domain]
You'll need a set of authenticating SMTP account settings including - these can be used both on the host and in the BBB installation:
- [SMTP server] - the domain name or IP address of an existing SMTP server, e.g. about.oerfoundation.org (our one), or smtp.googlemail.com,
- [SMTP port] - the port number for the service you're using. It'll usually be one of 587 or 465. Older, unauthenticated SMTP servers used to use port 25, but that's now blocked by most ISPs due to its abuse by spammers.
- [SMTP security] - usually this'll be something like 'SSL' (usually associated with port 465) or 'StartTLS' (usually associated with port 587).
- [SMTP username] - the username - often an email address - for the authenticating SMTP service, and lastly,
- [SMTP password] - the password accompanying the username.
You'll want an email address that you can check to send test emails to: token [Test email], e.g. you@youremailprovider.tld, and finally
You'll want a 'from' email address that users of your system will see when they get emails from you. Token: [Outgoing email], e.g. notifications@milll.ws.

Preferences

You'll need to copy and paste the following lines into any terminal you're using to complete this tutorial, so that that session is aware of your preferred values:

EDIT=$(which nano)

SITE=bbbtest.milll.ws

We're going to reference these periodically in the following process, so it's important you set these correctly. To verify them, you can run this in any terminal at any time to verify that the values are still defined and current:

echo "Our variables = $EDIT and $SITE"

Set up your virtual server

You'll need to log into your cloud service provider's dashboard - in our case, we've used DigitalOcean. That means pointing our browser to https://digitalocean.com and either using "Log In" (if we already have an account) or "Sign Up" (if we don't).

Once you're logged in, you'll want to go to 'Create' and select 'Droplets' (Digital Ocean calls each of their virtual servers a "Droplet").

We've included a screenshot of the Create Droplet page, with the relevant options selected. They are as follows:

Choose an image: we choose 'Ubuntu 20.04 LTS'
Choose a plan: we choose 'Basic'
- for CPU options: we choose 'Premium AMD with NVMe SSD'
- for the size, we choose either the '$24/mo' (choose the '$48/mo' option if you want to be able to support large groups, like 100+ simultaneous participants).
Choose a datacenter region: we choose 'San Franciso, zone 3' (which we've determined to be in the 'centre of the internet', i.e. the most central point to give the best website performance to a global audience. You might want to try a different place depending on your location in the globe and your audience).
VPC Network - we just leave the default.
Select additional options: we check 'IPv6' and 'Monitoring' but not User data.
Authentication: if we have added one or more SSH keys to our DigitalOcean profile select 'SSH keys'. If not, you can select 'Password'. It's far more efficient and secure to use SSH whereever possible.
We're ony creating 1 Droplet and we Choose a hostname of [Domain]
We don't need to add any tags
We won't Add backups.

Then we can Create Droplet...

When the Droplet is finished, we can get the [IPv4] and [IPv6] addresses.

We can also either log in via the command line from a local GNU/Linux or UNIX (e.g. MacOS) terminal or via a graphical SSH client (on Microsoft Windows, most people use Putty) via ssh root@[IPv4] or ssh root@[IPv6] (replacing those tokens with their actual IPv4 or IPv6 addresses). If we've set a key, we should get logged in without the need to enter any passwords. If not, we have to enter a password provided by DigitalOcean.

Configure your Domain to point at your Server

Once you have selected and registered your domain with a domain registrar - we are using Metaname - you can set up (usually through a web interface provided by the registrar)

an "A Record" which associates your website's name (your [Domain], e.g. milll.ws, or a subdomain of that domain, e.g. bbb.milll.ws, where 'bbb' is the subdomain part) to the IPv4 address of your server. You should just be able to enter your server's IPv4 address, the domain name (or sub-domain) you want to use for your server.
if your registrar offers it it's also important to define an IPv6 record, which is called an "AAAA Record"... you put in the same domain name or subdomain and then your IPv6 address instead of your IPv4 one.

I've attached an screenshot of the Metaname interface for configuring these DNS zone records.

You might be asked to set a "Time-to-live" (which has to do with the length of time Domain Name Servers are asked to "cache" the association that the A Record specifies) in which case you can put in 3600 seconds or an hour depending on the time units your interface requests... but in most cases that'll be set to a default of an hour automatically.

Once your domain A and AAAA records are configured, you should be able to log into your server via ssh root@[Domain], or, for example, ssh root@bbb.milll.ws. Although it should be instant, depending on your registrar, it might take as long as a few hours (even 24) for your domain name assignments to propogate through the DNS network and be available on your computer.

Best Practice: access your server as a non-root user

You should be able to test that your A and AAAA Records have been set correctly by logging into your server via SSH using your domain name rather than the IPv4 or IPv6 address you used previously. It should (after you accept the SSH warning that the server's name has a new name) work the same way your original SSH login did. On Linux, you'd SSH via a terminal and enter ssh root@[domain name]. I think you can do similar on MacOS and on Windows, I believe people typically use software called Putty...

But this will log you into your server as the 'root' user.

It's not considered good practice to access your server as root (it's too easy to completely screw it up). Best practice is to create a separate 'non-root' user who has 'sudo' privileges and the ability to log in via SSH. If you are currently logged in as 'root', you can create a normal user for yourself via (replace [username] with your chosen username):

U=[username]
adduser $U

You will be required to set a password for the user here. Then you can add the new user to several relevant groups that confer the required administrative capabilities.

adduser $U ssh
adduser $U admin
adduser $U sudo

If you want to change the password for user [username] you can run:

passwd $U

then become that user temporarily (note, the root user can 'become' another user without needing to enter a password) and create an SSH key and, in the process, the .ssh directory (directories starting with a '.' are normally 'hidden') for the file into which to put your public SSH key:

su $U
ssh-keygen -t rsa -b 2048
nano ~/.ssh/authorized_keys

and in that file, copy and paste (without spaces on either end) your current computer's public ssh key (never publish your private key anywhere!), save and close the file.

From that point, you should be able to SSH to your server via ssh [username]@[domain name] without needing to enter a password.

These instructions use 'sudo' in front of commands because I assume you're using a non-root user. The instructions will still work fine even if you're logged in as 'root'.

The rest of the tutorial can be run as your 'sudo-capable' non-root user.

A few post-install updates

Update the server's hosts file

This is required due to some quirks of the auto-detection of your domain name used by BigBlueButton - you'll need it later.

sudo $EDIT /etc/hosts

and add (or make sure it already has) the following:

127.0.1.1 [First part of domain]
127.0.0.1 localhost
[IPv4] [Domain]
[IPv6] [Domain]

For example - my test system has these details:

127.0.1.1 bbbtest
127.0.0.1 localhost
143.110.228.88 bbbtest.milll.ws
2604:a880:4:1d0::402:b000 bbbtest.milll.ws

Do an initial post-install update to the latest software versions:

sudo apt-get update && sudo apt-get dist-upgrade

and add a couple useful apps that, for example, track changes to our system configuration for future reference (etckeeper) and allow us to do network troubleshooting (net-tools):

sudo apt-get install -y etckeeper net-tools

We also want to enable console logins in the event we have trouble using SSH:

wget -qO- https://repos-droplet.digitalocean.com/install.sh | sudo bash

Firewall Configuration

We need to configure firewall for admin access via SSH and access to internet for Docker containers

sudo ufw allow OpenSSH

sudo ufw allow in on docker0

sudo ufw allow from 172.0.0.0/8 to any

Then we need to adjust the default firewall policy:

sudo $EDIT /etc/default/ufw

You'll find this:

# Set the default forward policy to ACCEPT, DROP or REJECT.  Please note that
# if you change this you will most likely want to adjust your rules
DEFAULT_FORWARD_POLICY="DROP"

which you need to change to

# Set the default forward policy to ACCEPT, DROP or REJECT.  Please note that
# if you change this you will most likely want to adjust your rules
DEFAULT_FORWARD_POLICY="ACCEPT"

Next you need to edit this file

sudo $EDIT /etc/ufw/sysctl.conf

And change (near the top of the file):

# Uncomment this to allow this host to route packets between interfaces
#net/ipv4/ip_forward=1
#net/ipv6/conf/default/forwarding=1
#net/ipv6/conf/all/forwarding=1

# Uncomment this to allow this host to route packets between interfaces
net/ipv4/ip_forward=1
net/ipv6/conf/default/forwarding=1
net/ipv6/conf/all/forwarding=1

(removing the "#" uncomments those lines)

Next, you have to restart the server's networking stack to apply the changes you've made:

sudo systemctl restart systemd-networkd

Luckily, this is generally instantaneous, so your connection to your server shouldn't be interrupted.

Then you either start or (if it's already running for some reason) restart the firewall

sudo ufw enable

sudo service ufw restart

(running both won't do any harm)

And we also update the firewall configuration to tell it to automatically start at boot time.

sudo $EDIT /etc/ufw/ufw.conf

Change ENABLED=no to ENABLED=yes.

Next we need to set up some specialised rules for the "COTURN" functionality of the BigBlueButton system. COTURN is a FOSS application that provides both TURN and STUN (video) (alternative non-video reference) functionality which are core to the WebRTC protocol on which modern video conferencing applications are built, and are necessary for your users to connect their audio and video to a session, particularly if they're behind an institutional firewall.

Note: in some cases, institutions will have implemented a rather over-the-top-paranoid 'default deny' for video conference hosts which will block access to your BBB instance unless you can get them to add your site's domain name to their institutional whitelist. Sadly, there's no easy way around this.

sudo ufw allow 7443/tcp

sudo ufw allow 16384:32768/udp

sudo ufw allow 3478/udp

sudo ufw allow 5349/tcp

sudo ufw allow from 10.7.7.0/24

Ok, that's it for the firewall shenanigans.

Install Postfix so the server can send email

It's generally a good idea to make sure any server you build can send email, and has a sensible default email address to send stuff to: stuff like administrative messages alerting you to failed tasks, or other system problems. We recommend that you designate an email address for whoever's responsible for this server. We've got a more comprehsensive howto for setting this up if you're wanting extra details.

We achieve the outgoing mail functionality using the industrial strength Postfix SMTP server (it's widely used by ISPs for large-scale email services) along with a command line SMTP client that allows us to test our solution from the command line:

sudo apt install postfix bsd-mailx

During this installation, you'll be asked by the installer to make some decisions to do preliminary configuration of the Postfix installation. Select the default asnwers except as follows:

Select "Internet Site with Smarthost",
fill in the [Domain] name you've chosen for your server,
the domain name or IP address and port (in the form [SMTP server]:[port], examples might be smtp.oeru.org:465, or 10.11.143.22:465) of your "smarthost" who'll be doing the authenticating SMTP for you - note: our configuration works with port 465, and
the email address to which you want to receive system-related messages, namely [Admin email].

Once that's installed, we need to set up our default email address for this server:

sudo $EDIT /etc/aliases

This file will containerd

# See man 5 aliases for format
postmaster:    root

update it to include an email address to send stuff intended for the system admin (aka 'root'):

# See man 5 aliases for format
postmaster:    root
 
root: [Admin email]

after writing that, we have to convert that file into a form understood by Postix:

sudo newaliases

Next, we need to create a new file with the SMTP 'relay host' aka 'smart host' details:

sudo $EDIT /etc/postfix/relay_password

In it you need to put the following:

[SMTP Server] [SMTP username]:[SMTP password]

Here's an example:

about.oerfoundation.org demosmtp@milll.ws:7TLM6qGoqZXHfkDmkh6

Once you've set that up, we have to again prepare that file for use by Postfix:

sudo postmap /etc/postfix/relay_password

Finally, we need to update Postfix's main configuration to tell it to use our authenticating SMTP details:

sudo $EDIT /etc/postfix/main.cf

You'll need to make main.cf look like this - specifically commenting out smtp_tls_security_level=may by adding a '#' at the start of the line, and then adding the details below # added to configure accessing the relay host via authenticating SMTP. You should also take this opportunity to confirm that your [Domain], [SMTP server] and [SMTP port] are set correctly.

smtpd_banner = $myhostname ESMTP $mail_name (Ubuntu)
biff = no
 
# appending .domain is the MUA's job.
append_dot_mydomain = no
 
# Uncomment the next line to generate "delayed mail" warnings
#delay_warning_time = 4h
 
readme_directory = no
 
# See http://www.postfix.org/COMPATIBILITY_README.html -- default to 2 on
# fresh installs.
compatibility_level = 2
 
# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
smtpd_tls_security_level=may
 
smtp_tls_CApath=/etc/ssl/certs
## Commented out for SmartHost configuration
#smtp_tls_security_level=may
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache
 
 
smtpd_relay_restrictions = permit_mynetworks permit_sasl_authenticated defer_unauth_destination
myhostname = [Domain]
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
myorigin = /etc/mailname
mydestination = $myhostname, bbbtest.milll.ws, localhost.milll.ws, localhost
relayhost = [SMTP server]:465
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128
mailbox_size_limit = 0
recipient_delimiter = +
inet_interfaces = all
inet_protocols = all
 
# added to configure accessing the relay host via authenticating SMTP
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/relay_password
smtp_sasl_security_options =
smtp_tls_security_level = encrypt
 
# add this if you're using Ubuntu 20.04, and comment out (with a "#") the
# earlier line smtp_tls_security_level = may to save errors in 'postfix check'
# and uncomment this line (by removing the #)
smtp_tls_wrappermode = yes

Here's an example of what the final code could look like (don't use these exact values as they won't work for you):

First, I commented this out:

#smtp_tls_security_level=may

Made sure this was my [Domain]

myhostname = bbbtest.milll.ws

Made sure this had my [SMTP server] and [SMTP port] details:

relayhost = about.oerfoundation.org:465

And I added this at the end:

# added to configure accessing the relay host via authenticating SMTP
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/relay_password
smtp_sasl_security_options =
smtp_tls_security_level = encrypt
 
# add this if you're using Ubuntu 20.04, and comment out (with a "#") the
# earlier line smtp_tls_security_level = may to save errors in 'postfix check'
# and uncomment this line (by removing the #)
smtp_tls_wrappermode = yes

After this, the Postfix configuration is done. We can check that we haven't got any typos via

sudo postfix check

If not, we can apply our configuration changes:

sudo postfix reload

and we can confirm it all worked correctly by checking the log file for Postfix:

sudo less +G /var/log/mail.log

Note: you might see a warning like this: postfix/postfix-script: warning: symlink leaves directory: /etc/postfix/./makedefs.out - it's spurious and you don't need to worry about it.

Email test

Next we can test our outgoing SMTP by sending a test message via the command line - use a test email that you can check!:

mail [Test email]

for example:

mail demo@oerfoundation.org

After you hit Enter, you'll be shown

Subject: {Enter an email subject, e.g. "Test email from [Domain]"}

After that, hit Enter, and you'll be shown a blank line. On that line:

{Enter your email text, e.g. "This is just a test."}

Then, to finish your email, type CTRL-D which will show you another line

CC: {Enter any CC email addresses, e.g. mybackupemail@anotherprovider.tld }

After you hit Enter, your email should be sent if all your configuration options are accepted by your remote host (the SMTP server at the address [SMTP server] with all the other details you entered).

You can check if it worked by looking at the Postfix log again:

sudo less +G /var/log/mail.log

If it sent the email, you'll see something like (but with different IP addresses, serial numbers, and addresses) - the key bit is the status=sent bit and the 250 code from the SMTP server:

08FBD2B501C: to=<demo@oerfoundation.org>, relay=dovecot[172.22.1.250]:24, delay=1.3, delays=1.3/0.02/0/0.04, dsn=2.0.0, status=sent (250 2.0.0 <demo@oerfoundation.org> MMokCa2TpWEffAAAPgmdMA Saved)

You can also check for receipt of email and verify receipt (note, if you don't get it quickily, check your email spam folder).

Install Nginx webserver and Let's Encrypt tools

sudo apt install -y nginx-full ca-certificates letsencrypt ssl-cert

You need to tell your firewall to open the ports that the Nginx webserver will use:

sudo ufw allow "Nginx Full"

And then we need to create a special configuration for Let's Encrypt and then an identify verification directory:

sudo mkdir /etc/nginx/includes

sudo mkdir /var/www/letsencrypt

To create the specific configuration, we create this file:

sudo $EDIT /etc/nginx/includes/letsencrypt.conf

And fill it with this information:

# Rule for legitimate ACME Challenge requests
location ^~ /.well-known/acme-challenge/ {
    default_type "text/plain";
    # this can be any directory, but this name keeps it clear
    root /var/www/letsencrypt;
}
 
# Hide /acme-challenge subdirectory and return 404 on all requests.
# It is somewhat more secure than letting Nginx return 403.
# Ending slash is important!
location = /.well-known/acme-challenge/ {
    return 404;
}

We'll reference this file in our Nginx configuration file for the reverse proxy functionality.

Set up COTURN certificates

In preparation for creating our Let's Encrypt SSL certificate for our [Domain], we're going to set up a 'hook' which is triggered when our SSL certificate is created, and it copies our current certificate to a place where the COTURN server can find it.

sudo $EDIT /etc/letsencrypt/renewal-hooks/deploy/coturn.sh

Copy and past the following into your file (replacing [Domain] with your domain name):

#!/bin/bash
 
DOMAIN=[Domain]
DEST=/etc/coturn-ssl
 
#if [[ 1 == 1 ]]; then
if [[ $RENEWED_DOMAINS == *"$DOMAIN"* ]]; then
  cp -L /etc/letsencrypt/live/${DOMAIN}/fullchain.pem $DEST
  cp -L /etc/letsencrypt/live/${DOMAIN}/privkey.pem $DEST
  echo "updated $DOMAIN certificates in $DEST"
fi

Next, make that script executable:

sudo chmod a+x /etc/letsencrypt/renewal-hooks/deploy/coturn.sh

so that it is run automatically anytime the relevant certificate is created or renewed.

After that, we have to create a place for the COTURN-specific certificates to go:

sudo mkdir /etc/coturn-ssl

Set up Nginx Reverse Proxy Configuration

Next we have to set up our Nginx webserver on our virtual server, which will be the Docker container host for our BigBlueButton system. The reverse proxy configuration will allow the virtual server to receive web requests from BBB users and pass them securely through to the right Docker container.

Create a suitable configuration file - at the OERF we use the convention of calling our configuration

sudo $EDIT /etc/nginx/sites-available/$SITE

In this file, you'll past in the following, replacing [Domain] as appropriate - now might be a good idea to try out search and replace in your text editor!

server {
  listen 80;
  # if your host doens't support IPv6, comment out the following line
  listen [::]:80;
  server_name [Domain];
 
  access_log  /var/log/nginx/[Domain].access.log;
  error_log /var/log/nginx/[Domain].error.log;
 
  include includes/letsencrypt.conf;
 
  # redirect all HTTP traffic to HTTPS.
  location / {
    return  302 https://$server_name$request_uri;
  }
}
 
server {
  listen 443 ssl http2 default_server;
  # if your host doens't support IPv6, comment out the following line
  listen [::]:443 ssl http2 default_server;
  server_name [Domain];
 
  # We comment these out *after* we have successfully geneated our Let's Encrypt certificate for [Domain].
  ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
  ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;   
  # we start with these commented out until after we can generate our Let's Encrypt certificate for [Domain]!
  #ssl_certificate /etc/letsencrypt/live/[Domain]/fullchain.pem;
  #ssl_certificate_key /etc/letsencrypt/live/[Domain]/privkey.pem;
  ssl_dhparam /etc/ssl/certs/dhparam.pem;
 
  access_log  /var/log/nginx/[Domain].access.log;
  error_log /var/log/nginx/[Domain].error.log;
 
  location / {
    proxy_http_version 1.1;
    # for BBB 2.4, the port used is 48087. For earlier versions of BBB, it's 8080
    proxy_pass http://127.0.0.1:48087;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    #proxy_set_header Connection $connection_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_cache_bypass $http_upgrade;
  }
}

Update 2021-12-30 With the release of BBB 2.4 a few weeks ago, the Docker configuration now has one 'breaking' change: the port has been changed to 48087! So, if you are installing an older version of BBB, the previous default was port 8080. If you get a 502 error after setting up your containers, check to make sure you haven't been bitten by this little detail!

Right - back to the process...

After creating it, we have to 'enable' the configuration:

sudo ln -sf /etc/nginx/sites-available/$SITE /etc/nginx/sites-enabled/

It's also not a bad idea to disable the Nginx default configuration, as it can sometimes interfere with things:

sudo rm /etc/nginx/sites-enabled/default

Extra security with dhparam.pem

We're going to create a 'dhparam' certificate for your configuration. These take a long time to generate - between 10-30 minutes, depending not on the speed of your computer, but on the rate at which it creates 'random events' that allow it to create a suitablely complex random prime number.

sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

If your time isn't limited, you can increase the size of your dhparam from 2048 to 4096 - it'll take quite a lot longer to create.

Ok - now that we've created our dhparam.pem, referenced in our Nginx configuration for [Domain], we should have everything in place. We can now test Nginx's configuration:

sudo nginx -t

If you don't get any errors or warnings, you can activate the new configuration:

sudo service nginx reload

You server should now successfully respond to your [Domain], but it'll redirect to HTTPS using the default (self-signed) certificates that are valid as far as Nginx is concerned, but your browser won't let you access the page due to those inappropriate certificates. You can test it by putting http://[Domain] into your browser and seeing if it redirects you to https://[Domain] and a 'bad certificate` (or similar) page.

To fix that, we can now generate a Let's Encrypt certificate which will be valid.

sudo letsencrypt certonly --webroot -w /var/www/letsencrypt -d ${SITE}

Since this is your first time running the letsencrypt script, you'll be asked for a contact email (so the Let's Encrypt system can warn you if your certificates are going to be expiring soon!) - use your [Admin email] for this. You can also opt in to allowing them to get anonymous statistics from your site.

Once you've done that, the Let's Encrypt system will verify that you (the person requesting the certificate) also controls the server that's requesting it (using the details specified in the /etc/nginx/includes/letsencrypt.conf file, along with data that the letsencrypt script writes into a special file in the /var/www/letsencrypt directory) and, all going well, you'll see a "Congratulations!" message telling you that you have new certificates for your [Domain].

Now is a good time to check if your renew-hook worked properly - there should now be two files in /etc/coturn-ssl, namely fullchain.pem and privkey.pem. If that's not the case, something might have gone wrong.

Then you can re-edit your Nginx confguration file:

sudo $EDIT /etc/nginx/sites-available/$SITE

and comment out the default certificates and uncomment the [Domain]-specific certificates, like this (we'll assume you've already got your [Domain] substituted!):

 
  ...
 
  # We comment these out *after* we have successfully geneated our Let's Encrypt certificate for [Domain].
  #ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
  #ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;   
  # we start with these commented out until after we can generate our Let's Encrypt certificate for [Domain]!
  ssl_certificate /etc/letsencrypt/live/[Domain]/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/[Domain]/privkey.pem;
  ssl_dhparam /etc/ssl/certs/dhparam.pem;
 
  ...

Once you've got that going, you again check to make sure your Nginx config is valid:

sudo nginx -t

and apply your configruation changes:

sudo service nginx reload

If you now go to http://[Domain] in your browser, you should be redirected to https://[Domain] and you shouldn't get any certificate errors, although you might get a "502" error because the service that reverse proxy configuration is trying to send you to doesn't yet exist! That's what we're expecting.

One more thing - we need to make sure that the coturn.sh renewal hook script has run. We can check to make sure that there are two files, fullchain.pem and privkey.pem in the /etc/coturn-ssl directory. If we start the Docker containers before these files exist, the Docker daemon creates them as directories by default which can lead to all sorts of trickiness. Run

sudo ls -l /etc/coturn-ssl/

and make sure you get a result like this:

-rw-r--r-- 1 root root 5588 Dec 13 08:42 fullchain.pem
-rw------- 1 root root 1704 Dec 13 08:42 privkey.pem

Install Docker

Now we have to set up the Docker container support by first registering a new package source...

sudo apt-get install -y apt-transport-https curl gnupg lsb-release

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

sudo echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

updating our list of available packages to include the Docker-related packages...

sudo apt-get update

and then install them:

sudo apt-get install -y docker-ce docker-ce-cli containerd.io

Which installs a bunch of dependencies as well.

To make sure that our non-root user can talk to the Docker server, we need to jump through a couple more hoops:

sudo addgroup docker

sudo adduser dave docker

After doing this, the easiest thing is to log out and log back in again to make sure my user can access the new permissions. To confirm that my user has docker group privileges, I can run

id

which should give a result like

uid=1000(dave) gid=1000(dave) groups=1000(dave),4(adm),27(sudo),1001(docker)

with the latter being the confirmation.

Install Docker-compose

Now we're almost to the BigBlueButton part - we just need to install the Docker Compose framework:

sudo apt install python3-pip

sudo pip install -U pip

sudo pip install -U docker-compose

Once you've done that, you should be able to run docker-compose at your command prompt and it should give you the docker-compose help page. If so, great work! Almost there.

Git-Clone BBB Docker repository

Now it's time to install the set of Docker containers that make up the BigBlueButton stack of coordinated services.

We make a place for the docker configuration and data to live:

sudo mkdir -p /home/docker/

go into it

cd /home/docker

and then we use the magic of 'git' (if you don't know it, this is one of the single most powerful tools programmers use - everyone would benefit from knowing how 'version control' works - git is by far the most widely used version control aka 'source code control' system in the world. It's open source.) to 'clone' the BigBlueButton developers' Docker definitions code:

sudo git clone -b main --recurse-submodules https://github.com/bigbluebutton/docker.git bbb-docker

That command puts all the code into a directory called bbb-docker so let's go there:

cd bbb-docker

and in there, we run this command to gram a second layer of code that is referenced by the first layer we already downloaded in the previous step:

sudo git submodule update --init

Finally, we run this handy script provided by the BBB developers to set up a working Docker Compose configuration:

sudo ./scripts/setup

This will script will ask you some questions about your system. These are the questions and the answers we'll use - note, where I've written [IPv4] and [IPv6] below, you should see the actual IPv4 and IPv6 addresses for your server:

Should greenlight be included? (y/n): y
Should an automatic HTTPS Proxy be included? (y/n): n
Should a coturn be included? (y/n): y
Coturn needs TLS to function properly.
   Since automatic HTTPS Proxy is disabled,
   you must provide a relative or absolute path
   to your certificates.
Please enter path to cert.pem: /etc/coturn-ssl/fullchain.pem
Please enter path to key.pem: /etc/coturn-ssl/privkey.pem
Should a Prometheus exporter be included? (y/n): y
Please enter the domain name: bbbtest.milll.ws
Should the recording feature be included?
   IMPORTANT: this is currently a big privacy issues, because it will 
   record everything which happens in the conference, even when the button
   suggests, that it does not.
   make sure that you always get people's consent, before they join a room!
   https://github.com/bigbluebutton/bigbluebutton/issues/9202
Choice (y/n): y
Is [IPv4] your external IPv4 address? (y/n): y
Is [IPv6] your external IPv6 address? (y/n): y

Once you finish answering these questions, the script creates a file called .env (the leading '.' means it's a 'hidden' file that won't show up in normal directory listings - you have to know it's there, as it holds important system values and shouldn't be deleted.

Configure your BBB

But now, we're going to tweak it, because it holds all the important customised values we need to configure our BigBlueButton service.

sudo $EDIT .env

When you're editing the file, scroll down through it and adjust the values you find as follows.

Uncomment this one

ALLOW_MAIL_NOTIFICATIONS=true

Set the following

SMTP_SERVER=[SMTP server]
SMTP_PORT=[SMTP port]
SMTP_DOMAIN=[Domain]
SMTP_USERNAME=[SMTP username]
SMTP_PASSWORD=[SMTP password]
SMTP_AUTH=plain
SMTP_STARTTLS_AUTO=true
#
SMTP_SENDER=[Outgoing email]

and finally set

DEFAULT_REGISTRATION=invite

This last one makes it possible for you to invite external people to make use of your BigBlueButton instance - they can create a log in and create their own rooms over which they'll have some control. These can be people in your organisation or community for whom you want your BBB to be available as a resource.

Fix minor configuration error that blocks JODConverter

One of the containers used in the BBB stack is called JODConverter which, in standard Free and Open Source Software tradition, makes use of an 'upstream' development by another developer, EugenMayer, which in turn makes use of an upstream development...

The issue is that a recent update (in early December 2021) has broken the process of launching this container. This is a big problem because the JODConverter provides the services of converting uploaded presentations and downloaded documents (like BBB's Public Chat or Shared Notes) in various useful file formats.

Turns out the fix is easy. While still in bbb-docker, Just run

sudo $EDIT mod/jodconverter/Dockerfile

and add the following line to the very bottom of the file:

CMD ["--spring.config.additional-location=optional:/etc/app/"]

Save it, and you're done. I have submitted an issue with the fix I've found to the bigbluebutton/docker project.

Once that configuration is done, it's finally time to...

Build your BBB

The first time it's run, this command will trigger the building of a set of no less than 22 separate Docker containers, each running its own crucial service as part of the BigBlueButton stack.

sudo docker-compose up -d

Note: this process can take a LONG time, like an hour or more depending on your server's internet connection speed.

If you want to see how long it takes the first time, run this instead:

sudo time docker-compose up -d

which will give you a readout of the time the command takes to complete.

Visit your new BBB

Once you next see the command prompt ($ or #), it means that your BBB system is starting up. You can see the status of the containers by running

sudo docker-compose ps

which should give you something that looks like this, once everything is running (it might take a few minutes!):

              Name                            Command                  State                Ports          
-----------------------------------------------------------------------------------------------------------
bbb-docker_apps-akka_1             /bin/sh -c dockerize     - ...   Up                                     
bbb-docker_bbb-web_1               /entrypoint.sh                   Up (healthy)                           
bbb-docker_coturn_1                docker-entrypoint.sh --ext ...   Up                                     
bbb-docker_etherpad_1              /entrypoint.sh                   Up             9001/tcp                
bbb-docker_freeswitch_1            /bin/sh -c /entrypoint.sh        Up                                     
bbb-docker_fsesl-akka_1            /bin/sh -c dockerize     - ...   Up                                     
bbb-docker_greenlight_1            bin/start                        Up             10.7.7.1:5000->80/tcp   
bbb-docker_html5-backend-1_1       /entrypoint.sh                   Up                                     
bbb-docker_html5-backend-2_1       /entrypoint.sh                   Up                                     
bbb-docker_html5-frontend-1_1      /entrypoint.sh                   Up                                     
bbb-docker_html5-frontend-2_1      /entrypoint.sh                   Up                                     
bbb-docker_jodconverter_1          /docker-entrypoint.sh --sp ...   Up                                     
bbb-docker_kurento_1               /entrypoint.sh                   Up (healthy)                           
bbb-docker_mongodb_1               docker-entrypoint.sh mongo ...   Up (healthy)   27017/tcp               
bbb-docker_nginx_1                 /docker-entrypoint.sh ngin ...   Up                                     
bbb-docker_periodic_1              /entrypoint.sh                   Up                                     
bbb-docker_postgres_1              docker-entrypoint.sh postgres    Up (healthy)   5432/tcp                
bbb-docker_prometheus-exporter_1   python server.py                 Up             9688/tcp                
bbb-docker_recordings_1            /bin/sh -c /entrypoint.sh        Up                                     
bbb-docker_redis_1                 docker-entrypoint.sh redis ...   Up (healthy)   6379/tcp                
bbb-docker_webhooks_1              /bin/sh -c /entrypoint.sh        Up                                     
bbb-docker_webrtc-sfu_1            ./docker-entrypoint.sh npm ...   Up             127.0.0.1:3008->3008/tcp

At that point, you can visit https://[Domain] and instead of a 502 error, you should see the BigBlueButton 'Greenlight' front page.

Now the final step...

Create an admin user:

To create an admin user, you run this:

sudo docker-compose exec greenlight bundle exec rake admin:create

It will give you a login email address and a randomly generated password. Use these to log in. In the profile (top right Admin menu dropdown), you can alter the admin user's email to a real email (perhaps [Admin email]?), and change the password if you like.

Then you can go back to the Admin menu and select "Organisation" which should put you on the Manage Users page. You then invite yourself to join as a user by sending yourself an email (which, if your SMTP settings are correct, will work). If you don't receive it in a minute or two, check your spam folder.

Either log out of Greenlight before clicking the link in the email or open the link (by copying and pasting it) in a different browser where you're not logged in to this Greenlight instance, and create a user account for yourself.

Then log back into Greenlight as the Admin user (if you've previously logged out) and refresh the "Manage Users" page. You should find your newly created user. Select 'Edit' from the vertical 3 dotted menu. On the "Update your Account Info" page, set the User Role for your user to 'Admin" and click the "Update" button. You should now be able to log out as Admin, and back in as your own user, but with administrative privileges.

Run your first conference

Now it's time to try running a video conference. Click on the "Home" link (top right menu) and you should see that you have a default room called "Home Room" with a URL specified in the form [Domain]/b/[first 3 letters of your name]-[3 random hex digits]-[3 more random hex digits]. For me, it might look something like this: https://[Domain]/b/dav-a5b-73z

Click "Start" to initiate a conference in that Home Room.

In the conference room, you should select 'Microphone' so you can test speaking and listening, and also test your video camera (assming you have access to both on the computing device you're using to access BBB - note, a modern cellphone normally offers all of these.

We always encourage people participating in video conferences (regardless of the technology) to employ headphones to separate the audio from the conference form their input. It greatly improves the audio quality for all involved!.

If you select 'Microphone', there will be a brief delay whil your browser negotiates with the COTURN server in your BBB stack to link your data and audio channels. Once it's done that, it will give you an "echo test" window (see included screen shots). You should speak into your microphone when you see that screen and check whether you can hear yourself. This will confirm that your audio settings are right (or not) and will help the BBB system adjust its echo cancellation algorithms.

You can then also clidk the 'camera' icon (bottom middle of the page) to activate your webcam if you have one (or choose one if you have multiple cameras) as well as the video quality.

You can also try to 'Start recording' if you want to test your ability to record a session. Note that there is a delay after the end of a session in which you've recorded before the recording is displayed on the 'room' page in Greenlight. It might take minutes or even hourse to generate depending on the power of your server and the length of the session.

To see other administrative functionality including moderation and breakout rooms, click on the "gear" icon next to the "Users" heading in the left hand column. You can also experiment with the "Public Chat" and the "Shared Notes". Both can be saved at any time (via the top right 3 dot menu in that section) and will be included in any recordings you make.

Note the contents of Public Chat and Shared Notes will be wiped at the end of a session unless you explicitly save them or record the session (at least briefly at the end).

You can provide that "room address" to anyone and they can join your room (via an modern browser) when you have a session running. Alternatively, you can click on the 3 dotted menu associated with your room below the 'Search for room" form, and change the default properties of your room, including configuring it to let anyone who knows the room's address start a session. You can also create additional rooms (as an Admin user, you can set the limits on many of these properties via Organisation in the top right menu under your user name.

Have fun with your new, world class, cost-effective, large-scale BigBlueButton video conferencing application!

Next Steps

In a future tutorial, we'll provide information on how to troubleshoot BBB issues, how to upgrade it as new versions are made available by developers, and how to ensure that your recordings, user database, and configuration are backed up incrementally, encrypted, in remote storage.

Blog comments

It says in the nginx-config…

LPup (not verified) Tue 04/01/2022 - 20:32

It says in the nginx-config to change the port for the proxy and not forget to change it in the .env file. Where do I need to put what into the .env file for using a different port than 8080?

Hmm - thanks for pointing…

dave Tue 04/01/2022 - 20:44

Hmm - thanks for pointing that out. Yes, I think I made an error with that instruction (I've updated the Nginx config). If you implement BBB today via this set of instructions, you'll be installing BBB 2.4 - port 8080 was used in 2.3 and earlier versions. For 2.4, use port 48087. To be honest, I'm not sure of the right way to alter it if you have to due to other services running on the same system. Writing it manually in the docker-compose.yml file will be overwritten the next time you do an update... It might be necessary to change the port specified in the relevant container's Dockerfile under mods...

Add new comment

OERF FOSS Tech Hosting Conventions

dave — Sun, 29 Aug 2021 23:44:43 +0000

OERF FOSS Tech Hosting Conventions

Blog tags

overview

docker

docker-compose

mariadb

nginx

ubuntu linux

ssh

restic

let's encrypt

git

gitlab

foss

dave Mon 30/08/2021 - 11:44

At the OER Foundation we host an array of Free and Open Source Software (FOSS) services. To keep things manageable, we have established a set of conventions to which we adhere, and I'm describing them here in case it's helpful to others who can either learn from, or improve on, our experience.

To begin with, we use Ubuntu Linux for all of our hosts. We deploy the current Long Term Support (LTS) version of Ubuntu (at the time of this writing, it's 20.04) on commodity Linux hosting services, like Digital Ocean and Hetzner.

Host access

We access all our hosts on the command line, via secure, end-to-end encrypted connections, using OpenSSH. We don't use a server management tool (neither an open source one, like ISPConfig or Webmin, nor proprietary ones like Plex or CPanel). They would just slow us down. We prefer the efficiency and power afforded us by SSH. At any given time, I'm logged into a half a dozen remote systems, issuing updates, deploying code, diagnosing issues, checking resource usage, shoring up disk space, or tweaking Docker configurations.

Software on the host

On the host, we run the following:

We run etckeeper on each server to track changes in configuration. In general, we have these changes pushed to a central server to provide a reference in the event of a disaster (e.g. the server is compromised and needs to be 'nuked from orbit'...).
The Nginx web server - it's our reverse proxy of choice. All of our Let's Encrypt certificates terminate at the host server, greatly simplifying the deployment of the individual services running on it.
The Postfix SMTP server - it's our outgoing mailserver of choice, and we set it up as a smarthost, so that the server can send status and administrative messages to us via our MailCow email infrastructure using authenticating secure SMTP.
The Docker containerisation framework using the Docker Compose system to coordinate collections of containers that work together to provide specific services. Docker allows us to run a bunch of effectively independent Linux systems, each with potentially different sets of complex software dependencies, efficiently and reliably on a single host.
For each service, with an individual domain or subdomain name, we get a Let's Encrypt SSL certificate using the letsencrypt scripting toolchain. It is free of cost, and easy to build into our workflow, so it's a 'no-brainer' as far as we're concerned, ensuring all of our sites protect the data of their users with full encrypted links!
For applications we deploy that depend on the MySQL database, we run a single instance of the fully MySQL-compatible MariaDB on our host, and the Docker containers connect to it via the internal network. We do it this way to easy the process of backing up the various MariaDB databases, which would be much more fiddly if we were running a bunch of individual MariaDB or MySQL instances in Docker containers. We use MariaDB because we prefer its development model, design decisions, and the fact that it's not being run by the Oracle Corporation, which owns the MySQL project.
We use Restic to perform remote encrypted incremental file backups for the filesystems on each server. We send them to a development server we have which has oodles of disk space (BTRFS RAID1 if you're curious) for safekeeping.

When each new Ubuntu LTS release comes out, we tend to create an install image for our commodity hosting provider (most recently, Digital Ocean), which has all these things pre-installed.

Docker deployments

For the various services we deploy using Docker - more specifically, using the very handy Docker Compose scripting toolchain, we have a bunch of conventional practices.

We put all our Docker Composer recipes in a common directory: /home/docker - each service goes in a directory using the domain name of that service. For example, this Tech blog, tech.oeru.org is in the directory /home/docker/tech.oeru.org on our server about.oerfoundation.org. Each service directory has a docker-compose.yml file which defines the collection of Docker containers making up each service. It also specifies the local directors in which data we want to make persistent, even surviving the removal of relevant Docker containers. In the case of this site, the containers include an Nginx webserver container which submits requests delivered to it by our hosts's Nginx reverse proxy to a PHP scripting engine container which, in turn, consults the Drupal 8 source code making up the site, and the MariaDB on the host which stores the data. There is also a PHP container which automatically runs the behind-the-scenes automated 'cron' tasks that every Drupal site requires.
We store that per-service persistent data in a similarly named directory under /home/data, so this site's data is stored in /home/data/tech.oeru.org. That data includes, in the case of this site, an Nginx directory, with a generic Drupal website configuration, and a directory to contain all the Drupal 8 core source code and that for theme, module, and library dependencies. In a few cases, where we're using tools with specialised Docker deployment practices, like Mailcow, BigBlueButton, and Discourse, the persistent data for the site is stored under the /home/docker directory to avoid unnecessarily complicating our use of those tools. So our conventions are just that - not hard and fast, if there's a good reason to compromise them.

Keeping track

For all of our service configurations, and, in particular our Docker deployments, we use Git to provide source code versioning and management. We also use it to deploy code that we have developed ourselves. Where possible, we use (and contribute back to!) upstream git repositories supplied by the communities surrounding many of the FOSS services we offer. We see that as doing our part to be good, contributing FOSS community members.

All of our git repositories are held on our own, self-hosted Gitlab instance: https://git.oeru.org - anyone is welcome to peruse the repositories, and we invite anyone interested in contributing to request a an account (give us an idea of what you're interested in doing and how you'd like to participate!).

Add new comment

Building a Course Site with WordPress on Ubuntu 20.04 using Docker Compose

dave — Tue, 24 Aug 2021 04:00:22 +0000

Building a Course Site with WordPress on Ubuntu 20.04 using Docker Compose

Blog tags

wordpress

docker

docker-compose

ubuntu linux

20.04

multisite

redis

nginx

php

let's encrypt

dave Tue 24/08/2021 - 16:00

The OERu offers accredited tertiary (University level) courses to learners anywhere on the Internet, whether they are using desktop computers or mobile devices.

Instead of using a Learning Management System to frame the courses, the OERu Courses are hosted in a WordPress MultiSite (originally called a "Network" of sites within a single WordPress installation) implementation, with each course a 'subsite' represented by sub-directory below the main site. For example, the first Learning in a Digital Age micro-course, "Digital literacies for online learning" with the course code LiDA 101, can be found at https://course.oeru.org/lida101. This post explains how you can replicate our fully Free and Open Source Software large-scale Open Educational Resource (OER) course delivery platform at negligible cost.

Step one - a suitable host
Step two - prepare the host
- Set up Docker and Docker-Compose
Step three - configure your domain
- Set up Nginx reverse proxy
- Set up Let's Encrypt for the domain
Step four - get the code
Step five - set up Docker Compose for the site
- Create the NGINX container's configuration
- Launch containers
Step Six - set up your site
Step Seven - celebrate!
Snapshotting your first OER course!
Enabling OERu's Register Enrol functionality
Data Backups
Staying up-to-date
Acknowledgements

To host our WordPress Multisite, we use a quartet of Docker containers - a Redis caching server, an Nginx webserver, and two servers running the PHP script interpreter in FPM mode, with the first being the main workhorse responding to queries sent to it by the Nginx server... The other PHP container is responsible for running cron (scheduled) tasks in the background. It's all driven by Docker Compose (which coordinates the individual Docker containers) on an Ubuntu Linux host. The host also runs an Nginx instance to act as a 'reverse proxy', and the endpoint of our SSL (we use Let's Encrypt certificates). This is all consistent with our FOSS Docker-based hosting conventions.

Although our process to get one of the these sites up and running is made up of simple steps, there are a bunch of them, so get comfortable and buckle yourself in and prepare for a fun ride! Just beware - this is a pretty audacious tutorial describing an advanced production-ready system with lots of moving parts doing a serious amount of stuff behind the scenes, so this process is likely to take a few hours from start to finish and isn't for the faint of heart.

Step one - a suitable host

The first step is to get yourself an entry-level virtual server or compute instance somewhere.

I generally use DigitalOcean (I have no affiliation with the company), but there are many other commodity hosting services (check out Vultr or Linode, for example) around the world which offer comparably (or better) spec'd servers for USD5.00/month, or USD60.00/year. For that you get a Gigabyte (GB) of RAM, a processor, and 40GB of SSD (Static Storage Device = faster) storage.

A server (a "Droplet" in Digital Ocean parlance) with a GB of RAM and 20+ GB of disk space will be sufficient for this sort of service. If you expect it to have heavy traffic, or you might want to add more services, you might want to invest in a higher-spec server up-front (because, among other things, it'll offer you more disk space). Most of our servers are USD40/month instances (USD480/year) which buys 8GB of RAM, 4 virtual processors, and 160GB of disk space.

I suggest you create an account for yourself on your chosen hosting provider (and I encourage you to use Two Factor Authentication, aka 2FA, on your hosting account so that no one can log in as you and, say, delete your server unexpectedly - you'll find instructions on how to set up 2FA on your hosting provider's site) and create an Ubuntu 20.04 (or the most recent 'Long Term Support' (LTS) version - the next will be 22.04, in April 2022) in the zone nearest to you.

If you don't already have an SSH key on your computer, I encourage you to create one and specify the public key in the process of creating your server - that should allow you to log in without needing a password!

You'll need to note the server's IPv4 address (it'll be a series of 4 numbers, 0-254, separated by full stops, e.g. 103.99.72.244), and you should also be aware that your server will have a newer IPv6 address, which will be a set of 8 four hex character values [each hex character can have one of 16 values: 0-9,A-F] separated by colons, e.g. 2604:A880:0002:00D0:0000:0000:20DE:9001. With one or the other of those IPs, you can log into it via SSH.

Once you get logged in, it's worth doing an upgrade of your server's Ubuntu system! Do that as follows:

sudo apt-get update && sudo apt-get dist-upgrade

Get your Domain lined up

If you want to use your domain for other things besides your WordPress instance, I'd encourage you to use a subdomain, like (my usual choice) is "course.domainname", namely the subdomain "course" of "domainname".

Once you have selected and registered your domain, you can set up (usually through a web interface provided by the registrar) an "A Record" which associates your website's name to the IPv4 address of your server. So you should just be able to enter your server's IPv4 address, the domain name (or sub-domain) you want to use for your WordPress service. Nowadays, if your Domain Name host offers it (some don't, meaning they're way behind the times), it's also important to define an IPv6 record, which is called an "AAAA Record"... you put in your IPv6 address instead of your IPv4 one.

You might be asked to set a "Time-to-live" (which has to do with the length of time Domain Name Servers are asked to "cache" the association that the A Record specifies) in which case you can put in 3600 seconds or an hour depending on the time units your interface requests... but in most cases that'll be set to a default of an hour automatically.

Log into your server

This will log you into your server as the 'root' user. It's not considered good practice to access your server as root (it's too easy to completely screw it up). Best practice is to create a separate 'non-root' user who has 'sudo' privileges and the ability to log in via SSH. If you are currently logged in as 'root', you can create a normal user for yourself via (replace [username] with your chosen username):

U=[username]
adduser $U
adduser $U ssh
adduser $U sudoers

You'll also want to a set a password for user [username]:

passwd $U

then become that user temporarily (note, the root user can 'become' another user without needing to enter a password) and create an SSH key and, in the process, the .ssh directory (directories starting with a '.' are normally 'hidden') for the file into which to put your public SSH key:

su $U ssh-keygen -t rsa -b 2048 nano ~/.ssh/authorized_keys

and in that file, copy and paste (without spaces on either end) your current computer's public ssh key (never publish your private key anywhere!), save and close the file.

From that point, you should be able to SSH to your server via ssh [username]@[domain name] without needing to enter a password.

These instructions use 'sudo' in front of commands because I assume you're using a non-root user. The instructions will still work fine even if you're logged in as 'root'.

Sort out your details

You'll replace the similarly [named] variables in the configuration files and command lines below. These are the values you need to find or create.

[domain name] - the fully qualified domain name or subdomain by which you want your WPMS to be accessed. You must have full domain management ability on this domain. Example: course.oeru.org
[port] - this is an unused port, i.e. not used by any other service, that will be used by the Nginx reverse proxy to talk to your Docker Nginx webserver container. A conventional option would be 8080... If that's already in use, try 8081, etc. You can check what ports are in use with the command sudo netstat -punta - the ports are listed after the ':' in each case
MariaDB/MySQL database details
- [database root password] - the administrative user (root) password for this server - see our tutorial on creating strong random passwords
- [your database password] - if you, optionally, want to set up an admin user for yourself on this server. Paired with [your username] on the server.
- [database name] - the name of the database for this specific WordPress site - example wordpress
- [database user] - a separate username for this WordPress database - example wordpress (but it can be different too)- note: you'll be creating two database users with this same username and password, but that's intended.
- [database password] a separate password for this WordPress database user
Authenticating SMTP details - this is required so your WordPress site can send emails to users - crucial things like email address validation and password recovery emails...
- [smtp host] - the domain name or IPv4 or IPv6 address of an SMTP server
- [smtp reply-to-email address] - a monitored email to which people can send email related to this WordPress site, e.g. webmaster@[domain name]
- [smtp user] - the username (often an email address) used to authenticate against your SMTP server, provided by your email provider.
- [smtp password] - the accompanying password, provided by your email provider.
Wordpress configuration values
- [redis password] - another random password, this time for the caching service we'll set up to make your WordPress site faster than billy-o.
- [wordpress keys and salts] - a series of random numbers to make your WordPress site far more secure than it would otherwise be - these can be generated automatically using the approach described below!.
For those incorporating our WEnotes system, you'll need the following (these values are optional and can be ignored!)
- [couchdb host] - the domain name of the couchdb host - in the case of the OERu, our host is couch.oerfoundation.org. Yours might be different.
- [couchdb mention database] - the name of the designated 'mention' database on the couchdb host.
- [couchdb user] - a couchdb username, provided by whoever manages your couchdb host
- [couchdb password] - a couchdb password, also provided by whoever manages your couchdb host
Docker.com login details (you'll need a username and password).

Note: not all values in all files surrounded by [] need to be replaced! If they're not included in the list above, leave them as you find them!

Step two - prepare the host

Preparing the host involves ensuring your firewall, UFW, is configured properly, installing the Nginx webserver to act as your host's reverse proxy, and installing MariaDB (MySQL compatible but better, for a variety of reasons including that it's not controlled by Oracle) and configuring it properly. Then we can create the MariaDB database specifically for this WordPress installation. We also suggest you install Postfix so your server can send out email to you, and finally, we'll ensure that your server knows how to launch Docker containers and manage them with Docker Compose.

Before we do anything else, let's make sure your Ubuntu package repository is up-to-date.

sudo apt-get update

If you pause this build process for more than a few hours, it pays to run it again before you continue on.

Firewall with UFW

No computer system is ever full secure - there're always exploits waiting to be found, so security is a process of maintaining vigilance. Part of that is reducing exposure - minimising your "attack surface". Use a firewall - ufw is installed on Ubuntu by default and is easy to set up and maintain. Make sure you've got exceptions for SSH (without them, you could lock yourself out of your machine! Doh!).

Run the following commands to allow your Docker containers to talk to other services on your host.

sudo ufw allow in on docker0
sudo ufw allow from 172.0.0.0/8 to any

Specifically for Docker's benefit, you need to tweak the default Forwarding rule (I use vim as my editor. An alternative, also installed by default on Ubuntu, nano, is probably easier to use for simple edits like this, so I'll use nano here):

sudo nano /etc/default/ufw

and copy the line DEFAULT_FORWARD_POLICY="DROP" tweak it to look like this (commenting out the default, but leaving it there for future reference!):

#DEFAULT_FORWARD_POLICY="DROP"
DEFAULT_FORWARD_POLICY="ACCEPT"

and then save and exit the file (CTRL-X and then 'Y').

You also have to edit /etc/ufw/sysctl.conf and remove the "#" at the start of the following lines, so they look like this:

sudo nano /etc/ufw/sysctl.conf

# Uncomment this to allow this host to route packets between interfaces
net/ipv4/ip_forward=1
net/ipv6/conf/default/forwarding=1
net/ipv6/conf/all/forwarding=1

and finally restart the network stack and ufw on your server

sudo systemctl restart systemd-networkd
sudo service ufw restart

Installing the Nginx webserver/reverse proxy

In the configuration I'm describing here, you'll need a webserver running on the server - it'll be acting as a reverse proxy for the Docker-based Nginx instance described below. I prefer the efficiency of Nginx and clarity of Nginx configurations over those of Apache and other open source web servers. Here's how you install it.

sudo apt-get install nginx-full

To allow nginx to be visible via ports 80 and 443, run

sudo ufw allow "Nginx Full"

To check that all worked, you can put http://[domain name] into your browser's address bar, and you should see a default "NGINX" page...

Note: make sure your hosting service is not blocking these ports at some outer layer (depending on who's providing that hosting service you may have to set up port forwarding).

Installing MariaDB

sudo apt-get install mariadb-server mariadb-client

You need to set a root (admin) user password - you might want to create a /root/.my.cnf file containing the following (replacing [mysql root password]) to let you access MariaDB without a password from the commandline:

sudo nano /root/.my.cnf

and put the following info into it

[client]
user=root
password=[database root password]

You should now be able to type mysql at the command prompt (note, the name mysql is used for backward compatibility with many implementations where MariaDB is being used to replace MySQL).

Optional MySQL non-root user

If you're happy to use your root user to access MySQL, e.g. sudo mysql (which uses 'sudo' to access it via the root user), then you can safely ignore the rest of this section.

If you're accessing the server via a non-root user (which is a good idea, and is the reason we use sudo in this howto), you might want to create a similar ~/.my.cnf file in your directory , with your username in place of root, and a different password. That will allow you to work with the MariaDB client without needing to enter the root credentials each time.

To make it work, you'll need to run the following as the MySQL admin user - this should be the default on this new install - remember to replace your [tokens]!). This creates two users with the same credentials that will allow you to log in either from the same server (i.e. 'localhost') or from any of your Docker containers (often useful for debugging!), namely the wildcard '%'. Remember: if you change the user's details, you'll have to do it for both the localhost and '%' users.

CREATE USER "[your username]"@"localhost" IDENTIFIED BY "[your database password]";
CREATE USER "[your username]"@"%" IDENTIFIED BY "[your database password]";
GRANT ALL ON *.* to "[your username]"@"localhost" WITH GRANT OPTION;
GRANT ALL ON *.* to "[your username]"@"%" WITH GRANT OPTION;
FLUSH PRIVILEGES;

Don't be alarmed if MySQL tells you "0 rows affected" when you create a user - unless you see a specific 'error', it's still creating them.

End optional MySQL non-root user section

Tweak the configuration so that it's listening on the right internal network device.

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

and copy the bind-address line and adjust so it looks like this - we want MariaDB to be listening on all interfaces, not just localhost (127.0.0.1)...

# Instead of skip-networking the default is now to listen only on
# localhost which is more compatible and is not less secure.
#bind-address           = 127.0.0.1
bind-address            = 0.0.0.0

Then restart MariaDB:

sudo service mysql restart

It should now be listening on MySQL/MariaDB's default port 3306 on all interfaces, i.e. 0.0.0.0. For safety's sake, external access to the MariaDB server is blocked by your UFW firewall.

Now set up the database which will hold WordPress' data. Log into the MariaDB client on the host (if you've created a .my.cnf file in your home directory as describe above, you won't need to enter your username and password):

mysql -u root -p

Enter your root password when prompted and then replace the following [database-related tokens] to create the database with the right language encoding, along with access to the right separate user:

CREATE DATABASE [database name] CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER "[database user]"@"%" IDENTIFIED BY "[database password]";
GRANT ALL ON [database name].* to "[database user]"@"%";
FLUSH PRIVILEGES;

The last line ensures that MariaDB has updated its internal permissions to recognise your new user. To exit the SQL client, just type \q and ENTER.

Sending emails

Because a server like this one is set up to perform lots of rather complex jobs to perform, it's vital that your server has the ability to send you emails to alert you of problems, like failed updates or backups. We encourage you to follow our instructions on how to configure your server to use the Postfix SMTP server to send out email, using your Authenticating SMTP details.

Regular automatic database backups

Finally, it's a good idea (but optional - if you're in a hurry, you can do this later) to make sure that your server is maintaining backups of your database - in this case, we'll use the automysqlbackup script to automatically maintain a set of dated daily database backups. It's easy to install, and the database backups will be in /var/lib/automysqlbackup in dated folders and files. If you haven't set up Postfix in the previous step, just beware you will be asked to set it up when installing automysqlbackup.

sudo apt-get install automysqlbackup

That's all there is to it. It should run automatically every night and store a set of historical SQL snapshots that may well save your bacon sometime down the track!

Set up Docker and Docker-Compose

First, you need to set up Docker support on your server - use the 'repository method' for Ubuntu 20.04 and choose the 'x86_64 / amd64' tab!

Also, if you're using a non-root user, follow the complete instructions including setting up Docker for your non-root user.

The way I implement this set of containers is to use Docker Compose) which depends on the Python script interpreter (version 3+). I suggest using the latest installation instructions provided by the Docker community. Of the options provided, I use the 'alternative instructions', employing the 'pip' approach. This is what I usually do (to summarise the pip instructions):

The firrst step is to Install Ubuntu's Python3 pip which is a bit outdated...

sudo apt install python3-pip

use the Ubuntu instance, called pip3 to install the latest Python 3 pip

sudo pip install -U pip

and (finally) install the docker-compose script:

sudo pip install -U docker-compose

Set up our conventional directories

To set up your server, I recommend setting up a place for your Docker containers as per our Docker-related conventions:

sudo mkdir -p /home/data/[domain name]
sudo mkdir -p /home/docker/[domain name]

Step three - configure your domain

Set up Nginx reverse proxy

A reverse proxy is a website intermediary. It accepts requests from the Internet, like a normal webserver would, but instead of having direct access to the data being requested, it, in turn, makes a request from another webserver either on the same host, or on a different one, and passes the results of that request back to the requester. In this case, the Nginx instance on the host is making a request of a different host that happens to reside on the same host instance as a Docker 'container'.

Our convention is to create an Nginx reverse proxy configuration file with the same name as our [domain name], so in the case of, say, our Course WordPress Multisite, the file would be /etc/nginx/sites-available/course.oeru.org. Create a file in your /etc/nginx/sites-available with the following (again, replacing the [values] with your own values.

sudo nano /etc/nginx/sites-available/[domain name]

and copy and paste this in (and remember to replace the [tokens] with your relevant variables!):

#
# Set [domain name] and [port] below to make this work
#
# HTTP does *soft* redirect to HTTPS
#
server {
    # add [IP-Address:]80 in the next line if you want to limit this to a single interface
    listen 80;
    listen [::]:80;
    server_name [domain name];
    root /home/data/[domain name]/scr;
    index index.php;
 
    # change the file name of these logs to include your server name
    # if hosting many services...
    access_log /var/log/nginx/[domain name]_access.log;
    error_log /var/log/nginx/[domain name]_error.log;
 
    # for let's encrypt renewals!
    include includes/letsencrypt.conf;
 
    # redirect all HTTP traffic to HTTPS.
    location / {
        return  302 https://[domain name]$request_uri;
    }
}
#
# HTTPS
#
# This assumes you're using Let's Encrypt for your SSL certs (and why wouldn't
# you!?)... https://letsencrypt.org
server {
    # add [IP-Address:]443 ssl in the next line if you want to limit this to a single interface
    listen 443 ssl;
    listen [::]:443 ssl;
    # Note: these are *temporary* certificates, created when your host was set up
    # they are only in use to get Nginx to start up properly and let you create your let's encrypt certificates!
    ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
    ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
    # these will be used after we finish the Let's Encrypt process
    #ssl_certificate /etc/letsencrypt/live/[domain name]/fullchain.pem;
    #ssl_certificate_key /etc/letsencrypt/live/[domain name]/privkey.pem;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    # to create this, see https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html
    ssl_dhparam /etc/ssl/certs/dhparam.pem;
    keepalive_timeout 20s;
 
    server_name [domain name];
    root /home/data/[domain name]/src;
    index index.php;
 
    # change the file name of these logs to include your server name
    # if hosting many services...
    access_log /var/log/nginx/[domain name]_access.log;
    error_log /var/log/nginx/[domain name]_error.log;
 
    location / {
        # a good value for [port] is 8080, unless it's already in use by another service on your server...
        proxy_pass http://127.0.0.1:[port];
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $server_name;
        proxy_set_header X-Forwarded-Proto https;
        proxy_connect_timeout 900;
        proxy_send_timeout 900;
        proxy_read_timeout 900;
        send_timeout 900;
    }
    #
    # These "harden" your security
    add_header 'Access-Control-Allow-Origin' "*";
    # from https://gist.github.com/Stanback/7145487
    add_header 'Access-Control-Allow-Credentials' 'true' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
    add_header 'Access-Control-Allow-Headers' 'Accept,Authorization,Cache-Control,Content-Type,DNT,If-Modified-Since,Keep-Alive,Origin,User-Agent,X-Requested-With' always;
    #
    # for H5P embedding
    #add_header 'X-Frame-Options' 'ALLOW-FROM https://h5p.oeru.org';
    # required to be able to read Authorization header in frontend
    add_header 'Access-Control-Expose-Headers' 'Authorization' always;
    # tested at https://csp-evaluator.withgoogle.com/
    # works, but only B+ on MozOBs https://observatory.mozilla.org/analyze.html
    add_header X-XSS-Protection "1; mode=block";
}

Having created that file, we now have to create the ssl_dhparam file we referenced, staring by installing OpenSSL tools:

sudo apt-get install openssl

by running (warning - this can take quite a long time - like 5-15 minutes in my experience, depending on a lot of factors - the system needs to generate sufficient entropy to achieve acceptable randomness):

sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 4096

if you're short on time, you can create a key half the size far more quickly (a few seconds, typically):

sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

When that's done, you should see there's a file here: ls -l /etc/ssl/certs/dhparam.pem

Set up Let's Encrypt for the domain

We've already written a guide to setting up and securing your domain with Let's Encrypt but here're the relevant details:

sudo mkdir /etc/nginx/includes

and edit the following file

sudo nano /etc/nginx/includes/letsencrypt.conf

to make sure it has the following content:

# Rule for legitimate ACME Challenge requests
location ^~ /.well-known/acme-challenge/ {
    default_type "text/plain";
    # this can be any directory, but this name keeps it clear
    root /var/www/letsencrypt;
}
 
# Hide /acme-challenge subdirectory and return 404 on all requests.
# It is somewhat more secure than letting Nginx return 403.
# Ending slash is important!
location = /.well-known/acme-challenge/ {
    return 404;
}

Next, make sure your designated Let's Encrypt directory exists (note - you only need to do this once on a given host):

sudo mkdir /var/www/letsencrypt

Now, we'll make sure Nginx is aware of your configuration, which you do like this (substituting [domain name] with your domain!):

sudo ln -sf /etc/nginx/sites-available/[domain name] /etc/nginx/sites-enabled

then make sure Nginx is happy with your configuration syntax:

sudo nginx -t

and fix any typos which might've crept in. If it says your configurations are okay, then make your configuration live:

sudo service nginx reload

Once this is done, you can check to see if things are working properly by entering http://[domain name] in your browser's address bar. It should redirect you to http**s**://[domain name] and give you an error that there's a 'mismatch' in your certificates... which there is: my configuration approach means the server and your reverse proxy configuration are temporarily using the default "SnakeOil" SSL certificate pair (required to get Nginx to start in SSL mode), but your Nginx configuration is working to the extent required for us to request our Let's Encrypt certificate!

And here's how we actually generate your SSL certificat via Let's Encrypt (replacing [domain name] as appropriate):

sudo letsencrypt certonly --webroot -w /var/www/letsencrypt -d [domain name]

If it works, it gratifyingly results in a message that starts with "Congratulations"! Well done if you got that! Note, if you get an error, make sure your domain is properly configured to point to your server! Also, there could be a delay in that configuration change taking effect due to the vagueries of the DNS system. If it worked, you should have a set of certificates in the directories, currently commented out with leading "#"s, in the Nginx configuration file above. You'll now need to re-edit it

sudo nano /etc/nginx/sites-available/[domain name]

to change it so the relevant part looks like this (again, ensuring your [domain name] is in place in the relevant locations!):

    # Note: these are *temporary* certificates, created when your host was set up
    # they are only in use to get Nginx to start up properly and let you create your let's encrypt certificates!
    #ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem;
    #ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;
    # these will be used after we finish the Let's Encrypt process
    ssl_certificate /etc/letsencrypt/live/[domain name]/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/[domain name]/privkey.pem;

and then we need to do our obligatory configuration test:

sudo nginx -t

and if Nginx is happy, reload the configuration to put it into effect:

sudo service nginx reload

Now, if you point your browser at http://[domain name], it should automatically redirect to https://[domain name] without any errors, except that it won't yet have any content to show you, so you might get a 404 error, which is expected!

Step four - get the code

Next we have to get all the relevant code for the WordPress site and its dependencies.

WordPress source code

The latest source code for WordPress is always available from https://wordpress.org/latest.tar.gz - we'll get a copy of it now and put it in the right place:

cd /home/data/[domain name]
sudo wget https://wordpress.org/latest.tar.gz
sudo tar xvfz latest.tar.gz && sudo mv wordpress src

After this, you should find a directory, src in your [domain name] directory. That contains all the default source code for WordPress including default themes and plugins.

Next, we have to make sure the default theme is in place, and then set up the WordPress multisite configuration process.

Later we'll get the assortment of third party plugins and custom OERu plugins needed to flesh out the WordPress functionality we need.

OERu Theme

First, we'll get the OERu theme, which is specially designed to provide an accessible desktop or mobile experience, given that many - even a majority - of our learners are in the developing world, where mobile computing is dominant!

We'll go to the theme directory - you should already be in /home/data/[domain name]. From there we go into the theme directory:

cd src/wp-content/themes

and we issue a git clone command to retrieve the latest version of the OERu theme from our git repository:

sudo git clone https://git.oeru.org/oeru/oeru_course.git oeru-course

Then it's time to customise our WordPress configuration.

Customise wp-config.php

First we need to create your wp-config.php file in your src directory:

sudo nano wp-config.php

Note: you'll need your password for Redis and a set of [wordpress keys and salts], both of which are essentially just random numbers that are used to make you site far more secure. You can use the this link to generate a set of random values suitable for copying-and-pasting into you wp-config.php file in your src directory - here's an example of the output I just requested (don't use these, generate your own):

define('AUTH_KEY',         '?4^Huc~R1=WW+T_p~.0dH$XJ`>U*MoreMmZ{@tORSFG3aX37#ZS+0ou{j^DS3{f<');
define('SECURE_AUTH_KEY',  '7.k4htjPnrA/?6JJlogA4Wp*o|,&&>;20ppqeqHq#gI <%gDz[o( hpRRB|!jws%');
define('LOGGED_IN_KEY',    'fTX,WkI=doAUE%?{zHp5.?fN%WWtBuy~`Scntr<]I1WvlF6i=7J kjO0Z%%~Z-`N');
define('NONCE_KEY',        '?p&]/*(G-+W!0#[&Y6KKj)j Ok5QI(SUc@@rv,ivtF> AR;Yv+Yu#>$B$<P9Ld|j');
define('AUTH_SALT',        'H6s2H~KP]Z7YXTFt|8[Lgz[1~5wF+PJzxR^KW$|he+9|RF/vi@}/|<8bkC:w)qW%');
define('SECURE_AUTH_SALT', '@- j6Kn CjP/mdbmLXtkC+>1>+H-8pXETlJ4+]b-9x_/t*.D}VA1w<^A?0 R<f+1');
define('LOGGED_IN_SALT',   ' y9:oh)]nA$}%9N-xk1MAQN1bH 8z{UD/e~K|G5{(9y|,n2E*,KwYPIf~HwhHT J');
define('NONCE_SALT',       '|B?p#Q4|.=[VL8)2AX;zy-R2;x#dqIo=!C3,;OACT%-uaQ7Li5KSVSSnLahwlZ+o');

This is what your wp-config.php file should look like - copy and paste the following into the file, replacing the relevant [tokens] with your versions (in particular note that the above wordpress keys and salts need to go where I've got the token [wordpress keys and salts] below):

<?php
/**
 * The base configuration for WordPress
 *
 * The wp-config.php creation script uses this file during the
 * installation. You don't have to use the web site, you can
 * copy this file to "wp-config.php" and fill in the values.
 *
 * This file contains the following configurations:
 *
 * * MySQL settings
 * * Secret keys
 * * Database table prefix
 * * ABSPATH
 *
 * @link https://codex.wordpress.org/Editing_wp-config.php
 *
 * @package WordPress
 */
 
// ** MySQL settings - You can get this info from your web host ** //
/** The name of the database for WordPress */
define('DB_NAME', '[database name');
 
/** MySQL database username */
define('DB_USER', '[database user]');
 
/** MySQL database password */
define('DB_PASSWORD', '[database password]');
 
/** MySQL hostname */
//define('DB_HOST', '10.10.10.1');
define('DB_HOST', '172.17.0.1');
 
/** Database Charset to use in creating database tables. */
define('DB_CHARSET', 'utf8mb4');
//define('DB_CHARSET', 'utf8');
 
/** The Database Collate type. Don't change this if in doubt. */
define('DB_COLLATE', '');
 
/**#@+
 * Authentication Unique Keys and Salts.
 *
 * Change these to different unique phrases!
 * You can generate these using the {@link https://api.wordpress.org/secret-key/1.1/salt/ WordPress.org secret-key service}
 * You can change these at any point in time to invalidate all existing cookies. This will force all users to have to log in again.
 *
 * @since 2.6.0
 */
[wordpress keys and salts]
 
/**
 * WordPress Database Table prefix.
 *
 * You can have multiple installations in one database if you give each
 * a unique prefix. Only numbers, letters, and underscores please!
 */
$table_prefix  = 'wp_';
 
/**
 * For developers: WordPress debugging mode.
 *
 * Change this to true to enable the display of notices during development.
 * It is strongly recommended that plugin and theme developers use WP_DEBUG
 * in their development environments.
 *
 * For information on other constants that can be used for debugging,
 * visit the Codex.
 *
 * @link https://codex.wordpress.org/Debugging_in_WordPress
 */
define('WP_DEBUG', false);
//define('WP_DEBUG', true);
define('CONCATENATE_SCRIPTS', false);
define('SCRIPT_DEBUG', true);
define('WP_DEBUG', true);
define('WP_DISABLE_FATAL_ERROR_HANDLER', true );   // 5.2 and later
 
/* We are behind a reverse proxy */
if (isset($_SERVER['HTTP_X_FORWARDED_FOR'])) {
    $forwarded_address = explode(',', $_SERVER['HTTP_X_FORWARDED_FOR']);
    $_SERVER['REMOTE_ADDR'] = $forwarded_address[0];
}
if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] == 'https') {
    $_SERVER['HTTPS'] = 'on';
}
 
/* Disable the default 'ad hoc' cron mechanism.
   We'll use actual cron instead. */
define('DISABLE_WP_CRON', true);
 
/* That's all, stop editing! Happy blogging. */
 
/** Absolute path to the WordPress directory. */
if ( !defined('ABSPATH') )
        define('ABSPATH', dirname(__FILE__) . '/');
 
/* Multisite */
// see https://wordpress.org/support/article/create-a-network/ 
define('WP_ALLOW_MULTISITE', true);
/*define('MULTISITE', true);
define('SUBDOMAIN_INSTALL', false);
define('DOMAIN_CURRENT_SITE', '[domain name]');
define('PATH_CURRENT_SITE', '/');
define('SITE_ID_CURRENT_SITE', 1);
define('BLOG_ID_CURRENT_SITE', 1);*/
 
/* disable trash, immediately permanently delete */
define('EMPTY_TRASH_DAYS', 0);
/* set the default theme for the network */
define('WP_DEFAULT_THEME', 'oeru_course');
 
/** Caching-related configuration */
/** Redis */
define('WP_REDIS_HOST', 'redis');
define('WP_REDIS_PASSWORD', '[redis password]');
define('WP_REDIS_PATH', '/tmp/cache');
 
/* WEnotes plugin configuration, commented out by default */
/* this is optional(!!) - only use if you're deploying the OERu WEnotes stack - contact us if you want help! */
/*define('WENOTES_HOST', '[couchdb host]');
define('WENOTES_PORT', '80');
define('WENOTES_DB',   '[couchdb mention database]');
define('WENOTES_USER', '[couchdb user]');
define('WENOTES_PASS', '[couchdb password]');*/
 
// go to /wp-admin/maint/repair.php to see if a repair is needed...
//define( 'WP_ALLOW_REPAIR', true );
 
 
/** Sets up WordPress vars and included files. */
require_once(ABSPATH . 'wp-settings.php');

Step five - set up Docker Compose for the site

The recipe for the four Docker containers that together provide the WordPress multisite service is pretty straightforward. All you need to do is go into /home/docker/[domain name] and

sudo nano docker-compose.yml

and enter the following, replacing the [tokens] as usual - note, if you don't have the same value for [port] specified below as you do in your 'reverse proxy' configuration above, nothing will work:

version: "3"
 
services:
    redis:
        image: redis:alpine
        command: redis-server --requirepass [redis password]
        networks:
            default:
                aliases:
                   - redis.[domain name]
    php:
        image: oeru/php74-fpm-wpms
        links:
            - redis
        volumes:
            - /home/data/[domain name]/src:/var/www/html
        environment:
            - SMTP_HOST=[smtp host]
            - SMTP_PORT=587
            - SMTP_REPLYTO_EMAIL=[smtp reply-to email address]
            - SMTP_AUTH_USER=[smtp user]
            - SMTP_AUTH_PASSWORD=[smtp password]
        restart: unless-stopped
        networks:
            default:
                aliases:
                   - [domain name]
    nginx:
        image: oeru/nginx-buster-wp
        links:
            - php
            - redis
        ports:
            - "127.0.0.1:[port]:80"
        volumes:
            - /home/data/[domain name]/nginx/conf.d:/etc/nginx/conf.d
            - /home/data/[domain name]/nginx/cache:/var/cache/nginx
            - /home/data/[domain name]/src:/var/www/html
        restart: unless-stopped
        networks:
            default:
                aliases:
                   - nginx.[domain name]
    cron:
        image: oeru/php74-fpm-wpms-cron
        links:
            - php
            - nginx
        volumes:
            - /home/data/[domain name]/src:/var/www/html
        environment:
            - SMTP_HOST=[smtp host]
            - SMTP_PORT=587
            - SMTP_REPLYTO_EMAIL=[smtp reply-to email address]
            - SMTP_AUTH_USER=[smtp user]
            - SMTP_AUTH_PASSWORD=[smtp password]
        restart: unless-stopped
        networks:
            default:
                aliases:
                   - cron.[domain name]

Create the NGINX container's configuration

In our Docker Compose file, we've specified that our NGINX container will have its configuration in /home/data/[domain name]/nginx/conf.d, so let's put it there.

Run the following:

sudo mkdir -p /home/data/[domain name]/nginx/conf.d

to create the relevant directories, and then create the default configuration for the container:

sudo nano /home/data/[domain name]/nginx/conf.d/default.conf

Copy and paste this

# Caching configuration
# https://easyengine.io/wordpress-nginx/tutorials/multisite/subdirectories/fastcgi-cache-with-purging/
#
fastcgi_cache_path /var/cache/nginx levels=1:2 keys_zone=WORDPRESS:500m inactive=60m;
fastcgi_cache_key "$scheme$request_method$host$request_uri";
fastcgi_cache_use_stale error timeout invalid_header http_500;
 
# from https://www.nginx.com/resources/wiki/start/topics/recipes/wordpress/
#
# using subdir approach, not subdomain...
map $uri $blogname{
    ~^(?P<blogpath>/[^/]+/)files/(.*)  $blogpath ;
}
 
map $blogname $blogid{
    default -999;
    #Ref: http://wordpress.org/extend/plugins/nginx-helper/
    include /var/www/html/wp-content/uploads/nginx-helper/map.conf;
}
 
# statements for each of your virtual hosts to this file
server {
    listen 80;
    root /var/www/html;
    index index.php index.html index.htm;
 
    #
    # Caching configuration
    #
    #fastcgi_cache start
    set $skip_cache 1;
 
    # POST requests and urls with a query string should always go to PHP
    if ($request_method = POST) { set $skip_cache 1; }
    if ($query_string != "") { set $skip_cache 1; }
 
    # Don't cache uris containing the following segments
    if ($request_uri ~* "(/wp-admin/|/xmlrpc.php|/wp-(app|cron|login|register|mail).php|wp-.*.php|/feed/|index.php|wp-comments-popup.php|wp-links-opml.php|wp-locations.php|sitemap(_index)?.xml|[a-z0-9_-]+-sitemap([0-9]+)?.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") {
        set $skip_cache 1;
    }
    # end main Caching functionality
 
    #
    # Flow of serving pages
    #
    # from https://www.nginx.com/resources/wiki/start/topics/recipes/wordpress/
 
    #avoid php readfile()
    location ^~ /blogs.dir {
        internal;
        alias /var/www/html/wp-content/blogs.dir;
        access_log off; log_not_found off; expires max;
    }
 
    if (!-e $request_filename) {
        rewrite /wp-admin$ $scheme://$host$uri/ permanent;
        rewrite ^(/[^/]+)?(/wp-.*) $2 last;
        rewrite ^(/[^/]+)?(/.*\.php) $2 last;
    }
 
    # from https://www.digitalocean.com/community/tutorials/how-to-install-wordpress-with-nginx-on-ubuntu-14-04
    # with other bits from https://premium.wpmudev.org/blog/wordpress-multisite-wordpress-nginx/
    location / {
        try_files $uri $uri/ /index.php?$args;
    }
    error_page 404 /404.html;
 
    # Directives to send expires headers and turn off 404 error logging.
    location ~* ^.+\.(xml|ogg|ogv|svg|svgz|eot|otf|woff|mp4|ttf|css|rss|atom|js|jpg|jpeg|gif|png|ico|zip|tgz|gz|rar|bz2|doc|xls|exe|ppt|tar|mid|midi|wav|bmp|rtf)$ {
        access_log off; log_not_found off; expires max;
    }
 
    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_pass php:9000;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_keep_conn on;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        fastcgi_intercept_errors on;
        fastcgi_buffer_size 128k;
        fastcgi_buffers 256 16k;
        fastcgi_busy_buffers_size 256k;
        fastcgi_temp_file_write_size 256k;
        fastcgi_read_timeout 500;
        #
        # caching functionality
       fastcgi_cache_bypass $skip_cache;
        fastcgi_no_cache $skip_cache;
       fastcgi_cache WORDPRESS;
       fastcgi_cache_valid 60m;
    }
    #
    # caching functionality
    location ~ /purge(/.*) { fastcgi_cache_purge WORDPRESS "$scheme$request_method$host$1";    }
    location = /favicon.ico { log_not_found off; access_log off; }
    location = /robots.txt { allow all; log_not_found off; access_log off; }
    location ~ ^(/[^/]+/)?files/(.+) {
        try_files /wp-content/blogs.dir/$blogid/files/$2 /wp-includes/ms-files.php?file=$2 ;
        access_log off; log_not_found off; expires max;
    }
}

and save and exit the file.

And now we have to create the following directory and file:

sudo mkdir -p /home/data/[domain name]/src/wp-content/uploads/nginx-helper

sudo touch /home/data/[domain name]/src/wp-content/uploads/nginx-helper/map.conf

Once that's done, we're ready to launch our containers... Phew.

Launch containers

Once that's done you can download the relevant containers (you may need to set up an account on https://hub.docker.com first - do that and then run docker login before doing the following):

docker-compose pull && docker-compose up -d && docker-compose logs -f

which will show you the combined logs of the four containers and should give you some insights if something goes wrong. If all is well, you can type CTRL-C to exit it. The Docker containers (to see what's running, you can run docker-compose ps) will run until you explicitly stop them (docker-compose stop). Unless you stop them prior to lock down, they will automatically restart anytime your server reboots.

Step Six - set up your site

Install WordPress

You should now be able to point your browser at https://[your domain] and you should automatically be redirected to the WordPress site install script, with all the database details already entered. You'll need to fill in the configuration fields and create an admin user.

Enable the OERu Course theme

You should already be in the /home/docker/[domain name] directory, but if not,

cd /home/docker/[domain name]

and then you can enable the OERu Course theme, oeru-course, using WordPress's command line utility, wp, via your PHP container:

docker-compose exec -u www-data php wp theme enable oeru-course

You should get the message Success: Enabled the 'OERu Course' theme. if all went well.

Create an admin user

Your admin user should probably be an account not normally used by a person. I usually create an admin user with a username of 'admin', a random password (using pwgen as above) and a role-based email like webmaster@[domain name] (if your domain name has email services) or some similarly useful generic email (using that protects against the 'tyranny of the individual', e.g. if you leave the organisation in whose interest you're setting up this site, and those left behind will have to make sense of this site and keep it running!

Later one, if you want to log into the site, you can always get a login prompt by going to https://[domain name]/admin/ ...

Enable multisite

The WordPress configuration we've set up in the wp-config.php file should have enabled the inbuilt functionality for enabling 'multisite' mode (or 'network', as it used to be called, i.e. for a "Network of Blogs", back when WordPress was more exclusively used for blogging). WordPress developer documentation on 'Creating a network' might be a useful reference if you run into any trouble.

Logged in as your admin user, in the admin menu structure go to Administration >Tools > Network Setup

You will be asked ot provide your Network Title and Network Admin Email (which can be the same as your current admin email).

You will also be asked whether you want to use the 'Sub-domains' or 'Sub-directories' structure for your network. Select the Sub-directories option (you will need to make changes your Nginx configurations and the wp-config.php configuration to use Sub-domains, which are beyond the scope of this howto), which means that each of your subsites will have a separate directory under your main site [domain name]. For example, on the OERu Course site, course.oeru.org, the Learning in a Digital Age 101 course sub-site is course.oeru.org/lida101. If you chose to use the Sub-domain option, you would instead reference that course as lida101.course.oeru.org.

Once you've enabled multisite, you need to update your wp-config.php -

sudo nano wp-config.php

and make the following change, to comment out the WP_ALLOW_MULTISITE variable, and uncomment the various MULTISITE-related settings:

/* Multisite */
// see https://wordpress.org/support/article/create-a-network/ 
//define('WP_ALLOW_MULTISITE', true);
define('MULTISITE', true);
define('SUBDOMAIN_INSTALL', false);
define('DOMAIN_CURRENT_SITE', '[domain name]');
define('PATH_CURRENT_SITE', '/');
define('SITE_ID_CURRENT_SITE', 1);
define('BLOG_ID_CURRENT_SITE', 1);

After you've saved that, and refreshed the page on your WordPress site, you should be looking at a fully functioning multisite!

Enable the relevant plugins

Third Party plugins

Now we need to get the specific OERu plugins that are not (yet) available through the WordPress plugin site.

The ones we use by default are

advanced-responsive-video-embedder, check-email, disable-comments, h5p, hypothesis, redis-cache, safe-redirect-manager, unconfirmed, wp-security-audit-log

As we did with the OERu Course theme, we'll install and active these plugins using WordPress's command line utility, wp, via your PHP container:

cd /home/docker/[domain name]

you can see the names of all your running containers by running this:

docker-compose ps

and you can download and activate all these plugins in 'network' (aka multisite) mode like this:

docker-compose exec -u www-data php wp plugin install advanced-responsive-video-embedder --activate-network
docker-compose exec -u www-data php wp plugin install check-email --activate-network
docker-compose exec -u www-data php wp plugin install disable-comments --activate-network
docker-compose exec -u www-data php wp plugin install h5p --activate-network
docker-compose exec -u www-data php wp plugin install hypothesis --activate-network
docker-compose exec -u www-data php wp plugin install redis-cache --activate-network
docker-compose exec -u www-data php wp plugin install safe-redirect-manager --activate-network
docker-compose exec -u www-data php wp plugin install unconfirmed --activate-network
docker-compose exec -u www-data php wp plugin install wp-security-audit-log --activate-network

These plugins should work as required without any specific configuration, but you're welcome to have a look at what they're doing and tweak them as you see fit.

OERu plugins

The final step is to install and enable the custom-developed plugins required to make this WordPress installation meet the requirements of an OERu Course site.

At the OERu (and the OER Foundation, who coordinates the OERu and employs me) we make extensive use of Git to manage our source code and to deploy it on our various servers. We'll use it here.

You'll need to go back to the plugin directory:

cd /home/data/[domain name]/src/wp-content/plugins

and run the following:

sudo git clone https://git.oeru.org/oeru/blog-feed-finder.git blog-feed-finder
sudo git clone https://git.oeru.org/oeru/oeru-h5p-tools.git oeru-h5p-tools
sudo git clone https://git.oeru.org/oeru/register-enrol.git register-enrol
sudo git clone https://git.oeru.org/oeru/wenotes.git wenotes
sudo git clone https://git.oeru.org/oeru/wpms-activity-register.git wpms-activity-register
sudo git clone https://git.oeru.org/oeru/wpms-mautic.git wpms-mautic

and the WEnotes plugin has a further dependency, our WEnotes Aggregator code.

cd wenotes
sudo git clone https://git.oeru.org/oeru/wenotes-aggregator.git wenotes-aggregator

We need ot make sure the plugins are all readable by the webserver, so

cd .. && sudo chown -R www-data ../plugins

And we have to make a couple tweaks to configurations of a couple plugins.

WEnotes tweaks

You'll want to set your WENOTES_SOURCE_NAME and WENOTES_SOURCE_URL so that your WEnotes are properly attributed.

[geshifilter-]cd /home/data/[domain name]/src/wp-content/plugins sudo nano wenotes/wenotes.php [/geshifilter-]

and edit the following values (between the ' ') to be suitable for your organisation! Put in your preferred URL as well.

define('WENOTES_SOURCE_NAME', 'OERu Course Site');
define('WENOTES_SOURCE_URL', 'course.oeru.org');

Register Enrol tweaks

Similarly, you are likely to want to change the following settings in the Register Enrol plugin configuration to reflect your site and organisation. First, edit register-enrol.php

sudo nano register-enrol/register-enrol.php

and alter the following values (between the ' ') to suit (we don't recommend change other settings unless you know what you're doing!):

// support link for users of this plugin...
define('ORE_SUPPORT_FORUM', 'https://forums.oeru.org/t/register-enrol');
define('ORE_SUPPORT_BLOG', 'https://course.oeru.org/support/studying-courses/register-enrol/');
define('ORE_SUPPORT_CONTACT', 'https://oeru.org/contact-us/');
define('ORE_SUPPORT_PASSWORD_MANAGER', 'https://course.oeru.org/lida102/learning-pathways/digital-environments/online-hygiene/#Password_managers');

and

define('ORE_DEFAULT_FROM_EMAIL', 'webmaster@oerfoundation.org');

Mautic Integration tweaks

You might also want to set up an OERu Partner record for your organisation (if you're not already a partner!) in our Mautic integration plugin in the file wpms-mautic/includes/mautic-sync.php in the $partner_names array and then and set your MAUTIC_DEFAULT_PARTNER to have your partner name in wpms-mautic/mautic-app.php.

Reasserting ownership

And a final step - this is crucial, as it will allow you to keep your WordPress instance up-to-date using the various WordPress standard approaches - is to ensure that the webserver user, www-data is the owner of the source code in your site:

sudo chown -R www-data /home/data/[domain name]/src

That's it. Done. Phew.

Step Seven - celebrate!

You've done it! You've got yourself a new Course WordPress multisite! Which, if I do say so myself, is an impressive accomplishment in it's own right.

Of course, it might not be as exciting as actually having a real live course hosted on your Course WordPress multisites... so there's one more step (maybe take a quick break to celebrate getting to this milestone before proceeding).

Snapshotting your first OER course!

There are quite a few courses (fully accredited!) available to push to your Course multisite on WikiEducator where we work with educators around the world to assemble OER-based courses, usually split into discrete 'micro-courses' that can be assembled to meet the credit requirement conventions in different parts of the world.

Here is an example course you can add to verify the process: the first micro-course in our (award winning) Learning in a digital age, called Digital literacies for online learning. That link points to the Outline for the course, which in turn shows all the resources making up the course materials in the hierarchy that will become the navigation of the resulting Course site on your WordPress Multisite. The way e get it there is by using our "Course Snapshot" process which converts that WikiEducator content in the outline into a WordPress content archive that it then pushes onto your designated Course subsite.

Before we can run a snapshot, you'll need to

request a WikiEducator account - unfortunately this is a moderated process (i.e. a person at the OER Foundation has to review your request) because we have lots of problems with would-be spammers. So this could take a fair while depending on when you request it (we're on NZ time). So much for instant gratification. Sorry about that.
you'll need to create a subsite (you don't want to replace your multisite's base site).

To do the latter, when you're logged into your WordPress multisite as the admin user, use the top menu to go to 'My Sites' -> 'Network Admin' -> 'Sites' and click the 'Add New' button. You'll need to specify a "Site Address (URL)" which is just the path following [domain name] in referencing your site. For example, the LiDA 101 course on the OERu's Course site is https://course.oeru.org/lida101 where lida101 is that path. You could use that same path here if you want (it's appropriate for this course).

You'll also need a title - you could use "Digital literacies for online learning" - and pick a Site Language (the default is probably what you want). For the 'Admin Email', use the email of your admin user, as WordPress will then make the user with that email, namely your admin user, the administrator of that lida1010 subsite, which is what we want.

Next, we go back to the WikiEducator page for the LiDA 101 outline above and find the 'Request snapshot' button near the top of the page. This is the important bit - Note: doing this will remove any existing content in the subsite you specify! Make sure that's what you're intending - clicking it will give you a dialog box into which you'll enter the full location of your subsite, which will look like https://[domain name]/[subsite name] (for example, in the OERu case it is https://course.oeru.org/lida101) , making suitable [token] substitutions, of course, and enter as your WordPress admin user and password. Clicking "Push snapshot to WordPress" sets things in motion, and, all going well, you should receive an email in a few minutes (5-20, usually) when the system has got to your request (it does them on a first-come, first-served basis) and processed it successfully. If you get that email, have another look at your site! It should look very similar to what you see on https://course.oeru.org/lida101 with the main difference being (possibly) the colour scheme and the lack of a Login/Register prompt (top right). That can be fixed as I explain next.

Enabling OERu's Register Enrol functionality

The interface the OER Foundation has developed to help learners register for the site and enrol in specific courses is not enabled by default and needs to be turned on for any given Course sub-site (this is useful for courses that are visible on the site, but not yet ready to accept enrolments). To do so, go to the relevant course site dashboard in the WordPress menu, and select Appearance -> Customize. In the resulting theme customisation side panel, selelct 'Site Navigation', and then set 'Show the login option?' to 'Yes' and 'Publish' to save the setting. Your login prompt should show near the top right corner of all the pages in that course site at that point.

Also note, you can change the pre-set colour palette for your course sites on a per-site basis using the menu combination OERu Theme -> Colour Scheme...

Data Backups

Your MariaDB will already be getting backed up daily via the automysqlbackup script installed towards the start of this process, but you also want to have backups of files and configurations on your server, and you want to have backups on a different server, i.e. remote to your server, as a matter of disaster-recovery prudence.

We will be describing how we do remote, encrypted, incremental backups in a separate how-to and will link to it here as soon as it's available.

Staying up-to-date

You should log into your site as your admin user or as your personal user (granted Administrator permissions by your admin user!) periodically to see if there are any updates available for your site - if there are, you can update them as per the instructions provided by the site.

The OERu plugins and themes undergo periodic improvements or bug fixes. To find out about them, you'll need to keep track of the various Git repositories on our Gitlab instance.

These are the relevant repositories:

We're always delighted to hear from folks using any of these components and invite people to collaborate with us on improving any and all of these software projects, including providing access to our Gitlab!

Also, from time to time, we might update the Docker containers we use for this service, and you're always welcome to make use of our updated containers. If you have any questions, feel free to get in touch or leave a comment below!!

Acknowledgements

Many thanks to the good folks at the Samoan Ministry for Education, Sport, and Culture and UNESCO in Apia for motivating me to write this up, and to educational technologist luminary Stephen Downes for unexpectedly finding this tutorial and then (even more unexpectedly) heroically and comprehensively going through it and providing extensive editorial input (part 1 and part 2), most (if not all) of which I've since incorporated! Thanks Stephen - see people were listening (just not in real-time)!

Add new comment

Protecting your users with Let's Encrypt SSL Certs

dave — Thu, 08 Jul 2021 02:23:06 +0000

Protecting your users with Let's Encrypt SSL Certs

Blog tags

let's encrypt

install

ubuntu linux

14.04

16.04

18.04

20.04

dave Thu 08/07/2021 - 14:23

SkFor any website that requires anyone (users or even just a few admins) to transfer secrets to and from it, you want to ensure the data is end-to-end encrypted. Today various browsers (like Firefox) give warnings when you're sending secret data (like passwords) "in the clear", namely unencrypted. In early 2017, Google added further urgency to doing the right thing for your users.

In the past, getting an SSL certificate to achieve encryption for your domain (the little "lock" icon in browser address bar indicating that your communication with the site is encrypted), was a complicated, expensive proposition, requiring a lot of annoying and time consuming "identity verification" (sometimes via post in the dark old days) and a fee of, in some cases, a couple hundred dollars per year paid to your "SSL Cert Provider" to pay for those administrative services along with the software needed to gin up a long prime number to act as your encryption key (the long string of characters making up your SSL certificate).

Thankfully, thanks to the efforts of the Let's Encrypt community, the process is both far far easier, and free of cost. Now there really isn't an excuse for not having an SSL certificate on your site.

Members of the Let's Encrypt community have provided a range of useful open source tools you can use to create and maintain certificates on your hosting infrastructure (e.g. the Virtual Machine (VM) on which you're installing web services detailed in the howtos on this site!). In this case we're going to use a tool, "certbot" provided by the good folks at the Electronic Frontier Foundation.

For VMs running Ubuntu 18.04 or more recent Long Term Support (LTS) versions of the Ubuntu Linux platform, you should be able to just run:

sudo apt-get install letsencrypt

For VMs running Ubuntu 14.04 or 16.04 which are what we use, the install is easy - at your VM command line, run:

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

We run Nginx on our VMs, which makes one or more hosted services (normally running in Docker containers) available on the Internet. Strictly speaking, we don't use full "end-to-end" encryption - in our case, on the server-end the encryption terminates at the Nginx server. We, perhaps cavalierly, assume that transfer between the host machine and a Docker container running on that host will be implicitly secure... The only way it could be compromised is if the VM itself is compromised, in which case, the Docker containers running on it could be, too. Avoiding having secure transfer between Nginx on the VM host and the various Docker containers also substantially simplifies setting up each application.

Thanks to a service which Nginx provides SNI (or Server Name Indication) - Apache and a few other web servers also provide this - which removes the historical limitation that meant you could only have one SSL certificate per IP address on a web server. The only downside of SNI is that some older browsers (and platforms) don't support it. Since those older technologies are rapidly dying out and it's quite expensive and difficult to have a single IP address for each SSL service on a server, we accept this compromise.

The Let's Encrypt Cert Process

Here's (roughly) how the process works:

Point your domain (via A or CNAME record) to point to the/an external IP address on your VM.
Set up a domain (or domains) for non-secure hosting (on port 80) via your Nginx instance.
The domain's configuration must include a special directory reserved for Let's Encrypt verification content.
You request that certbot (on the VM) acquires a certificate for that domain (or domains) at which point
1. the certbot writes a file with a hard-to-guess name to that special directory and requests that the Let's Encrypt infrastructure checks the domain name from outside
2. Let's Encrypt checks that domain name and special directory to see that the expected number appears there, thus verifying that the requesting party actually has the ability to set content at this hard-to-guess filename, and therefore has legitimate claim to being the party controlling the domain name and server.
3. Let's Encrypt registers the certificate request in the name of the party running the certbot (so it can, for example, send emails to the administrator warning them that the certificate needs to be renewed - which happens every 8 weeks or so), and
4. Let's Encrypt sends verification back to your VM's certbot telling it to complete the certificate generation, which it then (digitally) signs in the name of the Let's Encrypt Certificate Authority (which, in turn, is recognised by almost all web browsers out-of-the-box - no mean feat, I can tell you).
You get an alert telling you that you have created a valid SSL certificate.
You alter your Nginx domain configuration to
1. redirect connections to port 80 (un-encrypted) to port 443 (encrypted), and
2. you set up the 443 configuration including your new certificates.
You reload your Nginx configuration, and your site will now be end-to-end encrypted.

The Let's Encrypt Snippet

To make it easy to include the relevant directory info, I recommend that you create a new file in your Nginx configuration (substitute your preferred text editor for "vim" in the following - "nano" is a good choice if you haven't already got a preference):

sudo mkdir /etc/nginx/includes sudo vim /etc/nginx/includes/letsencrypt.conf

and make sure it has the following content (note, I learned this thanks to someone else's howto on the global Internet knowledge commons :))

# Rule for legitimate ACME Challenge requests location ^~ /.well-known/acme-challenge/ { default_type "text/plain"; # this can be any directory, but this name keeps it clear root /var/www/letsencrypt; }

# Hide /acme-challenge subdirectory and return 404 on all requests. # It is somewhat more secure than letting Nginx return 403. # Ending slash is important! location = /.well-known/acme-challenge/ { return 404; }

Next, make sure your directory exists (note - you only need to do this once per VM) - it shouldn't need an special permissions - it'll be written by the "root" user, and needs to be readable by the Nginx user, usually "www-data" on a Debian or Ubuntu Linux instance.

mkdir /var/www/letsencrypt

Example Nginx Domain Configuration - unencrypted

Here's an example of a pre-cert Nginx domain configuration for example.org and www.example.org (I usually name the configuration file after the main domain it concerns, so my file would be /etc/nginx/sites-available/example.org) - this should also let you do initial test of your app to make sure it works, before adding the additional complexity of SSL. (Replace example.com (and www.example.com) with your own domain!):

server {

listen 80; # this is one of our external IPs on the server. #listen [::]:80 default ipv6only=on; ## listen for ipv6 # this root directory isn't really relevant in a proxy situation
# so I usually set it to the system default root /usr/share/nginx/www; index index.html index.htm; server_name example.org www.example.org; access_log /var/log/nginx/example.org_access.log; error_log /var/log/nginx/example.org_error.log;

# this is where we include the snippet include /etc/nginx/includes/letsencrypt.conf;

# this is just an example of a "proxy" configuration # for, say, a Docker-based service, exposed on the VM's # local port 8081 location / { proxy_read_timeout 300; proxy_connect_timeout 300; proxy_redirect off; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_pass http://127.0.0.1:8081; }
}

You can make sure that the configuration is visible to Nginx by adding it into the "sites-enabled" directory via a file link

sudo ln -sf /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled

Test things to make sure the new configuration doesn't have typos or bad references:

sudo nginx -t

and if not, make it live:

sudo service nginx reload

You should now be able to go to http://example.com (or your domain) and you'll hopefully get your proxied application (if it's set up) or an Nginx error (see you nginx error file for more info!).

Now it's time to request the certificate!

Example Certbot invocation

Once cerbot is installed, and a domain is configured, it's pretty straightforward to get a certificate.

On the first invocation of certbot, you might get a coloured interface that requests your user details (e.g. name and email address) so that Let's Encrypt can register them for the purposes of future emails. They email if one of your certificates is on the verge of expiring, or if there's been a change to Let's Encrypt policy or process. It's worth being on the list.

You can request your certificate with the following:

sudo certbot certonly --webroot -w /var/www/letsencrypt -d example.org -d www.example.org

If it works, it gratifyingly results in a message that starts with "Congratulations"!

Example Nginx Domain Configuration - unencrypted

Once you've got your certificate, you can reference it in your configuration. We normally set up a redirect from the unencrypted version of the site to the encrypted on (except for the Let's Encrypt verification directory!):

server {     listen 80; # listen on port 80 on all IPv4 addresses
    listen [::]:80; # listen on port 80 on all IPv6 addresses
    root /var/www/html;     index index.html index.htm;     server_name example.org www.example.org;     access_log /var/log/nginx/example.org_access.log;     error_log /var/log/nginx/example.org_error.log;

include /etc/nginx/includes/letsencrypt.conf;

    # a 302 is a "soft" redirect. A 301 can never be reversed.     location / {         return 302 https://example.org$request_uri;     }      } server {
    listen 443 ssl; # listen on port 443 on all IPv4 addresses
    listen [::]:443 ssl; # listen on port 443 on all IPv6 addresses

    # this is a deprecated rule, not required in Ubuntu 20.04's nginx     # ssl on;     ssl_certificate /etc/letsencrypt/live/example.org/fullchain.pem;     ssl_certificate_key /etc/letsencrypt/live/example.org/privkey.pem;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2; ssl_dhparam /etc/ssl/certs/dhparam.pem;     keepalive_timeout 20s;

access_log /var/log/nginx/example.org_access.log; error_log /var/log/nginx/example.org_error.log;

root /var/www/html; index index.html index.htm;

server_name example.org www.example.org; # this is just an example of a "proxy" configuration # for, say, a Docker-based service, exposed on the VM's # local port 8081 location / { proxy_read_timeout 300; proxy_connect_timeout 300; proxy_redirect off; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_pass http://127.0.0.1:8081; }
}

Note - you also need to set up the ssl_dhparam file for this configuration to work. You can do this based on these instructions after installing OpenSSL tools:

sudo apt-get install openssl

by running (warning - this can take quite a long time, 5-15 minutes in my experience - the system needs to generate sufficient entropy to achieve acceptable randomness):

openssl dhparam -out /etc/ssl/certs/dhparam.pem 4096

When you've set up the file, you can enable it:

sudo ln -sf /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled

Test the file to ensure there aren't any syntax errors before reloading nginx:

sudo nginx -t

If this shows an error, you'll need to fix the file. If all's well, reload nginx to enable the new configuration:

sudo service nginx reload

You should now be able to point your browser at your domain name, and it should automatically redirect you to https://example.org - and (based on the above configuration, https://www.example.org should work too. You might want to redirect www.example.org to example.org or visa versa).

A word to the wise - if it doesn't work, check your firewall settings!

Update: discovered this very well done how-to on Let's Encrypt that offers additional background to this one.

Ongoing Certificate Maintenance

One of the nice things about EFF's certbot is that when it's installed, it also installs a nightly cron task (see /etc/cron.d/certbot) which checks all domains registered on the server for renewals. Assuming your domains have been configured in Nginx as described above, renewals should occur automatically, and you'll just receive a periodic email to let you know that they've happened.

If you want to check your renewal status, you can run this:

sudo certbot renew --dry-run

Good on you for securing your users and your site!

Add new comment

Installing NextCloud and Collabora Office Online with Docker on Ubuntu 16.04

dave — Mon, 29 Jan 2018 04:29:13 +0000

Installing NextCloud and Collabora Office Online with Docker on Ubuntu 16.04

Blog tags

ubuntu linux

mariadb

docker

docker-compose

php

collabora office

nextcloud

let's encrypt

redis

productivity

nginx

dave Mon 29/01/2018 - 17:29

Update 2021-11-08: this post is now getting a bit long-in-the-tooth, and I need to update it to use up-to-date components. It might still be useful to folks, but use it with caution. Also, please note, we're using NextCloud with OnlyOffice (the open source community edition) these days. Update 2023-06-14: Here's a new tutorial for Ubuntu 22.04!

Dropbox is the best known of the end-user "cloud storage" services for documents, backups, and synchronising data among multiple devices, although now Google's Drive and Microsoft's OneDrive are functionally similar and are being heavily promoted and tied into all sorts of services.

Similarly the collaborative editing of documents, spreadsheets, and presentations in the browser, pioneered by Etherpad, but then adopted in a big way by Google Docs (and more recently, Microsoft Office 365), has revolutionised collective note taking, document preparation, and ease of access to these powerful tools by the mainstream of computer users. Only a browser is required, and no other software needs to be installed.

But what about people who don't want to entrust all of their data to foreign corporations, holding their data in foreign jurisdiction, in formats that may or may not be retrievable in the event that the supplier fails or changes "strategic direction"? And many of these services involve "mining" their data to extract useful information that vendors sell to others to help them advertise to us in a more targeted way. Yeah, that's creepy.

More-over, often if you want to share your data with others, they have to log into the same service, and accept the service's terms and conditions (usually substantially constraining the user's normal rights and freedoms, although who actually reads those, eh?!) in order to do so... so ones use of those services has a magnifying effect on the loss of privacy and control.

Some people sensibly prefer to manage their own, or institution-specific, solutions on the infrastructure of their choosing, in a way that doesn't tie anyone into paying ever increasing amounts for data storage as the volumes increase perpetually, month on month.

Some of us simply prefer to have control of our own destiny, without a dependence on, for example, file or data storage formats and practices that are completely opaque to them. Our data reflects our creativity energy, and it seems much more comfortable for many of us to be in charge of our own fates rather than entrusting it to a third party who simply sees us a profit centre.

Thankfully, the open source world has created an array of possible equivalent systems, and this post describes how you, too, can set up your own equivalent to Dropbox + Google Docs using entirely open source software on any commodity virtual machine hosting system you want to use by adopting NextCloud and Collabora Office.

NextCloud

NextCloud is functionally similar to Dropbox, however, with its active development community and plug-in architecture, it can provide quite a lot more as well, like shared calendaring, email, video conferencing, contact syncing, image/sound/video galleries, among many other services.

If you prefer not to organise and run your own server, you can purchase a supported server via their website for a cost similar to Dropbox (although, realise that NextCloud is relatively small by comparison and doesn't have the massive economies of scale enjoyed by the bigger players).

For those with an interest in history: NextCloud is a fork created by the founder of OwnCloud, after he decided that the company which formed around his OwnCloud project was moving in a direction that was philosophical unpalatable for him. The beauty of open source is that developers can follow their consciences without requiring anyone's permission. The resulting "forks" in code bases and communities then thrive or die based on the strengths of the communities they can build and sustain. This fork is remarkably similar to that which occurred in the OpenOffice community which resulted in the founding of LibreOffice. LibreOffice has thrived and OpenOffice has faded into irrelevance. More on that below.

For those with a technological interest, NextCloud is a mature PHP application (but with a modern architecture, including a command line interface, occ) which stores its data in an RDBMS like MySQL, MariaDB, PostgreSQL, or (usually for development purposes) the lightweight SQLite database. Here are details for would-be administrators.

Collabora Office

Given how much companies like Google and Microsoft invest on Docs and Office 365 respectively, how is it possible for an open source community to create a credible competitor? Turns out it's not as hard as you might think if they leverage the power of open source.

A small software company with headquarters in the UK (although their team appears to be from all over), Collabora Office, has taken on the ambitious mission of creating a "collaborative web interface" allowing users to collaborate using LibreOffice, one of the most powerful and widely used office package available anywhere. We're currently at Collabora Office 3.0, and the front end is quite nice and functional, but still pretty simple - that can be a good thing for many users. Collabora is progressively re-imagining the user interface of LibreOffice as a collaborative web interface. This isn't easy, but it's much easier than it otherwise would be because the difficult job of creating the heavy-lifting application back-end is already done - LibreOffice is a mature widely used application (albeit with a desktop interface, not a web-based collaborative interface). So we can expect progress will be rapid, and large sets of new capabilities will be "unlocked" as they progress their efforts.

NextCloud and Collabora - better together!

The beauty of the open source software model is that we can connect NextCloud and Collabora office - completely separate and unrelated communities - thanks to a new integration standard, WOPI (Web-application Open Platform Interface) they form a well integrated component model - with the major added benefit of being able to swap in a better file management platform, or a better collaborative productivity package if one or the other emerges, without having to start from scratch.

Setting up your own NextCloud Collabora Server

If you're game to run your own (and, in my experience, it's a surprisingly well behaved system) here's how you do it.

In preparation, you'll want to have the following ready:

a Linux virtual machine or "VM" (I recommend running the current Ubuntu LTS version, or current Debian) with a user with Sudo privileges...,
your domain name for the NextCloud instance, pointing to the IP address of your VM,
your domain name for the Collabora instance, also pointing to the IP of your VM, and
credentials for an email address capable of sending from a remote server (usually termed an "authenticating SMTP email account")

Secure access with SSH

First things first, make sure you're logged into your host (probably via SSH) as a user who has "sudo" capabilities! You need to log into the host from your local machine. We recommend setting up key-based authentication.

Firewall with UFW

No computer system is ever full secure - there're always exploits waiting to be found, so security is a process of maintaining vigilance. Part of that is reducing exposure - minimising your "attack surface". Use a firewall - "ufw" is installed on Ubuntu by default. Make sure you've got exceptions for SSH (without them, you could lock yourself out of your machine! Doh!).

Run the following commands to allow your Docker containers to talk to other services on your host.

sudo ufw allow in on docker0 sudo ufw allow from 172.0.0.0/8 to any

Specifically for Docker's benefit, you need to tweak the default Forwarding rule (I use "vim" as my editor. If you don't know how to/want to use it, replace vim with nano everywhere you see it in the following - nano's easier to use for simple edits like this):

sudo vim /etc/default/ufw

and copy the line DEFAULT_FORWARD_POLICY="DROP" tweak it to look like this (commenting out the default, but leaving it there for future reference!):

#DEFAULT_FORWARD_POLICY="DROP" DEFAULT_FORWARD_POLICY="ACCEPT"

You also have to edit /etc/ufw/sysctl.conf and remove the "#" at the start of the following lines, so they look like this:

sudo vim /etc/ufw/sysctl.conf

# Uncomment this to allow this host to route packets between interfaces net/ipv4/ip_forward=1 net/ipv6/conf/default/forwarding=1 net/ipv6/conf/all/forwarding=1

and finally restart the network stack and ufw on your server

sudo service networking restart sudo service ufw restart

Installing the Nginx webserver

In the configuration I'm describing here, you'll need a webserver running on the server - it'll be acting as a "proxy" for the Docker-based Nginx instance described below. I like the efficiency of Nginx and clarity of Nginx configurations over those of Apache and other open source web servers. Here's how you install it.

sudo apt-get install nginx-full

To allow nginx to be visible via ports 80 and 443, run

sudo ufw allow "Nginx Full"

Note: make sure your hosting service is not blocking these ports at some outer layer (depending on who's providing that hosting service you may have to set up port forwarding).

Installing MariaDB

sudo apt-get install mariadb-server-10.0 mariadb-client-10.0

You need to set a root (admin) user password - you might want to create a /root/.my.cnf file containing the following (replacing YOURPASSWORD) to let you access MariaDB without a password from the commandline:

[client] user=root password=YOURPASSWORD

You should now be able to type "mysql" at the command prompt

Tweak the configuration so that it's listening on

sudo vim /etc/mysql/mariadb.conf.d/50-server.cnf

and copy the bind-address line and adjust so it looks like this - we want MariaDB to be listening on all interfaces, not just localhost (127.0.0.1)...

# Instead of skip-networking the default is now to listen only on # localhost which is more compatible and is not less secure. #bind-address = 127.0.0.1 bind-address = 0.0.0.0

Then restart MariaDB:

sudo service mysql restart

It should now be listening on port 3306 on all interfaces, i.e. 0.0.0.0.

Now set up the database which will hold NextCloud's data. Log into the MySQL client on the host (if you've created a .my.cnf file in your home directory as describe above, you won't need to enter your username and password):

mysql -u root -p

Enter your root password when prompted. It's also a good idea to gin up a password for your "nextcloud" database user. I usually use pwgen (sudo apt-get install pwgen) - for example running this command will give you a single 12 character password without special characters (just numbers and letters):

pwgen -s 12 1 T7KR2osrMkyC

At the prompt (which will look something like MariaDB [(none)]>) enter the following lines (putting your password in place of [passwd]):

CREATE DATABASE nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER "nextcloud"@"%" IDENTIFIED BY "[passwd]"; GRANT ALL ON nextcloud.* to "nextcloud"@"%"; FLUSH PRIVILEGES;

Then enter \q to exit.

NextCloud and Collabora Office with Docker

We make use of the NextCloud community's stable Docker container which they keep up to date. Similarly, the Collabora community has created a reference Docker container.

The over all architecture consists of five Docker containers (note, done properly, you aim to ensure that each container runs only one service!):

the main NextCloud container (running the PHP-FPM service)
an identical container to the PHP one which runs the cron service (which does periodic administrative tasks relevant to NextCloud)
the self-contained Collabora Office container (running PHP with an Apache web server instance and a full instance of LibreOffice running in headless server mode (never fear, no servers were harmed in the building of this server!) - yes this server doesn't really adhere to the "one-service per container" convention, but I'm ok with that. It's just a convention after all.)
a Redis container (which provides performance improving caching for NextCloud), and
an Nginx webserver container which makes it easier to manage the configuration and paths of the NextCloud and Collabora servers via WOPI. It means that on the hosting server, we only need to run a proxying web server, which is easy.

The way I prefer to implement this set of containers is to use Docker Compose (after first setting up Docker support on your server - I'll assume you've followed the complete instructions including setting up Docker for your non-root user). I suggest using the latest installation instructions provided by the Docker community. To be honest, I usually use the alternative instructions, employing the "pip" approach. You can upgrade an existing install by issuing (on your Linux VM's command line):

sudo pip install -U docker-compose

To set up your server, I recommend setting up a place for your Docker containers (replace "me" with your non-root username on the server) and the associated persistent data (your Docker containers should hold no important data - you should be able to delete and recreate them entirely without losing any important data or configuration):

sudo mkdir /home/data
sudo mkdir /home/data/nextcloud
sudo mkdir /home/data/nextcloud/apps sudo mkdir /home/data/nextcloud/config sudo mkdir /home/data/nextcloud/data sudo mkdir /home/data/nextcloud/redis sudo mkdir /home/data/nextcloud/resources sudo mkdir /home/docker sudo mkdir /home/docker/nextcloud-collabora sudo chown -R me:me /home/docker cd /home/docker/nextcloud-collabora

Here's an example of the required docker-compose.yml file (you can create this via a text editor like "nano" which should be pre-installed on any VM these days, or use my preferred, but less intuitive, editor, vim via vim docker-compose.yml in the /home/docker/nextcloud-collabora directory):

version: '2' networks: back:     driver: bridge services: web:     image: nginx     ports:       - 127.0.0.1:8082:80     volumes:       - ./nginx.conf:/etc/nginx/nginx.conf:ro     links:       - app     volumes_from:       - app     environment:       - VIRTUAL_HOST     networks:     - back     restart: unless-stopped     app:     image: nextcloud:12-fpm     links:       - redis     volumes:       - /home/data/nextcloud/apps:/var/www/html/apps       - /home/data/nextcloud/config:/var/www/html/config       - /home/data/nextcloud/resources:/var/www/html/resources       - /home/data/nextcloud/data:/var/www/html/data     networks:     - back     restart: unless-stopped     cron:     image: nextcloud:12-fpm     volumes_from:       - app     user: www-data     entrypoint: |       bash -c 'bash -s <<EOF       trap "break;exit" SIGHUP SIGINT SIGTERM       while /bin/true; do         /usr/local/bin/php /var/www/html/cron.php         sleep 900       done       EOF'     networks:       - back     restart: unless-stopped     redis:     image: redis:alpine     volumes:       - /home/data/nextcloud/redis:/data     networks:       - back     restart: unless-stopped collab:     image: collabora/code     environment:
      # put the domain name you select for your NextCloud instance       # here! Escape any . in your domain name by preceding them with \\       domain: your\\.domain\\.tld       username: admin
      # put your own strong password in here!       password: some-good-password     cap_add:       - MKNOD     networks:       - back     volumes_from:       - app     ports:       - 127.0.0.1:9980:9980     links:       - app     restart: unless-stopped

You'll need to substitute the domain name you pick for your NextCloud instance - Collabora's container requires that you specify it so that it doesn't accept connections from other (potentially nefarious) containers elsewhere on the Internet!

Also note, the "ports" specified above, 8082 for nginx and 9980 for collab are arbitrary - I picked these to ensure they don't conflict with ports being used by other containers on my server - you can use these if you want, or use sudo netstat -punta to see what ports are currently claimed by other services on your server (if there are any) and pick ones that don't clash! If it scroll past too fast, you can pipe it into less to allow you to scroll and search: sudo netstat -punta | less - hit "q" to exit or "/" to initiate a text search.

You will also need to provide the "nginx.conf" file referenced in the nginx section of the file. Do that by using your editor, e.g. vim nginx.conf, and enter this content:

user www-data;

events { worker_connections 768; }

http { upstream backend {
# if you don't call your NextCloud server "app" in your # docker-compose.yml, you'll need to change app below to
# whatever you end up calling it. server app:9000; } include /etc/nginx/mime.types; default_type application/octet-stream;

server { listen 80; # Add headers to serve security related headers add_header X-Content-Type-Options nosniff; add_header X-Frame-Options "SAMEORIGIN"; add_header X-XSS-Protection "1; mode=block"; add_header X-Robots-Tag none; add_header X-Download-Options noopen; add_header X-Permitted-Cross-Domain-Policies none;

root /var/www/html;

location = /robots.txt { allow all; log_not_found off; access_log off; }

location = /.well-known/carddav { return 301 $scheme://$host/remote.php/dav; } location = /.well-known/caldav { return 301 $scheme://$host/remote.php/dav; }

client_max_body_size 1G; fastcgi_buffers 64 4K;

gzip off;

index index.php; error_page 403 /core/templates/403.php; error_page 404 /core/templates/404.php; location / { rewrite ^ /index.php$uri; }

location ~ ^/(?:build|tests|config|lib|3rdparty|templates|data)/ { deny all; } location ~ ^/(?:\.|autotest|occ|issue|indie|db_|console) { deny all; }

location ~ ^/(?:index|remote|public|cron|core/ajax/update|status|ocs/v[12]|updater/.+|ocs-provider/.+|core/templates/40[34])\.php(?:$|/) { include fastcgi_params; fastcgi_split_path_info ^(.+\.php)(/.*)$; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_param PATH_INFO $fastcgi_path_info; fastcgi_param HTTPS on; #Avoid sending the security headers twice fastcgi_param modHeadersAvailable true; fastcgi_param front_controller_active true; fastcgi_pass backend; fastcgi_intercept_errors on; fastcgi_request_buffering off; }

location ~ ^/(?:updater|ocs-provider)(?:$|/) { try_files $uri/ =404; index index.php; }

# Adding the cache control header for js and css files # Make sure it is BELOW the PHP block location ~* \.(?:css|js)$ { try_files $uri /index.php$uri$is_args$args; add_header Cache-Control "public, max-age=7200"; # Add headers to serve security related headers (It is intended to # have those duplicated to the ones above) # Before enabling Strict-Transport-Security headers please read into # this topic first. # add_header Strict-Transport-Security "max-age=15768000; # includeSubDomains; preload;"; add_header X-Content-Type-Options nosniff; add_header X-Frame-Options "SAMEORIGIN"; add_header X-XSS-Protection "1; mode=block"; add_header X-Robots-Tag none; add_header X-Download-Options noopen; add_header X-Permitted-Cross-Domain-Policies none; # Optional: Don't log access to assets access_log off; }

location ~* \.(?:svg|gif|png|html|ttf|woff|ico|jpg|jpeg)$ { try_files $uri /index.php$uri$is_args$args; # Optional: Don't log access to other assets access_log off; } } }

That should be all the configuration you need to make the Docker containers go.

Configuring Nginx to proxy NextCloud and Collabora

The next step is configuring the local nginx proxy servers for NextCloud and Collabora using the nginx instance you installed earlier. That's what responds to the domain name you choose for this service. In our case, the name is https://docs.oeru.org - you can have a look at it to see what you should be seeing when you first start things up! We use Let's Encrypt to provide secure hosting - here're my Let's Encrypt instructions on setting it up. The key thing to realise is that your "certificates" need to exist for Nginx to restart with the new configurations below - use the "commenting out the intervening lines" trick mentioned in my instructions to bootstrap the creation of your secure certificates!

To configure the proxies, you need to create two configuration files in your /etc/nginx/sites-available/ directory.

NextCloud Proxy Configuration

Create a file with a meaningful name for your NextCloud Proxy, perhaps based on the domain name you've chosen (our file for docs.oeru.org is called "docs") using the same editing approach as the last few (although this is in a different directory) for example sudo vim /etc/nginx/sites-available/docs with the following contents, replacing "nextcloud.domain" with your selected domain name (and the port number 8082 if you've opted to change to a different one!):

server { listen 80; server_name nextcloud.domain;

include /etc/nginx/includes/letsencrypt.conf;

# redirect all HTTP traffic to HTTPS. location / { return 302 https://nextcloud.domain$request_uri; } }

# This configuration assumes that there's an nginx container talking to the mautic PHP-fpm container, # and this is a reverse proxy for that Mautic instance. server { listen 443 ssl; server_name nextcloud.domain;

ssl_certificate /etc/letsencrypt/live/nextcloud.domain/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/nextcloud.domain/privkey.pem; ssl_protocols TLSv1 TLSv1.1 TLSv1.2; # to create this, see https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html ssl_dhparam /etc/ssl/certs/dhparam.pem; keepalive_timeout 20s;

include /etc/nginx/includes/letsencrypt.conf; location ^~ / { proxy_pass http://localhost:8082; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; proxy_set_header Host $http_host; proxy_read_timeout 36000s; } client_max_body_size 1G; fastcgi_buffers 64 4K;

add_header X-Frame-Options "SAMEORIGIN"; add_header Strict-Transport-Security "max-age=31536000; includeSubdomains;"; }

Collab Proxy Configuration

Now create a collabora proxy configuration.

Note: This will probably never by used by any user directly (there is a resource analysis service on the collabora system that might be of interest) - instead it'll be referenced by the NextCloud instance transparently to your users.

In our case, we chose the domain collab.oeru.org and the file is called "collab", created via sudo vim /etc/nginx/sites-available/collab and containing (replace collab.domain with the one you've selected - similarly replace the port number 9980 with whatever you've selected if you've opted for a different one!):

server { listen 80; server_name collab.domain;

# for let's encrypt renewals! include /etc/nginx/includes/letsencrypt.conf;

# redirect all HTTP traffic to HTTPS. location / { return 302 https://collab.domain$request_uri; } }

server { listen 443 ssl; server_name collab.domain;

ssl_certificate /etc/letsencrypt/live/collab.domain/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/collab.domain/privkey.pem; ssl_protocols TLSv1 TLSv1.1 TLSv1.2; # to create this, see https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html ssl_dhparam /etc/ssl/certs/dhparam.pem; keepalive_timeout 20s;

# for let's encrypt renewals! include /etc/nginx/includes/letsencrypt.conf;

proxy_http_version 1.1; proxy_buffering off;

# static files location ^~ /loleaflet { proxy_pass https://localhost:9980; proxy_set_header Host $http_host; }

# WOPI discovery URL location ^~ /hosting/discovery { proxy_pass https://localhost:9980; proxy_set_header Host $http_host; }

# download, presentation and image upload location ^~ /lool { proxy_pass https://localhost:9980; proxy_set_header Upgrade $http_upgrade; proxy_set_header Conection "upgrade"; proxy_set_header Host $http_host; } }

Once those are created, you have to make sure that they're "enabled" (replacing with your file names, of course):

sudo cd /etc/nginx/sites-enabled sudo ln -sf ../sites-available/docs . sudo ln -sf ../sites-available/collab .

To confirm that there aren't any typos or issues that might make nginx unhappy, run

sudo nginx -t

If all's well, get nginx to reread its configuration with the new files:

sudo service nginx reload

Firing it all up!

Phew - congratulations on getting here! We've reached the moment of truth where we need to see if this whole thing will work!

We need to make sure we're back in the Docker directory we set up:

cd /home/docker/nextcloud-collabora

and then we need to try running our docker-compose script to "pull" in the pre-built Docker containers we've specified in our docker-compose.yml file:

docker-compose pull

All going well, after a few minutes (longer or shorter depending on the speed of your server's connection) you should have download the Nginx, Redis, NextCloud and Collabora-CODE Docker images. Then you can run:

docker-compose up -d && docker-compose logs -f

This will attempt to start up the containers (bringing them "up" in daemon mode, thus the -d) and then show you a stream of log messages from the containers, preceded by the container name. This should help you debug any problems that occur during the process (ideally, none).

Setting up the database

On doing so, if all is well, you should be directed through the database set up process for your NextCloud instance. Your details should be:

database IP: 172.17.0.1 - this is the default IP of the Docker host server.
database name: nextcloud
database user: nextcloud
database password: (the one you came up with above)

Setting the Admin user

Once that's set and working, NextCloud will install all the relevant database tables and initial data. You'll be asked to set up an admin user account, which can be "admin" (you could make it something different to help stymie nefarious probes that assume you've got a user called "admin" - but don't forget what you've called it!) and some strong password you create (you can use the pwgen utility you used earlier) - I'd recommend recording it somewhere. I would not recommend making your own account, in your name, the main admin account. I recommend creating a second account, with administrator privileges for yourself, but leave the admin account purely for administrative activities.

Configuring Outgoing Email

To allow your NextCloud instance to send outgoing email, so that your site can alert you to security updates that need to be applied, or so that users can request a replacement password if they've forgot theirs, you'll need an authenticating SMTP account somewhere. Most of you already have one. You'll probably want to set up a dedicated email address for this server somewhere, perhaps something like "nextcloud@your.domain" or similar, with a username (often just the email address) and a password. You'll need the following details:

SMTP server : an IP address or a domain name
SMTP username: a username or an email address
SMTP password: a strong password already configured for the username on that server
SMTP login security: whether login is via TLS, SSL, or unsecure (!!), and
SMTP login method: plain, encrypted, "login" or some other value.

You should be able to test your email settings to make sure the details you've entered are valid. If you need to adjust these settings later, you can go to the admin menu (top right of the web browser interface) and go to Admin->Additional Settings - should have a path of https://your.domain/settings/admin/additional

Configuring Collabora Office Integration

Once you're logged in as your own user, looking at your own default folders, you can start having a look around. You should have an "admin" menu (assuming you've created your user with Administrator privileges) at the top right of the web interface. If you go to Apps, you can use the search box to search for "Collabora" or go to the "Office & text" App category. You'll need to "enable" the Collabora Online "official" app, at which point it will download the latest version of the connector app and install it (it should appear in your /home/data/nextcloud/apps directory)

Once you've done that, go to your top right menu again, selecting Admin, and you should see "Collabora Online" as an option in the left column (which starts with "Basic settings"). Selecting that, you'll need to enter "https://collab.domain" (replacing with your domain, of course). I don't have any of the other options ticked.

If it works, you should have the ability to go back to the home of your NextCloud install, which should show you your top-level folders. If you click the "+" next to the home icon (top left of the folder pane) you should now have the option to create (in addition to "Upload file", "New folder", "New text file") a "New Document", "New Spreadsheet", and "New Presentation". Clicking those should give you the Collabora Office interface for the designated content type.

Similarly, you can use the "Upload file" to upload a document in a format that is supported by Collabora Office, once uploaded clicking on the filename should open it for editing in the appropriate Collabora Office interface.

It is saved as it is change, you shouldn't need to save it explicitly.

Upgrading it

So, as you're no doubt aware, both NextCloud and Collabora Office are always being improved and updated. I certainly encourage you to keep your installation up-to-date.

While you'll periodically see that NextCloud apps have available updates (these can be upgraded through the browser interface) updates to the NextCloud and Collabora Office systems themselves need to be undertaken by upgrading the containers. Luckily it's easy to do (although I strongly urge you to ensure you have a very recent backup of both database and uploaded files - they're the files in /home/data/nextcloud/data:

Updating the container should be as easy as either doing another

docker pull oeru/mautic

and then shutting down Docker container via a

docker-compose stop

removing the old containers (this won't remove any data you want to save if you followed the directions above! But remember to do it in the right directory!) via

docker-compose rm -v

and then restarting it via

docker-compose up -d

Use docker-compose logs -f to watch the logs - you'll likely see debugging information in the unlikely event that something goes wrong in the upgrade process.

Backing it up

To back up your instance on your server, you need two things: a file system backup of your /home/data/nextcloud directory, and database dumps of your database.

There're lots of ways to back up your files (I personally use a bash script that I wrote in a past role, which uses rdiff-backup to create versioned backups either locally or on a remote server, although there're other documented approaches - leave a comment below if you'd like to learn more about my approach!).

Backing up your database is as easy installing automysqlbackups:

sudo apt install automysqlbackups

You'll find daily versioned dumps of your MariaDB database(s) in /var/lib/automysqlbackups. To run an ad hoc backup (which will replace the previous backup from that day, if there is one) just run

sudo automysqlbackups

Collabora Admin Console

Once you've got everything set up, you can access the admin console of the Collabora Office instance at the collab.domain you specified above - it'll have the path https://collab.domain/loleaflet/dist/admin/admin.html (of course replacing collab.domain with your domain) which gives you useful info about the system resources being used, number of documents being edited and by whom, and some other interesting details. I've included a screen shot.

When prompted for login details, use the collab username - "admin" if you used the default I provided, and the password you set in your docker-compose.yml file above.

Blog comments

All I get after all of that…

Tim (not verified) Sat 06/11/2021 - 04:21

All I get after all of that is "OK"

Sorry Tim, after all what?

dave Sat 06/11/2021 - 08:18

Sorry Tim, after all what? I'd love to provide assistance, but need you to be a bit more specific.

Add new comment

Installing Mastodon with Docker-Compose on Ubuntu 16.04

dave — Fri, 02 Jun 2017 03:02:31 +0000

Installing Mastodon with Docker-Compose on Ubuntu 16.04

Blog tags

mastodon

ubuntu linux

16.04

nginx

let's encrypt

ruby on rails

docker

docker compose

dave Fri 02/06/2017 - 15:02

Not long ago, Mastodon, an open source, federated alternative to the proprietary network-effect wunderkind, Twitter, came out of no where. Actually, it came out of an insane amount of work done by free and open source powerhouse Eugen Rochko aka Gargron and a small elite developer community, and many predecessors who are part of the GNU Social Fediverse (kudos to Danyl Strype for compiling that excellent history).

Mastodon, unlike Twitter, is entirely community driven - there are no ads, there are no privacy threats, there are no corporate Terms and Conditions to blindly "I Accept". And your Mastodon "persona" can be on a server you control (or that is controlled by someone you trust). Despite being distributed, you're still part of a global network, but one made resilient by its federated, decoupled nature.

Instead of "Tweeting" in 140 characters like on Twitter, your "Toots" are limited to 500 characters (a lot more information can usefully be passed). You can follow people (and they you) by learning their handle - which looks like an email. I've got a couple Mastodon accounts, but my main one right now is lightweight@mastodon.social (I set it up quite a while back, before I set up my first couple Mastodon servers). Actually, Mastodon's biggest problem (in my opinion) right now is that you can't easily migrate your "main" persona from one server to another without losing a lot of its value (historical toots, followers, those you follow, etc.). You can migrate some things, like those you're following, and any users you've "blocked" but it's still fairly rudimentary.

Mastodon includes a nice web interface which will look somewhat familiar to anyone who's used Twitter's "Tweetdeck" web application. Similarly, the GNU Social community has rallied to provide at least 2 separate open source mobile apps (I run Tusky on my LineageOS powered phone at the moment) - I think there're some for iOS, too, although Apple's not as amenable to open source apps.

There's a useful Mastodon FAQ.

Running with the Mastodon Herd

The way I implement a complex Ruby on Rails app like Mastodon is to do as much as possible to keep it at arms length (and stop it from getting anything gooey on my virtual machine). To achieve that comforting isolation, I employ Docker Compose on Ubuntu Linux 16.04. See our Docker Compose article on how to install it (and its dependencies, like Docker itself).

Once you've got Docker Compose running, you can do what I did.

A couple notes:

I have an unprivileged user on my server, "ubuntu". You can use any unprivileged users - I'd encourage you to use sudo rather than login as root.
I use "vim" as my terminal-based text editor below. I think it's a great tool, but it does have a learning curve. If you're daunted (no shame in that), I recommend using "nano" instead - it'll probably installed on most Ubuntu 16.04 instances. If someone suggests you use "emacs" instead, they're jerkin' yer chain (I used emacs for over a decade, I know what I'm talking about).
make sure you have the "git" VCS system installed... sudo apt install git should do it.
you'll need nginx installed, too... sudo apt install nginx-full will do that for you.

After logging into my server (via SSH remotely) as the ubuntu user (you might have different non-privileged user name, that's ok), I did the following (to avoid permissions problems later on, we'll create a "mastodon" group and user with the id 991, used by the Mastodon app by default, on the hosting platform):

groupadd -g 991 mastodon useradd -u 991 -g 991 -c "Mastodon User" -s /usr/bin/nologin -d /home/data/mastodon mastodon
sudo mkdir -p /home/docker /home/data/mastodon sudo chown -R ubuntu:ubuntu /home/docker sudo chown -R mastodon:mastodon /home/data/mastodon
cd /home/docker git clone https://github.com/tootsuite/mastodon.git docker-mastodon cd docker-mastodon

What you then need to do is ensure you're using the current "tagged" release (it'll make your life easiest). You can find out what tags are available:

git tag -l

At present, the latest tag is "v1.4.7" - to use it do this:

git checkout tags/v1.4.7

Obviously, replace this with the most recent tag (note, you might have to look through the whole list to find it!). Then you're using the specific collection of files corresponding to the v1.4.7 tagged release. We can carry on...

cp .env.production.sample .env.production vim .env.production

Edit this file to look like the .env.production sample below, but replacing the [tokens] with your values. Then run this:

vim docker-compose.yml

Edit this file to look like docker-compose.yml below.

docker-compose run --rm web rake secret

Run this last command 3 times - to get 3 secrets - long random strings - for .env.production! Copy and paste your 3 secrets into your .env.production file with your preferred editor as shown below.

docker-compose build docker-compose up

That should download the required Docker images (might take quite a while depending on how fast your server's network connection is) and result in starting 5 different Docker containers, and you'll be able to watch them put out status (and error) messages as they boot and find their various dependencies. If there're no obvious errors, you can hit CTRL-C to shut them down again and restart them in a mode that keeps them running after you log out

docker-compose up -d

Note, you can always stop the containers by running docker-compose stop in that directory. You can check their status by running

docker ps

which should show you something like this:

CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES c6be9f3eef1e gargron/mastodon "bundle exec rails s " 13 days ago Up 13 days 127.0.0.1:3000->3000/tcp, 4000/tcp dockermastodon_web_1 6a123d9b1843 gargron/mastodon "bundle exec sidekiq " 13 days ago Up 13 days 3000/tcp, 4000/tcp dockermastodon_sidekiq_1 f06c4a9bc479 gargron/mastodon "npm run start" 13 days ago Up 13 days 3000/tcp, 127.0.0.1:4000->4000/tcp dockermastodon_streaming_1 6dbfad0669f8 postgres:alpine "docker-entrypoint.sh" 2 weeks ago Up 13 days 5432/tcp dockermastodon_postgres_1 8026b79e976d redis:alpine "docker-entrypoint.sh" 4 weeks ago Up 13 days 6379/tcp dockermastodon_redis_1

You can use the 12 digit IDs to run other Docker commands, like docker inspect [ID] or docker exec -it [ID] bash to log into the container itself and get a bash prompt. After all that's running, you can do some final housekeeping:

docker-compose run --rm web rails db:migrate docker-compose run --rm web rails assets:precompile sudo vim /etc/nginx/sites-available/mastodon

Edit this to look like the mastodon nginx config file below.

sudo cd /etc/nginx/sites-enabled sudo ln -sf ../sites-available/mastodon .

to enable the new configuration...

sudo nginx -t

To check for typos in you file. If you get no errors, you can restart nginx:

sudo service nginx restart

When that's done, to [your domain] in your browser, which should take you to https://[your domain] and create a new user. If your email is set up properly, you'll get an email confirmation, and this will allow you to log in. If that works, I'd encourage you to modify your configuration to use a Let's Encrypt SSL certificate to protect your users' (and your server's) security. We provide this dedicated howto! The .env.production template below assumes you've done this, so if your Mastodon isn't working, that might be why (you can try turning LOCAL_HTTPS=false temporarily if that's helpful).

You will want to create an admin user - create the user first through the web interface, and then on the command line run (replacing [admin username] with the username you set up:

cd /home/docker/docker-mastodon docker-compose run --rm web rails mastodon:make_admin USERNAME=[admin username]

Then go to that user's Mastodon preferences and define the relevant info for your instance (see the administration options).

Debugging

If you run in to problems, a very useful Docker Compose option to use (from within the docker-mastodon directory) is

docker-compose logs -f

It will provide you with the automatically updating integrated logs of all the containers you've unleashed!

Sample .env.production

Here's a sample with (hopefully obviously named) [placeholders]

# Service dependencies REDIS_HOST=redis REDIS_PORT=6379 DB_HOST=postgres DB_USER=postgres DB_NAME=postgres DB_PASS= DB_PORT=5432

# Federation LOCAL_DOMAIN=[your domain] LOCAL_HTTPS=true

# Application secrets # Generate each with the `rake secret` task (`docker-compose run --rm web rake secret` if you use docker compose) PAPERCLIP_SECRET=[first secret] SECRET_KEY_BASE=[second secret] OTP_SECRET=[third secret]

# Registrations # Single user mode will disable registrations and redirect frontpage to the first profile # SINGLE_USER_MODE=true # Prevent registrations with following e-mail domains # EMAIL_DOMAIN_BLACKLIST=example1.com|example2.de|etc

# E-mail configuration SMTP_SERVER=[smtp server domain name] SMTP_PORT=587 SMTP_LOGIN=[smtp user name] SMTP_PASSWORD=[smtp user password] SMTP_FROM_ADDRESS=[sender address for outgoing mastodon emails] SMTP_DOMAIN=[your site's base domain] SMTP_OPENSSL_VERIFY_MODE=none

# Optional asset host for multi-server setups # CDN_HOST=assets.example.com

# S3 (optional) # S3_ENABLED=true # S3_BUCKET= # AWS_ACCESS_KEY_ID= # AWS_SECRET_ACCESS_KEY= # S3_REGION= # S3_PROTOCOL=http # S3_HOSTNAME=192.168.1.123:9000

# Optional alias for S3 if you want to use Cloudfront or Cloudflare in front # S3_CLOUDFRONT_HOST=

# Streaming API integration # STREAMING_API_BASE_URL=

Sample docker-compose.yml

Here's a sample with [placeholders]. Note - this generates five Docker containers. Yeah, like I said, this is a serious, complex app.

version: '2' services: postgres:     restart: unless-stopped     image: postgres:alpine     volumes:      - /home/data/mastodon/postgres:/var/lib/postgresql/data redis:     restart: unless-stopped     image: redis:alpine     volumes:      - /home/data/mastodon/redis:/data web:     restart: unless-stopped     build: .     image: gargron/mastodon     env_file: .env.production     command: bundle exec rails s -p 3000 -b '0.0.0.0'     ports:       - "127.0.0.1:3000:3000"     depends_on:       - postgres       - redis     volumes:       - /home/data/mastodon/packs:/mastodon/public/packs
      - /home/data/mastodon/assets:/mastodon/public/assets
      - /home/data/mastodon/system:/mastodon/public/system streaming:     restart: unless-stopped     build: .     image: gargron/mastodon     env_file: .env.production     command: npm run start     ports:       - "127.0.0.1:4000:4000"     depends_on:       - postgres       - redis sidekiq:     restart: unless-stopped     build: .     image: gargron/mastodon     env_file: .env.production     command: bundle exec sidekiq -q default -q mailers -q pull -q push     depends_on:       - postgres       - redis     volumes:       - /home/data/mastodon/system:/mastodon/public/system

Sample nginx mastodon config file

Here's a copy of the nginx configuration file I use (with [placeholders], obviously) - it's the result of quite a lot of tweaking. Have fun!

map $http_upgrade $connection_upgrade { default upgrade; '' close; }

server { listen 80; # listen [::]:80; server_name [your domain]; root /var/www/html;

# for let's encrypt renewals! location /.well-known/acme-challenge/ { default_type text/plain; root /var/www/html; }

# redirect all HTTP traffic to HTTPS. location / { return 302 https://[your domain]$request_uri; } }

server { listen 443 ssl; # listen [::]:443 ssl; server_name [your domain];

ssl_certificate /etc/letsencrypt/live/[your domain]/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/[your domain]/privkey.pem; ssl_protocols TLSv1 TLSv1.1 TLSv1.2; # from https://0x39b.fr/post/nginx_security/ ssl_session_timeout 1d; ssl_session_cache shared:SSL:50m; #ssl_session_tickets off; ssl_prefer_server_ciphers on; ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256'; # OCSP Stapling --- # fetch OCSP records from URL in ssl_certificate and cache them ssl_stapling on; ssl_stapling_verify on; # to create this, see https://raymii.org/s/tutorials/Strong_SSL_Security_On_nginx.html ssl_dhparam /etc/ssl/certs/dhparam.pem;

# for let's encrypt renewals! location /.well-known/acme-challenge/ { default_type text/plain; root /var/www/html; }

keepalive_timeout 70; sendfile on; client_max_body_size 0; # update from https://github.com/tootsuite/documentation/blob/master/Running-Mastodon/Production-guide.md gzip on; gzip_vary on; gzip_proxied any; gzip_comp_level 6; gzip_buffers 16 8k; gzip_http_version 1.1; gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";

location / { try_files $uri @proxy; }

location ~ ^/(packs|system/media_attachments/files|system/accounts/avatars) { add_header Cache-Control "public, max-age=31536000, immutable"; try_files $uri @proxy; }

    location @proxy {         proxy_set_header Host $host;         proxy_set_header X-Real-IP $remote_addr;         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;         proxy_set_header X-Forwarded-Proto https;
        proxy_set_header Proxy "";
        proxy_pass_header Server;         proxy_pass http://localhost:3000;         proxy_buffering off;         proxy_redirect off;         proxy_http_version 1.1;         proxy_set_header Upgrade $http_upgrade;         proxy_set_header Connection $connection_upgrade;         tcp_nodelay on;     }

location /api/v1/streaming { proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto https; proxy_set_header Proxy ""; proxy_pass http://localhost:4000; proxy_buffering off; proxy_redirect off; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; tcp_nodelay on; }

error_page 500 501 502 503 504 /500.html; # this should give you an A+ rating on https://instances.mastodon.xyz/ add_header X-XSS-Protection "1; mode=block"; add_header Content-Security-Policy "default-src 'none'; font-src 'self'; media-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self'; img-src 'self' data: blob:; connect-src 'self' wss://[your domain]"; }

Enjoy!

Keeping Mastodon up to date

To ensure your Mastodon doesn't become a run down abandoned trailerpark node bit rotting quietly in the ether, I recommend you keep it up to date! There is a useful Mastodon Administrator's guide for Docker instances that I consult every time I want to update. Note, if the "git stash" part of it is too hard, I recommend that any time you change your docker-compose.yml file, you copy it to

cp docker-compose.yml docker-compose.yml-backup

That way, you can simply remove docker-compose.yml (double check your docker-compose.yml-backup is up-to-date first!), do the git checkout TAG_NAME, and then

cp docker-compose.yml-backup docker-compose.yml

and you're done. Welcome the Fediverse!

Add new comment

Many simple tools, loosely coupled

dave — Mon, 08 May 2017 03:10:35 +0000

Many simple tools, loosely coupled

Blog tags

philosophy

unix

ubuntu linux

docker

let's encrypt

dave Mon 08/05/2017 - 15:10

Our approach to technology here at the OERu is inspired by the UNIX tool philosophy which can be summarised as follows:

"create simple tools that do one job well, and make it easy to combine them to work together"

In the UNIX (and, somewhat more recently, the Linux) computing environment, this originally meant a lot of small commandline applications like "ls" for listing the contents of file directories, and "grep" for searching directories of files for words and other snippets of content, and "diff" for showing the difference between two files, and many many more. These all output text, and they also accept text as an input - you can chain all of these simple little applications together to create, on the fly, remarkably complex capabilities. This is one of the things that makes Linux and the commandline so powerful for those who have learned its lore (and so intimidating for those who haven't yet done so).

This idea of "loosely coupled" tools, working together is also a good way to describe both the OERu technology and documentation philosophy.

On this website, the way it manifests is interesting - each time I write a howto article, there're certain common tasks - things like setting up Docker, or creating secure SSL certificates for encrypting user interactions with a web service.

Initially, I wrote howtos with all of those details contained in one document, however the instructions fairly quickly become outdated, for example, the install process for Docker or Let's Encrypt is changed by its community (usually to make it faster and more convenient) or to reflect the release of new software dependencies. It doesn't sit well with me to be leaving outdated or inaccurate resources on the web - I feel a responsibility for curating them to improve the signal-to-noise ratio of the 'net. Also, it rapidly becomes an intractable problem to go through old howtos to update all the slight variations on the same instructions to something new (the problem grows exponentially as more howtos are added).

So, taking the UNIX approach, I use my experience writing a few howtos to provide insight into parts of each that are repeated. Any section repeated (more or less unchanged) in each howto is a candidate for replacement with a stand-alone howto.

As it turns out, the community that's building the Docker container technology has done a good job of keeping their installation documentation up-to-date and making it easy to find the relevant info for our target platforms, Ubuntu Linux 14.04 and 16.04. As a result, there's no point in my repeating their instructions. Instead, I just point my readers there when it's time to install Docker.

My first candidate for documentation "refactoring" was the "Let's Encrypt" SSL Certificate process (it's a feature of almost all my howtos to date). Having now created that stand-alone howto, I can replace the largely repeated sections of several howtos with a single link to the same place.

Yes, this change adds the overhead of the reader of a howto needing to go to a different article on this site, but I think this is greatly outweighed by the benefits: if I need to update or improve the description of this operation, I can simply update one document and ensure it's got the "best of" tips across all the different howtos. Also, if people leave questions or comments, all relevant ones will be in the same place, making it easier for other site visitors to find them.