diff --git a/doc/md/guides/images/01-create-droplet-distro.jpg b/doc/md/guides/images/01-create-droplet-distro.jpg new file mode 100644 index 00000000..63682ba8 Binary files /dev/null and b/doc/md/guides/images/01-create-droplet-distro.jpg differ diff --git a/doc/md/guides/images/02-create-droplet-region.jpg b/doc/md/guides/images/02-create-droplet-region.jpg new file mode 100644 index 00000000..135a78be Binary files /dev/null and b/doc/md/guides/images/02-create-droplet-region.jpg differ diff --git a/doc/md/guides/images/03-create-droplet-size.jpg b/doc/md/guides/images/03-create-droplet-size.jpg new file mode 100644 index 00000000..aa5b2fd2 Binary files /dev/null and b/doc/md/guides/images/03-create-droplet-size.jpg differ diff --git a/doc/md/guides/images/04-finalize.jpg b/doc/md/guides/images/04-finalize.jpg new file mode 100644 index 00000000..68ec0dc5 Binary files /dev/null and b/doc/md/guides/images/04-finalize.jpg differ diff --git a/doc/md/guides/images/05-droplet.jpg b/doc/md/guides/images/05-droplet.jpg new file mode 100644 index 00000000..44e93a1e Binary files /dev/null and b/doc/md/guides/images/05-droplet.jpg differ diff --git a/doc/md/guides/images/06-domain.jpg b/doc/md/guides/images/06-domain.jpg new file mode 100644 index 00000000..5827dd93 Binary files /dev/null and b/doc/md/guides/images/06-domain.jpg differ diff --git a/doc/md/guides/images/07-installation.jpg b/doc/md/guides/images/07-installation.jpg new file mode 100644 index 00000000..42cc9f10 Binary files /dev/null and b/doc/md/guides/images/07-installation.jpg differ diff --git a/doc/md/guides/install-shaarli-with-debian9-and-docker.md b/doc/md/guides/install-shaarli-with-debian9-and-docker.md new file mode 100644 index 00000000..f1b26d47 --- /dev/null +++ b/doc/md/guides/install-shaarli-with-debian9-and-docker.md @@ -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](https://www.debian.org/), a GNU/Linux distribution widely used in + server environments; +- [Docker](https://docs.docker.com/engine/docker-overview/), an open platform + for developing, shipping, and running applications; +- [Docker Compose](https://docs.docker.com/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](https://www.digitalocean.com/docs/droplets/overview/) +- [Pricing](https://www.digitalocean.com/pricing/) +- [How to Create a Droplet from the DigitalOcean Control Panel](https://www.digitalocean.com/docs/droplets/how-to/create/) +- [How to Add SSH Keys to Droplets](https://www.digitalocean.com/docs/droplets/how-to/add-ssh-keys/) +- [Initial Server Setup with Debian 8](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-debian-8) (also applies to Debian 9) +- [An Introduction to Securing your Linux VPS](https://www.digitalocean.com/community/tutorials/an-introduction-to-securing-your-linux-vps) + +### Creating a Droplet +Select `Debian 9` as the Droplet distribution: + +Droplet distribution + +Choose a region that is geographically close to you: + +Droplet region + +Choose a Droplet size that corresponds to your usage and budget: + +Droplet size + +Finalize the Droplet creation: + +Droplet finalization + +Droplet information is displayed on the Control Panel: + +Droplet summary + +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](https://www.gandi.net/en/domain). + +Once you have your own domain, you need to create a new DNS record that points +to your VPS' IP address: + +Domain configuration + +## Host setup +Now's the time to connect to your freshly created VPS! + +```shell +$ 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 + +root@stretch-shaarli-02:~$ +``` + +### Updating the system +```shell +root@stretch-shaarli-02:~$ apt update && apt upgrade -y +``` + +### Setting up Docker +_The following instructions are from the +[Get Docker CE for Debian](https://docs.docker.com/install/linux/docker-ce/debian/) +guide._ + +Install package dependencies: + +```shell +root@stretch-shaarli-02:~$ apt install -y apt-transport-https ca-certificates curl gnupg2 software-properties-common +``` + +Add Docker's package repository GPG key: + +```shell +root@stretch-shaarli-02:~$ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add - +``` + +Add Docker's package repository: + +```shell +root@stretch-shaarli-02:~$ add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian stretch stable" +``` + +Update package lists and install Docker: + +```shell +root@stretch-shaarli-02:~$ apt update && apt install -y docker-ce +``` + +Verify Docker is properly configured by running the `hello-world` image: + +```shell +root@stretch-shaarli-02:~$ docker run hello-world +``` + +### Setting up Docker Compose +_The following instructions are from the +[Install Docker Compose](https://docs.docker.com/compose/install/) +guide._ + +Download the current version from the release page: + +```shell +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](https://docs.docker.com/storage/volumes/) to store Shaarli data +- a Docker [volume](https://docs.docker.com/storage/volumes/) to store Træfik TLS configuration and certificates +- a [Shaarli](https://hub.docker.com/r/shaarli/shaarli/) instance +- a [Træfik](https://hub.docker.com/_/traefik/) instance + +[Træfik](https://docs.traefik.io/) is a modern HTTP reverse proxy, with native +support for Docker and [Let's Encrypt](https://letsencrypt.org/). + +### Compose configuration +Create a new directory to store the configuration: + +```shell +root@stretch-shaarli-02:~$ mkdir shaarli && cd shaarli +root@stretch-shaarli-02:~/shaarli$ +``` + +Download the current version of Shaarli's `docker-compose.yml`: + +```shell +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 +`` and `` with your actual information): + +```shell +root@stretch-shaarli-02:~/shaarli$ vim .env +``` + +```shell +SHAARLI_VIRTUAL_HOST= +SHAARLI_LETSENCRYPT_EMAIL= +``` + +### Pull the Docker images +```shell +root@stretch-shaarli-02:~/shaarli$ docker-compose pull +Pulling shaarli ... done +Pulling traefik ... done +``` + +### Run! +```shell +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://`. + +Shaarli installation page + +## Resources +### Related Shaarli documentation +- [Docker 101](../docker/docker-101.md) +- [Shaarli images](../docker/shaarli-images.md) + +### Hosting providers +- [DigitalOcean](https://www.digitalocean.com/) +- [Gandi](https://www.gandi.net/en) +- [OVH](https://www.ovh.co.uk/) +- [RackSpace](https://www.rackspace.com/) +- etc. + +### Domain Names and Registrars +- [Introduction to the Domain Name System (DNS)](https://opensource.com/article/17/4/introduction-domain-name-system-dns) +- [ICANN](https://www.icann.org/) +- [Domain name registrar](https://en.wikipedia.org/wiki/Domain_name_registrar) +- [OVH Domain Registration](https://www.ovh.co.uk/domains/) +- [Gandi Domain Registration](https://www.gandi.net/en/domain) + +### HTTPS and Security +- [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) +- [Let's Encrypt](https://letsencrypt.org/) + +### Docker +- [Docker Overview](https://docs.docker.com/engine/docker-overview/) +- [Docker Documentation](https://docs.docker.com/) +- [Get Docker CE for Debian](https://docs.docker.com/install/linux/docker-ce/debian/) +- [docker logs](https://docs.docker.com/engine/reference/commandline/logs/) +- [Volumes](https://docs.docker.com/storage/volumes/) +- [Install Docker Compose](https://docs.docker.com/compose/install/) +- [docker-compose logs](https://docs.docker.com/compose/reference/logs/) + +### Træfik +- [Getting Started](https://docs.traefik.io/) +- [Docker backend](https://docs.traefik.io/configuration/backends/docker/) +- [Let's Encrypt and Docker](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/) +- [traefik](https://hub.docker.com/_/traefik/) Docker image diff --git a/docker-compose.yml b/docker-compose.yml index fc68bf30..e8ea4271 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,8 +1,13 @@ --- -# Shaarli - Docker Compose script +# Shaarli - Docker Compose example configuration # # See: # - https://shaarli.readthedocs.io/en/master/docker/shaarli-images/ +# - https://shaarli.readthedocs.io/en/master/guides/install-shaarli-with-debian9-and-docker/ +# +# Environment variables: +# - SHAARLI_VIRTUAL_HOST Fully Qualified Domain Name for the Shaarli instance +# - SHAARLI_LETSENCRYPT_EMAIL Contact email for certificate renewal version: '3' networks: diff --git a/mkdocs.yml b/mkdocs.yml index 7f6ce255..c66d164b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,6 +28,7 @@ pages: - REST API: REST-API.md - Community & Related software: Community-&-Related-software.md - Guides: + - Install Shaarli on Debian 9 with Docker: guides/install-shaarli-with-debian9-and-docker.md - Backup, restore, import and export: guides/backup-restore-import-export.md - Various hacks: guides/various-hacks.md - Development: