From 91a21c272960889afd4eaa431a3d29b7785b6efc Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 16 May 2020 12:54:51 +0200 Subject: **General rewording, proof-reading, deduplication, shortening, reordering, simplification, cleanup/formatting/standardization** - standardize page names, rework documentation structure, update TOC - use same example paths everywhere - level 1 titles on all pages - fix broken links - .md suffix on all page links (works both from readthedocs and github repository views) **Server:** A full and concise installation guide with examples is a frequent request. The documentation should provide such a guide for basic installation needs, while explaining alternative/advanced configuration at the end. Links to reference guides and documentation should be used more frequently to avoid recommending an outdated or excessively complex configuration. - server: move most server-related info to server-configuration.md, cleanup/shorten - server: update list of php dependencies/libraries, link to composer.json - server: installation: support 3 install methods (from release zip, from sources, using docker) - server: installation: use rsync instead of mv as mv results will change depending of taget directory already existing or not - server: add example/basic usage of certbot - server, upgrade, installation: update file permissions setup, use sudo for upgrade operations in webserver document root - server: apache: add comments to configuration, fix and factorize file permissions setup, set cache-control header, deny access to dotfiles, add missing apache config steps, add http->https redirect example - server: nginx: refactor nginx configuration, add comments, DO log access to denied/protected files - server: add links to MDN for x-forwarded-* http headers explanation, cleanup/clarify robots.txt and crawlers section - server: bump file upload size limit to 100MB we have reports of bookmark exports weighing +40MB - i have a 13MB one here - server: simplify phpinfo documentation - server: move backup and restore information to dedicated page - docker: move all docker docs to Docker.md, simplify/ docker setup, add docker-compose.yml example, replace docker-101 with docker cheatsheet - troubleshooting: move all troubleshooting documentation to troubleshooting.md **Usage:** - index: add getting started section on index page - features/usage: move all usage-related documentation to usage.md, add links from the main feature list to corresponding usage docs, clarify/reword features list - shaarli configuration: add note about configuring from web interface **Removed:** - remove obsolete/orphan images - remove obsolete shaarchiver example - remove outdated "decode datastore content" snippet **Development:** - development: move development-related docs (static analysis, CI, unit tests, 3rd party libs, link structure/directory, guidelines, security....) to dev/ directory - development: Merge several pages to development.md - **Breaking change?:** remove mentions of 'stable' branch, switch to new branch/release model (master=latest commit, release=latest tag) - **Breaking change?:** refer to base sharing unit as "Shaare" everywhere (TODO: reflect changes in the code?) doc: update featues list/link to usage.md for details - development: directory structure: add note about required file permissions - .travis-ci.yml: add comments - .htaccess: add comment --- .../install-shaarli-with-debian9-and-docker.md | 257 --------------------- 1 file changed, 257 deletions(-) delete mode 100644 doc/md/guides/install-shaarli-with-debian9-and-docker.md (limited to 'doc/md/guides/install-shaarli-with-debian9-and-docker.md') diff --git a/doc/md/guides/install-shaarli-with-debian9-and-docker.md b/doc/md/guides/install-shaarli-with-debian9-and-docker.md deleted file mode 100644 index f1b26d47..00000000 --- a/doc/md/guides/install-shaarli-with-debian9-and-docker.md +++ /dev/null @@ -1,257 +0,0 @@ -_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 -- cgit v1.2.3