diff --git a/.dockerignore b/.dockerignore index a0d28dc..96fd31c 100644 --- a/.dockerignore +++ b/.dockerignore @@ -4,6 +4,9 @@ .github tests +# Docker Compose resources +docker-compose.yml + # Shaarli runtime resources cache/* data/* diff --git a/.gitattributes b/.gitattributes index 9d22f11..9a92bc3 100644 --- a/.gitattributes +++ b/.gitattributes @@ -35,6 +35,7 @@ doc/**/*.json export-ignore doc/**/*.md export-ignore .docker/ export-ignore .dockerignore export-ignore +docker-compose.* export-ignore Dockerfile* export-ignore Doxyfile export-ignore Makefile export-ignore diff --git a/doc/md/Backup,-restore,-import-and-export.md b/doc/md/guides/backup-restore-import-export.md similarity index 100% rename from doc/md/Backup,-restore,-import-and-export.md rename to doc/md/guides/backup-restore-import-export.md 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 0000000..63682ba 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 0000000..135a78b 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 0000000..aa5b2fd 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 0000000..68ec0dc 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 0000000..44e93a1 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 0000000..5827dd9 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 0000000..42cc9f1 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 0000000..f1b26d4 --- /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/doc/md/Various-hacks.md b/doc/md/guides/various-hacks.md similarity index 100% rename from doc/md/Various-hacks.md rename to doc/md/guides/various-hacks.md diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..e8ea427 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,61 @@ +--- +# 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: + http-proxy: + +volumes: + traefik-acme: + shaarli-cache: + shaarli-data: + +services: + shaarli: + image: shaarli/shaarli:master + build: ./ + networks: + - http-proxy + volumes: + - shaarli-cache:/var/www/shaarli/cache + - shaarli-data:/var/www/shaarli/data + labels: + traefik.domain: "${SHAARLI_VIRTUAL_HOST}" + traefik.backend: shaarli + traefik.frontend.rule: "Host:${SHAARLI_VIRTUAL_HOST}" + + traefik: + image: traefik + command: + - "--defaultentrypoints=http,https" + - "--entrypoints=Name:http Address::80 Redirect.EntryPoint:https" + - "--entrypoints=Name:https Address::443 TLS" + - "--retry" + - "--docker" + - "--docker.domain=docker.localhost" + - "--docker.exposedbydefault=true" + - "--docker.watch=true" + - "--acme" + - "--acme.domains=${SHAARLI_VIRTUAL_HOST}" + - "--acme.email=${SHAARLI_LETSENCRYPT_EMAIL}" + - "--acme.entrypoint=https" + - "--acme.onhostrule=true" + - "--acme.storage=/acme/acme.json" + - "--acme.httpchallenge" + - "--acme.httpchallenge.entrypoint=http" + networks: + - http-proxy + ports: + - 80:80 + - 443:443 + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + - traefik-acme:/acme diff --git a/index.php b/index.php index 29d67f6..5fc880e 100644 --- a/index.php +++ b/index.php @@ -1103,7 +1103,7 @@ function renderPage($conf, $pluginManager, $LINKSDB, $history, $sessionManager, // Linkdate is kept here to: // - use the same permalink for notes as they're displayed when creating them // - let users hack creation date of their posts - // See: https://shaarli.readthedocs.io/en/master/Various-hacks/#changing-the-timestamp-for-a-shaare + // See: https://shaarli.readthedocs.io/en/master/guides/various-hacks/#changing-the-timestamp-for-a-shaare $linkdate = escape($_POST['lf_linkdate']); if (isset($LINKSDB[$id])) { // Edit diff --git a/mkdocs.yml b/mkdocs.yml index 76e0efb..ae38459 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,9 +30,10 @@ pages: - RSS feeds: RSS-feeds.md - REST API: REST-API.md - Community & Related software: Community-&-Related-software.md -- How To: - - Backup, restore, import and export: Backup,-restore,-import-and-export.md - - Various hacks: Various-hacks.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: - Development guidelines: Development-guidelines.md - Continuous integration tools: Continuous-integration-tools.md