Hosting your own Scratchpad

You can very easily host a Scratchpad on your own server using our in-built Docker configuration.

This system architecture has been used to successfully run https://bio.acousti.ca, our most resource-intensive site, for many years.

If you need any help or support hosting your own Scratchpad, please raise a ticket on our issue queue https://github.com/NaturalHistoryMuseum/scratchpads2/issues

Finding a server

To host your own Scratchpad, you need access to a Linux Server (we prefer the Ubuntu distro) with admin permission so you can install packages.

There are plenty of companies providing this service - just search for Ubuntu Virtual Private Server. Or your institution might be able to provide a VPS for you.

Once you have a server, SSH in, and we’ll start installing the packages you need to run your Scratchpad.

Installing Docker

These instructions are based on https://docs.docker.com/engine/install/ubuntu/

1. Set up the repository

1.1 Update the apt package index and install packages to allow apt to use a repository over HTTPS:

sudo apt-get update
sudo apt-get install ca-certificates curl gnupg

1.2 Add Docker’s official GPG key:

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

1.3 Set up the repository

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

2. Install Docker

2.1 Update the apt package index:

sudo apt-get update

2.2 Install Docker Engine, containerd, and Docker Compose:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3. Install Scratchpads

3.1 Clone Scratchpads

git clone https://github.com/NaturalHistoryMuseum/scratchpads2.git /var/lib/scratchpads2

3.2 Update environment variables

cp /var/lib/scratchpads2/.env.template /var/lib/scratchpads2/.env

You must update the SQL default settings in the .env file (if you are recreating your site from an existing Scratchpads site, the settings.php will have sensible values to use).

MYSQL_ROOT_PASSWORD=root
MYSQL_DATABASE=drupal
MYSQL_USER=drupal
MYSQL_PASSWORD=drupal

3.3 Run docker images

cd /var/lib/scratchpads2
make up

4. Recreate from backup

If you want to recreate your hosted Scratchpad, first download the backup file following these instructions Create backup.

make site-from-archive archive=/path/to/backup/backup.myspecies.info-20230404.194808.tar.gz

5. Daemonize

To keep serving the site once you log-off from the server, you must daemonize the process.

make down
docker compose -f docker-compose.yml -f docker-compose.production.yml up -d

6. Set up cron

Scratchpads has tasks that run at intervals in the background (indexing for the site search, for example). To enable this, you must add a cron task.

crontab -e

And enter the text before saving the file.

0 3 * * * docker exec scratchpads.apache drush core-cron > /var/log/docker.cron.log 2>&1

You can also run Scratchpads without Docker, installing your own versions of PHP, MySQL, Apache and SOLR. It’s much more complex, but these instructions will help - https://www.digitalocean.com/community/tutorials/how-to-install-linux-apache-mysql-php-lamp-stack-ubuntu-18-04