aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md/Docker.md
diff options
context:
space:
mode:
authornodiscc <nodiscc@gmail.com>2020-05-16 12:54:51 +0200
committernodiscc <nodiscc@gmail.com>2020-09-12 14:31:45 +0200
commit91a21c272960889afd4eaa431a3d29b7785b6efc (patch)
tree26e3ba62319964c5fd48d93fdfe47813d5dc9bf5 /doc/md/Docker.md
parent6128ab6a55430a2b705be31ff417c0c552a0db1f (diff)
downloadShaarli-91a21c272960889afd4eaa431a3d29b7785b6efc.tar.gz
Shaarli-91a21c272960889afd4eaa431a3d29b7785b6efc.tar.zst
Shaarli-91a21c272960889afd4eaa431a3d29b7785b6efc.zip
**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
Diffstat (limited to 'doc/md/Docker.md')
-rw-r--r--doc/md/Docker.md207
1 files changed, 207 insertions, 0 deletions
diff --git a/doc/md/Docker.md b/doc/md/Docker.md
new file mode 100644
index 00000000..bcd8cff2
--- /dev/null
+++ b/doc/md/Docker.md
@@ -0,0 +1,207 @@
1# Docker
2
3[Docker](https://docs.docker.com/get-started/overview/) is an open platform for developing, shipping, and running applications
4
5## Install Docker
6
7Install [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/):
8
9```bash
10# update your package lists
11$ sudo apt update
12# remove old versions
13$ sudo apt-get remove docker docker-engine docker.io containerd runc
14# install requirements
15$ sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common
16# add docker's GPG signing key
17curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
18# add the repository
19$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
20# install docker engine
21$ sudo apt-get update
22$ sudo apt-get install docker-ce docker-ce-cli containerd.io
23# verify that Docker is properly configured
24root@stretch-shaarli-02:~$ docker run hello-world
25```
26
27
28## Get and run a Shaarli image
29
30Shaarli images are available on [DockerHub](https://hub.docker.com/r/shaarli/shaarli/):
31
32- `latest`: latest branch
33- `master`: master branch
34
35These images are built automatically on DockerHub and rely on:
36
37- [Alpine Linux](https://www.alpinelinux.org/)
38- [PHP7-FPM](http://php-fpm.org/)
39- [Nginx](http://nginx.org/)
40
41Additional 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/).
42
43```bash
44# download the 'latest' image from dockerhub
45docker pull shaarli/shaarli
46
47# create persistent data volumes/directories on the host
48docker volume create shaarli-data
49docker volume create shaarli-cache
50
51# create a new container using the Shaarli image
52# --detach: run the container in background
53# --name: name of the created container/instance
54# --publish: map the host's :8000 port to the container's :80 port
55# --rm: automatically remove the container when it exits
56# --volume: mount persistent volumes in the container ($volume_name:$volume_mountpoint)
57docker run --detach \
58 --name myshaarli \
59 --publish 8000:80 \
60 --rm \
61 --volume shaarli-data:/var/www/shaarli/data \
62 --volume shaarli-cache:/var/www/shaarli/cache \
63 shaarli/shaarli
64
65# verify that the container is running
66docker ps | grep myshaarli
67
68# to completely remove the container
69docker stop myshaarli # stop the running container
70docker ps | grep myshaarli # verify the container is no longer running
71docker ps -a | grep myshaarli # verify the container is stopped
72docker rm myshaarli # destroy the container
73docker ps -a | grep myshaarli # verify th container has been destroyed
74
75```
76
77## Docker Compose
78
79A [Compose file](https://docs.docker.com/compose/compose-file/) is a common format for defining and running multi-container Docker applications.
80
81A `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/).
82
83Shaarli 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.
84
85```bash
86Download docker-compose from the [release page](https://docs.docker.com/compose/install/):
87
88```shell
89$ 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
90$ sudo chmod +x /usr/local/bin/docker-compose
91# create a new directory to store the configuration:
92$ mkdir shaarli && cd shaarli
93# Download the current version of Shaarli's docker-compose.yml
94$ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/master/docker-compose.yml -o docker-compose.yml
95# Create the .env file and fill in your VPS and domain information
96# (replace <MY_SHAARLI_DOMAIN> and <MY_CONTACT_EMAIL> with your actual information)
97$ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' > .env
98$ echo 'SHAARLI_LETSENCRYPT_EMAIL=admin@mydomain.org' >> .env
99# Pull the Docker images
100$ docker-compose pull
101# Run!
102$ docker-compose up -d
103```
104
105
106
107### Running dockerized Shaarli as a systemd service
108
109It 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.
110
111As root, create `/etc/systemd/system/docker.shaarli.service`:
112
113```ini
114[Unit]
115Description=Shaarli Bookmark Manager Container
116After=docker.service
117Requires=docker.service
118
119
120[Service]
121Restart=always
122
123# Put any environment you want in an included file, like $host- or $domainname in this example
124EnvironmentFile=/etc/sysconfig/box-environment
125
126# It's just an example..
127ExecStart=/usr/bin/docker run \
128 -p 28010:80 \
129 --name ${hostname}-shaarli \
130 --hostname shaarli.${domainname} \
131 -v /srv/docker-volumes-local/shaarli-data:/var/www/shaarli/data:rw \
132 -v /etc/localtime:/etc/localtime:ro \
133 shaarli/shaarli:latest
134
135ExecStop=/usr/bin/docker rm -f ${hostname}-shaarli
136
137[Install]
138WantedBy=multi-user.target
139```
140
141```bash
142# reload systemd services definitions
143systemctl daemon-reload
144# start the servie and enable it a boot time
145systemctl enable docker.shaarli.service --now
146# verify that the service is running
147systemctl status docker.*
148# inspect system log if needed
149journalctl -f
150```
151
152
153
154## Docker cheatsheet
155
156```bash
157# pull/update an image
158$ docker pull shaarli:release
159# run a container from an image
160$ docker run shaarli:latest
161# list available images
162$ docker images ls
163# list running containers
164$ docker ps
165# list running AND stopped containers
166$ docker ps -a
167# run a command in a running container
168$ docker exec -ti <container-name-or-first-letters-of-id> bash
169# follow logs of a running container
170$ docker logs -f <container-name-or-first-letters-of-id>
171# delete unused images to free up disk space
172$ docker system prune --images
173# delete unused volumes to free up disk space (CAUTION all data in unused volumes will be lost)
174$ docker system prunt --volumes
175# delete unused containers
176$ docker system prune
177```
178
179
180## References
181
182- [Docker: using volumes](https://docs.docker.com/storage/volumes/)
183- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/)
184- [Dockerfile reference](https://docs.docker.com/reference/builder/)
185- [DockerHub: GitHub automated build](https://docs.docker.com/docker-hub/github/)
186- [DockerHub: Repositories](https://docs.docker.com/userguide/dockerrepos/)
187- [DockerHub: Teams and organizations](https://docs.docker.com/docker-hub/orgs/)
188- [Get Docker CE for Debian](https://docs.docker.com/install/linux/docker-ce/debian/)
189- [Install Docker Compose](https://docs.docker.com/compose/install/)
190- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/)
191- [Service management: Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon)
192- [Service management: Using supervisord](https://docs.docker.com/articles/using_supervisord/)
193- [Volumes](https://docs.docker.com/storage/volumes/)
194- [Volumes](https://docs.docker.com/userguide/dockervolumes/)
195- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/)
196- [docker create](https://docs.docker.com/engine/reference/commandline/create/)
197- [Docker Documentation](https://docs.docker.com/)
198- [docker exec](https://docs.docker.com/engine/reference/commandline/exec/)
199- [docker images](https://docs.docker.com/engine/reference/commandline/images/)
200- [docker logs](https://docs.docker.com/engine/reference/commandline/logs/)
201- [docker logs](https://docs.docker.com/engine/reference/commandline/logs/)
202- [Docker Overview](https://docs.docker.com/engine/docker-overview/)
203- [docker ps](https://docs.docker.com/engine/reference/commandline/ps/)
204- [docker pull](https://docs.docker.com/engine/reference/commandline/pull/)
205- [docker run](https://docs.docker.com/engine/reference/commandline/run/)
206- [docker-compose logs](https://docs.docker.com/compose/reference/logs/)
207- 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/) \ No newline at end of file