MyShaarli/doc/md/guides/install-shaarli-with-debian9-and-docker.md

Last updated on 2018-07-01.

Goals

• Getting a Virtual Private Server (VPS)
• Running Shaarli:
  • as a Docker container,
  • using the Træfik reverse proxy,
  • securized with TLS certificates from Let's Encrypt.

The following components and tools will be used:

• Debian, a GNU/Linux distribution widely used in server environments;
• Docker, an open platform for developing, shipping, and running applications;
• Docker Compose, a tool for defining and running multi-container Docker applications.

More information can be found in the Resources section at the bottom of the guide.

Getting a Virtual Private Server

For this guide, I went for the smallest VPS available from DigitalOcean, a Droplet with 1 CPU, 1 GiB RAM and 25 GiB SSD storage, which costs $5/month ($0.007/hour):

• Droplets Overview
• Pricing
• How to Create a Droplet from the DigitalOcean Control Panel
• How to Add SSH Keys to Droplets
• Initial Server Setup with Debian 8 (also applies to Debian 9)
• An Introduction to Securing your Linux VPS

Creating a Droplet

Select Debian 9 as the Droplet distribution:

Choose a region that is geographically close to you:

Choose a Droplet size that corresponds to your usage and budget:

Finalize the Droplet creation:

Droplet information is displayed on the Control Panel:

Once your VPS has been created, you will receive an e-mail with connection instructions.

Obtaining a domain name

After creating your VPS, it will be reachable using its IP address; some hosting providers also create a DNS record, e.g. ns4853142.ip-01-47-127.eu.

A domain name (DNS record) is required to obtain a certificate and setup HTTPS (HTTP with TLS encryption).

Domain names can be obtained from registrars through hosting providers such as Gandi.

Once you have your own domain, you need to create a new DNS record that points to your VPS' IP address:

Host setup

Now's the time to connect to your freshly created VPS!

$ ssh root@188.166.85.8

Linux stretch-shaarli-02 4.9.0-6-amd64 #1 SMP Debian 4.9.88-1+deb9u1 (2018-05-07) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Sun Jul  1 11:20:18 2018 from <REDACTED>

root@stretch-shaarli-02:~$

Updating the system

root@stretch-shaarli-02:~$ apt update && apt upgrade -y

Setting up Docker

The following instructions are from the Get Docker CE for Debian guide.

Install package dependencies:

root@stretch-shaarli-02:~$ apt install -y apt-transport-https ca-certificates curl gnupg2 software-properties-common

Add Docker's package repository GPG key:

root@stretch-shaarli-02:~$ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -

Add Docker's package repository:

root@stretch-shaarli-02:~$ add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian stretch stable"

Update package lists and install Docker:

root@stretch-shaarli-02:~$ apt update && apt install -y docker-ce

Verify Docker is properly configured by running the hello-world image:

root@stretch-shaarli-02:~$ docker run hello-world

Setting up Docker Compose

The following instructions are from the Install Docker Compose guide.

Download the current version from the release page:

root@stretch-shaarli-02:~$ curl -L https://github.com/docker/compose/releases/download/1.21.2/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose
root@stretch-shaarli-02:~$ chmod +x /usr/local/bin/docker-compose

Running Shaarli

Shaarli comes with a configuration file for Docker Compose, that will setup:

• a local Docker network
• a Docker volume to store Shaarli data
• a Docker volume to store Træfik TLS configuration and certificates
• a Shaarli instance
• a Træfik instance

Træfik is a modern HTTP reverse proxy, with native support for Docker and Let's Encrypt.

Compose configuration

Create a new directory to store the configuration:

root@stretch-shaarli-02:~$ mkdir shaarli && cd shaarli
root@stretch-shaarli-02:~/shaarli$

Download the current version of Shaarli's docker-compose.yml:

root@stretch-shaarli-02:~/shaarli$ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/master/docker-compose.yml -o docker-compose.yml

Create the .env file and fill in your VPS and domain information (replace <MY_SHAARLI_DOMAIN> and <MY_CONTACT_EMAIL> with your actual information):

root@stretch-shaarli-02:~/shaarli$ vim .env

SHAARLI_VIRTUAL_HOST=<MY_SHAARLI_DOMAIN>
SHAARLI_LETSENCRYPT_EMAIL=<MY_CONTACT_EMAIL>

Pull the Docker images

root@stretch-shaarli-02:~/shaarli$ docker-compose pull
Pulling shaarli ... done
Pulling traefik ... done

Run!

root@stretch-shaarli-02:~/shaarli$ docker-compose up -d
Creating network "shaarli_http-proxy" with the default driver
Creating volume "shaarli_traefik-acme" with default driver
Creating volume "shaarli_shaarli-data" with default driver
Creating shaarli_shaarli_1 ... done
Creating shaarli_traefik_1 ... done

Conclusion

Congratulations! Your Shaarli instance should be up and running, and available at https://<MY_SHAARLI_DOMAIN>.

Resources

Related Shaarli documentation

• Docker 101
• Shaarli images

Hosting providers

• DigitalOcean
• Gandi
• OVH
• RackSpace
• etc.

Domain Names and Registrars

• Introduction to the Domain Name System (DNS)
• ICANN
• Domain name registrar
• OVH Domain Registration
• Gandi Domain Registration

HTTPS and Security

• Transport Layer Security
• Let's Encrypt

Docker

• Docker Overview
• Docker Documentation
• Get Docker CE for Debian
• docker logs
• Volumes
• Install Docker Compose
• docker-compose logs

Træfik

• Getting Started
• Docker backend
• Let's Encrypt and Docker
• traefik Docker image