]> git.immae.eu Git - github/shaarli/Shaarli.git/blame - doc/md/Docker.md
Fix: bulk add redirection with ending slash
[github/shaarli/Shaarli.git] / doc / md / Docker.md
CommitLineData
b7c50a58 1
91a21c27 2# Docker
3
4[Docker](https://docs.docker.com/get-started/overview/) is an open platform for developing, shipping, and running applications
5
6## Install Docker
7
97870f35 8Install [Docker](https://docs.docker.com/engine/install/), by following the instructions relevant to your OS / distribution, and start the service. For example on [Debian](https://docs.docker.com/engine/install/debian/):
91a21c27 9
10```bash
11# update your package lists
97870f35 12sudo apt update
91a21c27 13# remove old versions
97870f35 14sudo apt-get remove docker docker-engine docker.io containerd runc
91a21c27 15# install requirements
97870f35 16sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common
91a21c27 17# add docker's GPG signing key
18curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
19# add the repository
97870f35 20sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
91a21c27 21# install docker engine
97870f35
A
22sudo apt-get update
23sudo apt-get install docker-ce docker-ce-cli containerd.io
24# Start and enable Docker service
25sudo systemctl enable docker && sudo systemctl start docker
91a21c27 26# verify that Docker is properly configured
97870f35 27sudo docker run hello-world
91a21c27 28```
29
97870f35
A
30In order to run Docker commands as a non-root user, you must add the `docker` group to this user:
31
32```bash
33# Add docker group as secondary group
34sudo usermod -aG docker your-user
35# Reboot or logout
36# Then verify that Docker is properly configured, as "your-user"
37docker run hello-world
38```
91a21c27 39
40## Get and run a Shaarli image
41
97870f35 42Shaarli images are available on [DockerHub](https://hub.docker.com/r/shaarli/shaarli/) `shaarli/shaarli`:
91a21c27 43
97870f35
A
44- `latest`: latest branch (last release)
45- `stable`: stable branch (last release in previous major version)
46- `master`: master branch (development branch)
91a21c27 47
48These images are built automatically on DockerHub and rely on:
49
50- [Alpine Linux](https://www.alpinelinux.org/)
51- [PHP7-FPM](http://php-fpm.org/)
52- [Nginx](http://nginx.org/)
53
54Additional 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/).
55
97870f35
A
56Here is an example of how to run Shaarli latest image using Docker:
57
91a21c27 58```bash
59# download the 'latest' image from dockerhub
60docker pull shaarli/shaarli
61
62# create persistent data volumes/directories on the host
63docker volume create shaarli-data
64docker volume create shaarli-cache
65
66# create a new container using the Shaarli image
67# --detach: run the container in background
68# --name: name of the created container/instance
69# --publish: map the host's :8000 port to the container's :80 port
70# --rm: automatically remove the container when it exits
71# --volume: mount persistent volumes in the container ($volume_name:$volume_mountpoint)
72docker run --detach \
73 --name myshaarli \
74 --publish 8000:80 \
75 --rm \
76 --volume shaarli-data:/var/www/shaarli/data \
77 --volume shaarli-cache:/var/www/shaarli/cache \
97870f35 78 shaarli/shaarli:latest
91a21c27 79
80# verify that the container is running
81docker ps | grep myshaarli
82
83# to completely remove the container
84docker stop myshaarli # stop the running container
85docker ps | grep myshaarli # verify the container is no longer running
86docker ps -a | grep myshaarli # verify the container is stopped
87docker rm myshaarli # destroy the container
88docker ps -a | grep myshaarli # verify th container has been destroyed
89
90```
91
97870f35
A
92After running `docker run` command, your Shaarli instance should be available on the host machine at [localhost:8000](http://localhost:8000). In order to access your instance through a reverse proxy, we recommend using our [Docker Compose](#docker-compose) build.
93
91a21c27 94## Docker Compose
95
96A [Compose file](https://docs.docker.com/compose/compose-file/) is a common format for defining and running multi-container Docker applications.
97
98A `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/).
99
97870f35 100Shaarli provides configuration file for Docker Compose, that will setup a Shaarli instance, a [Træfik](https://containo.us/traefik/) instance (reverse proxy) with [Let's Encrypt](https://letsencrypt.org/) certificates, a Docker network, and volumes for Shaarli data and Træfik TLS configuration and certificates.
91a21c27 101
91a21c27 102Download docker-compose from the [release page](https://docs.docker.com/compose/install/):
103
fe007f94 104```bash
ff2b5f5b 105$ sudo curl -L "https://github.com/docker/compose/releases/download/1.26.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
91a21c27 106$ sudo chmod +x /usr/local/bin/docker-compose
97870f35
A
107```
108
109To run Shaarli container and its reverse proxy, you can execute the following commands:
110
111```bash
91a21c27 112# create a new directory to store the configuration:
113$ mkdir shaarli && cd shaarli
97870f35
A
114# Download the latest version of Shaarli's docker-compose.yml
115$ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/latest/docker-compose.yml -o docker-compose.yml
91a21c27 116# Create the .env file and fill in your VPS and domain information
b7c50a58 117# (replace <shaarli.mydomain.org>, <admin@mydomain.org> and <latest> with your actual information)
91a21c27 118$ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' > .env
119$ echo 'SHAARLI_LETSENCRYPT_EMAIL=admin@mydomain.org' >> .env
b7c50a58
A
120# Available Docker tags can be found at https://hub.docker.com/r/shaarli/shaarli/tags
121$ echo 'SHAARLI_DOCKER_TAG=latest' >> .env
91a21c27 122# Pull the Docker images
123$ docker-compose pull
124# Run!
125$ docker-compose up -d
126```
127
97870f35 128After a few seconds, you should be able to access your Shaarli instance at [https://shaarli.mydomain.org](https://shaarli.mydomain.org) (replace your own domain name).
91a21c27 129
97870f35 130## Running dockerized Shaarli as a systemd service
91a21c27 131
132It 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.
133
134As root, create `/etc/systemd/system/docker.shaarli.service`:
135
136```ini
137[Unit]
138Description=Shaarli Bookmark Manager Container
139After=docker.service
140Requires=docker.service
141
142
143[Service]
144Restart=always
145
146# Put any environment you want in an included file, like $host- or $domainname in this example
147EnvironmentFile=/etc/sysconfig/box-environment
148
149# It's just an example..
150ExecStart=/usr/bin/docker run \
151 -p 28010:80 \
152 --name ${hostname}-shaarli \
153 --hostname shaarli.${domainname} \
154 -v /srv/docker-volumes-local/shaarli-data:/var/www/shaarli/data:rw \
155 -v /etc/localtime:/etc/localtime:ro \
156 shaarli/shaarli:latest
157
158ExecStop=/usr/bin/docker rm -f ${hostname}-shaarli
159
160[Install]
161WantedBy=multi-user.target
162```
163
164```bash
165# reload systemd services definitions
166systemctl daemon-reload
167# start the servie and enable it a boot time
168systemctl enable docker.shaarli.service --now
169# verify that the service is running
170systemctl status docker.*
171# inspect system log if needed
172journalctl -f
173```
174
175
176
177## Docker cheatsheet
178
179```bash
180# pull/update an image
97870f35 181$ docker pull shaarli/shaarli:release
91a21c27 182# run a container from an image
97870f35 183$ docker run shaarli/shaarli:latest
91a21c27 184# list available images
185$ docker images ls
186# list running containers
187$ docker ps
188# list running AND stopped containers
189$ docker ps -a
190# run a command in a running container
191$ docker exec -ti <container-name-or-first-letters-of-id> bash
192# follow logs of a running container
193$ docker logs -f <container-name-or-first-letters-of-id>
194# delete unused images to free up disk space
195$ docker system prune --images
196# delete unused volumes to free up disk space (CAUTION all data in unused volumes will be lost)
197$ docker system prunt --volumes
198# delete unused containers
199$ docker system prune
200```
201
202
203## References
204
205- [Docker: using volumes](https://docs.docker.com/storage/volumes/)
206- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/)
207- [Dockerfile reference](https://docs.docker.com/reference/builder/)
208- [DockerHub: GitHub automated build](https://docs.docker.com/docker-hub/github/)
209- [DockerHub: Repositories](https://docs.docker.com/userguide/dockerrepos/)
210- [DockerHub: Teams and organizations](https://docs.docker.com/docker-hub/orgs/)
211- [Get Docker CE for Debian](https://docs.docker.com/install/linux/docker-ce/debian/)
212- [Install Docker Compose](https://docs.docker.com/compose/install/)
213- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/)
214- [Service management: Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon)
215- [Service management: Using supervisord](https://docs.docker.com/articles/using_supervisord/)
216- [Volumes](https://docs.docker.com/storage/volumes/)
217- [Volumes](https://docs.docker.com/userguide/dockervolumes/)
218- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/)
219- [docker create](https://docs.docker.com/engine/reference/commandline/create/)
220- [Docker Documentation](https://docs.docker.com/)
221- [docker exec](https://docs.docker.com/engine/reference/commandline/exec/)
222- [docker images](https://docs.docker.com/engine/reference/commandline/images/)
223- [docker logs](https://docs.docker.com/engine/reference/commandline/logs/)
224- [docker logs](https://docs.docker.com/engine/reference/commandline/logs/)
225- [Docker Overview](https://docs.docker.com/engine/docker-overview/)
226- [docker ps](https://docs.docker.com/engine/reference/commandline/ps/)
227- [docker pull](https://docs.docker.com/engine/reference/commandline/pull/)
228- [docker run](https://docs.docker.com/engine/reference/commandline/run/)
229- [docker-compose logs](https://docs.docker.com/compose/reference/logs/)
b7c50a58 230- 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/)