MyShaarli/doc/md/Docker.md

206 lines
8.7 KiB
Markdown
Raw Normal View History

**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
2020-05-16 12:54:51 +02:00
# Docker
[Docker](https://docs.docker.com/get-started/overview/) is an open platform for developing, shipping, and running applications
## Install Docker
Install [Docker](https://www.docker.com/), by following the instructions relevant to your OS / distribution, and start the service. For example on [Debian](https://docs.docker.com/engine/install/debian/):
```bash
# update your package lists
$ sudo apt update
# remove old versions
$ sudo apt-get remove docker docker-engine docker.io containerd runc
# install requirements
$ sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common
# add docker's GPG signing key
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
# add the repository
$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
# install docker engine
$ sudo apt-get update
$ sudo apt-get install docker-ce docker-ce-cli containerd.io
# verify that Docker is properly configured
root@stretch-shaarli-02:~$ docker run hello-world
```
## Get and run a Shaarli image
Shaarli images are available on [DockerHub](https://hub.docker.com/r/shaarli/shaarli/):
- `latest`: latest branch
- `master`: master branch
These images are built automatically on DockerHub and 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/).
```bash
# download the 'latest' image from dockerhub
docker pull shaarli/shaarli
# create persistent data volumes/directories on the host
docker volume create shaarli-data
docker volume create shaarli-cache
# create a new container using the Shaarli image
# --detach: run the container in background
# --name: name of the created container/instance
# --publish: map the host's :8000 port to the container's :80 port
# --rm: automatically remove the container when it exits
# --volume: mount persistent volumes in the container ($volume_name:$volume_mountpoint)
docker run --detach \
--name myshaarli \
--publish 8000:80 \
--rm \
--volume shaarli-data:/var/www/shaarli/data \
--volume shaarli-cache:/var/www/shaarli/cache \
shaarli/shaarli
# verify that the container is running
docker ps | grep myshaarli
# to completely remove the container
docker stop myshaarli # stop the running container
docker ps | grep myshaarli # verify the container is no longer running
docker ps -a | grep myshaarli # verify the container is stopped
docker rm myshaarli # destroy the container
docker ps -a | grep myshaarli # verify th container has been destroyed
```
## Docker Compose
A [Compose file](https://docs.docker.com/compose/compose-file/) is a common format for defining and running multi-container Docker applications.
A `docker-compose.yml` file can be used to run a persistent/autostarted shaarli service using [Docker Compose](https://docs.docker.com/compose/) or in a [Docker stack](https://docs.docker.com/engine/reference/commandline/stack_deploy/).
Shaarli provides configuration file for Docker Compose, that will setup a Shaarli instance, a [Træfik](https://hub.docker.com/_/traefik/) instance with [Let's Encrypt](https://letsencrypt.org/) certificates, a Docker network, and volumes for Shaarli data and Træfik TLS configuration and certificates.
Download docker-compose from the [release page](https://docs.docker.com/compose/install/):
2020-05-16 13:08:28 +02:00
```bash
**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
2020-05-16 12:54:51 +02:00
$ sudo curl -L "https://github.com/docker/compose/releases/download/1.25.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
$ sudo chmod +x /usr/local/bin/docker-compose
# create a new directory to store the configuration:
$ mkdir shaarli && cd shaarli
# Download the current version of Shaarli's docker-compose.yml
$ 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 <MY_SHAARLI_DOMAIN> and <MY_CONTACT_EMAIL> with your actual information)
$ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' > .env
$ echo 'SHAARLI_LETSENCRYPT_EMAIL=admin@mydomain.org' >> .env
# Pull the Docker images
$ docker-compose pull
# Run!
$ docker-compose up -d
```
### Running dockerized Shaarli as a systemd service
It is possible to start a dockerized Shaarli instance as a systemd service (systemd is the service management tool on several distributions). After installing Docker, use the following steps to run your shaarli container Shaarli to run on system start.
As root, create `/etc/systemd/system/docker.shaarli.service`:
```ini
[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
```
```bash
# reload systemd services definitions
systemctl daemon-reload
# start the servie and enable it a boot time
systemctl enable docker.shaarli.service --now
# verify that the service is running
systemctl status docker.*
# inspect system log if needed
journalctl -f
```
## Docker cheatsheet
```bash
# pull/update an image
$ docker pull shaarli:release
# run a container from an image
$ docker run shaarli:latest
# list available images
$ docker images ls
# list running containers
$ docker ps
# list running AND stopped containers
$ docker ps -a
# run a command in a running container
$ docker exec -ti <container-name-or-first-letters-of-id> bash
# follow logs of a running container
$ docker logs -f <container-name-or-first-letters-of-id>
# delete unused images to free up disk space
$ docker system prune --images
# delete unused volumes to free up disk space (CAUTION all data in unused volumes will be lost)
$ docker system prunt --volumes
# delete unused containers
$ docker system prune
```
## References
- [Docker: using volumes](https://docs.docker.com/storage/volumes/)
- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/)
- [Dockerfile reference](https://docs.docker.com/reference/builder/)
- [DockerHub: GitHub automated build](https://docs.docker.com/docker-hub/github/)
- [DockerHub: Repositories](https://docs.docker.com/userguide/dockerrepos/)
- [DockerHub: Teams and organizations](https://docs.docker.com/docker-hub/orgs/)
- [Get Docker CE for Debian](https://docs.docker.com/install/linux/docker-ce/debian/)
- [Install Docker Compose](https://docs.docker.com/compose/install/)
- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/)
- [Service management: Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon)
- [Service management: Using supervisord](https://docs.docker.com/articles/using_supervisord/)
- [Volumes](https://docs.docker.com/storage/volumes/)
- [Volumes](https://docs.docker.com/userguide/dockervolumes/)
- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/)
- [docker create](https://docs.docker.com/engine/reference/commandline/create/)
- [Docker Documentation](https://docs.docker.com/)
- [docker exec](https://docs.docker.com/engine/reference/commandline/exec/)
- [docker images](https://docs.docker.com/engine/reference/commandline/images/)
- [docker logs](https://docs.docker.com/engine/reference/commandline/logs/)
- [docker logs](https://docs.docker.com/engine/reference/commandline/logs/)
- [Docker Overview](https://docs.docker.com/engine/docker-overview/)
- [docker ps](https://docs.docker.com/engine/reference/commandline/ps/)
- [docker pull](https://docs.docker.com/engine/reference/commandline/pull/)
- [docker run](https://docs.docker.com/engine/reference/commandline/run/)
- [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](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/), [Docker image](https://hub.docker.com/_/traefik/)