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 --- doc/md/docker/docker-101.md | 140 --------------------------- doc/md/docker/resources.md | 19 ---- doc/md/docker/reverse-proxy-configuration.md | 123 ----------------------- doc/md/docker/shaarli-images.md | 118 ---------------------- 4 files changed, 400 deletions(-) delete mode 100644 doc/md/docker/docker-101.md delete mode 100644 doc/md/docker/resources.md delete mode 100644 doc/md/docker/reverse-proxy-configuration.md delete mode 100644 doc/md/docker/shaarli-images.md (limited to 'doc/md/docker') diff --git a/doc/md/docker/docker-101.md b/doc/md/docker/docker-101.md deleted file mode 100644 index a9c00b85..00000000 --- a/doc/md/docker/docker-101.md +++ /dev/null @@ -1,140 +0,0 @@ -## Basics -Install [Docker](https://www.docker.com/), by following the instructions relevant -to your OS / distribution, and start the service. - -### Search an image on [DockerHub](https://hub.docker.com/) - -```bash -$ docker search debian - -NAME DESCRIPTION STARS OFFICIAL AUTOMATED -ubuntu Ubuntu is a Debian-based Linux operating s... 2065 [OK] -debian Debian is a Linux distribution that's comp... 603 [OK] -google/debian 47 [OK] -``` - -### Show available tags for a repository -```bash -$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool - -% Total % Received % Xferd Average Speed Time Time Time Current -Dload Upload Total Spent Left Speed -100 1283 0 1283 0 0 433 0 --:--:-- 0:00:02 --:--:-- 433 -``` - -Sample output: -```json -[ - { - "layer": "85a02782", - "name": "stretch" - }, - { - "layer": "59abecbc", - "name": "testing" - }, - { - "layer": "bf0fd686", - "name": "unstable" - }, - { - "layer": "60c52dbe", - "name": "wheezy" - }, - { - "layer": "c5b806fe", - "name": "wheezy-backports" - } -] - -``` - -### Pull an image from DockerHub -```bash -$ docker pull repository[:tag] - -$ docker pull debian:wheezy -wheezy: Pulling from debian -4c8cbfd2973e: Pull complete -60c52dbe9d91: Pull complete -Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe -Status: Downloaded newer image for debian:wheezy -``` - -Docker re-uses layers already downloaded. In other words if you have images based on Alpine or some Ubuntu version for example, those can share disk space. - -### Start a container -A container is an instance created from an image, that can be run and that keeps running until its main process exits. Or until the user stops the container. - -The simplest way to start a container from image is ``docker run``. It also pulls the image for you if it is not locally available. For more advanced use, refer to ``docker create``. - -Stopped containers are not destroyed, unless you specify ``--rm``. To view all created, running and stopped containers, enter: -```bash -$ docker ps -a -``` - -Some containers may be designed or configured to be restarted, others are not. Also remember both network ports and volumes of a container are created on start, and not editable later. - -### Access a running container -A running container is accessible using ``docker exec``, or ``docker copy``. You can use ``exec`` to start a root shell in the Shaarli container: -```bash -$ docker exec -ti bash -``` -Note the names and ID's of containers are listed in ``docker ps``. You can even type only one or two letters of the ID, given they are unique. - -Access can also be through one or more network ports, or disk volumes. Both are specified on and fixed on ``docker create`` or ``run``. - -You can view the console output of the main container process too: -```bash -$ docker logs -f -``` - -### Docker disk use -Trying out different images can fill some gigabytes of disk quickly. Besides images, the docker volumes usually take up most disk space. - -If you care only about trying out docker and not about what is running or saved, the following commands should help you out quickly if you run low on disk space: - -```bash -$ docker rmi -f $(docker images -aq) # remove or mark all images for disposal -$ docker volume rm $(docker volume ls -q) # remove all volumes -``` - -### Systemd config -Systemd is the process manager of choice on Debian-based distributions. Once you have a ``docker`` service installed, you can use the following steps to set up Shaarli to run on system start. - -```bash -systemctl enable /etc/systemd/system/docker.shaarli.service -systemctl start docker.shaarli -systemctl status docker.* -journalctl -f # inspect system log if needed -``` - -You will need sudo or a root terminal to perform some or all of the steps above. Here are the contents for the service file: -``` -[Unit] -Description=Shaarli Bookmark Manager Container -After=docker.service -Requires=docker.service - - -[Service] -Restart=always - -# Put any environment you want in an included file, like $host- or $domainname in this example -EnvironmentFile=/etc/sysconfig/box-environment - -# It's just an example.. -ExecStart=/usr/bin/docker run \ - -p 28010:80 \ - --name ${hostname}-shaarli \ - --hostname shaarli.${domainname} \ - -v /srv/docker-volumes-local/shaarli-data:/var/www/shaarli/data:rw \ - -v /etc/localtime:/etc/localtime:ro \ - shaarli/shaarli:latest - -ExecStop=/usr/bin/docker rm -f ${hostname}-shaarli - - -[Install] -WantedBy=multi-user.target -``` diff --git a/doc/md/docker/resources.md b/doc/md/docker/resources.md deleted file mode 100644 index 082d4a46..00000000 --- a/doc/md/docker/resources.md +++ /dev/null @@ -1,19 +0,0 @@ -### Docker - -- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/) -- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/) -- [Dockerfile reference](https://docs.docker.com/reference/builder/) -- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/) -- [Volumes](https://docs.docker.com/userguide/dockervolumes/) - -### DockerHub - -- [Repositories](https://docs.docker.com/userguide/dockerrepos/) -- [Teams and organizations](https://docs.docker.com/docker-hub/orgs/) -- [GitHub automated build](https://docs.docker.com/docker-hub/github/) - -### Service management - -- [Using supervisord](https://docs.docker.com/articles/using_supervisord/) -- [Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon) -- [supervisord](http://supervisord.org/) diff --git a/doc/md/docker/reverse-proxy-configuration.md b/doc/md/docker/reverse-proxy-configuration.md deleted file mode 100644 index e53c9422..00000000 --- a/doc/md/docker/reverse-proxy-configuration.md +++ /dev/null @@ -1,123 +0,0 @@ -## Foreword - -This guide assumes that: - -- Shaarli runs in a Docker container -- The host's `10080` port is mapped to the container's `80` port -- Shaarli's Fully Qualified Domain Name (FQDN) is `shaarli.domain.tld` -- HTTP traffic is redirected to HTTPS - -## Apache - -- [Apache 2.4 documentation](https://httpd.apache.org/docs/2.4/) - - [mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html) - - [Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers) - -The following HTTP headers are set when the `ProxyPass` directive is set: - -- `X-Forwarded-For` -- `X-Forwarded-Host` -- `X-Forwarded-Server` - -The original `SERVER_NAME` can be sent to the proxied host by setting the [`ProxyPreserveHost`](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#ProxyPreserveHost) directive to `On`. - -```apache - - ServerName shaarli.domain.tld - Redirect permanent / https://shaarli.domain.tld - - - - ServerName shaarli.domain.tld - - SSLEngine on - SSLCertificateFile /path/to/cert - SSLCertificateKeyFile /path/to/certkey - - LogLevel warn - ErrorLog /var/log/apache2/shaarli-error.log - CustomLog /var/log/apache2/shaarli-access.log combined - - RequestHeader set X-Forwarded-Proto "https" - ProxyPreserveHost On - - ProxyPass / http://127.0.0.1:10080/ - ProxyPassReverse / http://127.0.0.1:10080/ - -``` - - -## HAProxy - -- [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/) - -```conf -global - [...] - -defaults - [...] - -frontend http-in - bind :80 - redirect scheme https code 301 if !{ ssl_fc } - - bind :443 ssl crt /path/to/cert.pem - - default_backend shaarli - - -backend shaarli - mode http - option http-server-close - option forwardfor - reqadd X-Forwarded-Proto: https - - server shaarli1 127.0.0.1:10080 -``` - - -## Nginx - -- [Nginx documentation](https://nginx.org/en/docs/) - -```nginx -http { - [...] - - index index.html index.php; - - root /home/john/web; - access_log /var/log/nginx/access.log; - error_log /var/log/nginx/error.log; - - server { - listen 80; - server_name shaarli.domain.tld; - return 301 https://shaarli.domain.tld$request_uri; - } - - server { - listen 443 ssl http2; - server_name shaarli.domain.tld; - - ssl_certificate /path/to/cert - ssl_certificate_key /path/to/certkey - - location / { - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Forwarded-Host $host; - - proxy_pass http://localhost:10080/; - proxy_set_header Host $host; - proxy_connect_timeout 30s; - proxy_read_timeout 120s; - - access_log /var/log/nginx/shaarli.access.log; - error_log /var/log/nginx/shaarli.error.log; - } - } -} -``` diff --git a/doc/md/docker/shaarli-images.md b/doc/md/docker/shaarli-images.md deleted file mode 100644 index 14971d54..00000000 --- a/doc/md/docker/shaarli-images.md +++ /dev/null @@ -1,118 +0,0 @@ -A brief guide on getting starting using docker is given in [Docker 101](docker-101.md). -To learn more about user data and how to keep it across versions, please see [Upgrade and Migration](../Upgrade-and-migration.md). - -## Get and run a Shaarli image - -### DockerHub repository -The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaarli/shaarli/) -repository. - -### Available image tags -- `latest`: latest branch -- `master`: master branch -- `stable`: stable branch - -The `latest`, `master` and `stable` images rely on: - -- [Alpine Linux](https://www.alpinelinux.org/) -- [PHP7-FPM](http://php-fpm.org/) -- [Nginx](http://nginx.org/) - -Additional Dockerfiles are provided for the `arm32v7` platform, relying on -[Linuxserver.io Alpine armhf -images](https://hub.docker.com/r/lsiobase/alpine.armhf/). These images must be -built using [`docker -build`](https://docs.docker.com/engine/reference/commandline/build/) on an -`arm32v7` machine or using an emulator such as -[qemu](https://resin.io/blog/building-arm-containers-on-any-x86-machine-even-dockerhub/). - -### Download from Docker Hub -```shell -$ docker pull shaarli/shaarli - -latest: Pulling from shaarli/shaarli -32716d9fcddb: Pull complete -84899d045435: Pull complete -4b6ad7444763: Pull complete -e0345ef7a3e0: Pull complete -5c1dd344094f: Pull complete -6422305a200b: Pull complete -7d63f861dbef: Pull complete -3eb97210645c: Pull complete -869319d746ff: Already exists -869319d746ff: Pulling fs layer -902b87aaaec9: Already exists -Digest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98 -Status: Downloaded newer image for shaarli/shaarli:latest -``` - -### Create and start a new container from the image -```shell -# map the host's :8000 port to the container's :80 port -$ docker create -p 8000:80 shaarli/shaarli -d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 - -# launch the container in the background -$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 -d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 - -# list active containers -$ docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo -``` - -### Stop and destroy a container -```shell -$ docker stop backstabbing_galileo # those docker guys are really rude to physicists! -backstabbing_galileo - -# check the container is stopped -$ docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - -# list ALL containers -$ docker ps -a -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) 48 seconds ago backstabbing_galileo - -# destroy the container -$ docker rm backstabbing_galileo # let's put an end to these barbarian practices -backstabbing_galileo - -$ docker ps -a -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -``` - -### Automatic builds -Docker users can start a personal instance from an -[autobuild image](https://hub.docker.com/r/shaarli/shaarli/). -For example to start a temporary Shaarli at ``localhost:8000``, and keep session -data (config, storage): - -```shell -MY_SHAARLI_VOLUME=$(cd /path/to/shaarli/data/ && pwd -P) -docker run -ti --rm \ - -p 8000:80 \ - -v $MY_SHAARLI_VOLUME:/var/www/shaarli/data \ - shaarli/shaarli -``` - -### Volumes and data persistence -Data can be persisted by [using volumes](https://docs.docker.com/storage/volumes/). -Volumes allow to keep your data when renewing and/or updating container images: - -```shell -# Create data volumes -$ docker volume create shaarli-data -$ docker volume create shaarli-cache - -# Create and start a Shaarli container using these volumes to persist data -$ docker create \ - --name shaarli \ - -v shaarli-cache:/var/www/shaarli/cache \ - -v shaarli-data:/var/www/shaarli/data \ - -p 8000:80 \ - shaarli/shaarli:master -$ docker start shaarli -``` -- cgit v1.2.3