Browse files

Docs: Add an installation guide for Debian 9 + Docker

Signed-off-by: VirtualTam <>
  • Loading branch information...
virtualtam committed Jul 1, 2018
1 parent 1cafacf commit a0c34a49765ecc2559ac51b62966b9785ff3a5a3
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
@@ -0,0 +1,257 @@
_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](#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:
<img src="../images/01-create-droplet-distro.jpg"
alt="Droplet distribution" />
Choose a region that is geographically close to you:
<img src="../images/02-create-droplet-region.jpg"
alt="Droplet region" />
Choose a Droplet size that corresponds to your usage and budget:
<img src="../images/03-create-droplet-size.jpg"
alt="Droplet size" />
Finalize the Droplet creation:
<img src="../images/04-finalize.jpg"
alt="Droplet finalization" />
Droplet information is displayed on the Control Panel:
<img src="../images/05-droplet.jpg"
alt="Droplet summary" />
Once your VPS has been created, you will receive an e-mail with connection
## 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. ``.
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
Once you have your own domain, you need to create a new DNS record that points
to your VPS' IP address:
<img src="../images/06-domain.jpg"
alt="Domain configuration" />
## Host setup
Now's the time to connect to your freshly created VPS!
$ ssh root@
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>
### 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](
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 | sudo apt-key add -
Add Docker's package repository:
root@stretch-shaarli-02:~$ add-apt-repository "deb [arch=amd64] 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](
Download the current version from the release page:
root@stretch-shaarli-02:~$ curl -L$(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
Download the current version of Shaarli's `docker-compose.yml`:
root@stretch-shaarli-02:~/shaarli$ curl -L -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
### 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>`.
<img src="../images/07-installation.jpg"
alt="Shaarli installation page" />
## Resources
### Related Shaarli documentation
- [Docker 101](../docker/
- [Shaarli images](../docker/
### 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
@@ -1,8 +1,13 @@
# Shaarli - Docker Compose script
# Shaarli - Docker Compose example configuration
# See:
# -
# -
# Environment variables:
# - SHAARLI_VIRTUAL_HOST Fully Qualified Domain Name for the Shaarli instance
# - SHAARLI_LETSENCRYPT_EMAIL Contact email for certificate renewal
version: '3'
@@ -28,6 +28,7 @@ pages:
- Community & Related software: Community-&
- Guides:
- Install Shaarli on Debian 9 with Docker: guides/
- Backup, restore, import and export: guides/
- Various hacks: guides/
- Development:

0 comments on commit a0c34a4

Please sign in to comment.