]>
Commit | Line | Data |
---|---|---|
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 | ||
7 | 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/): | |
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 | |
17 | curl -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 | |
24 | root@stretch-shaarli-02:~$ docker run hello-world | |
25 | ``` | |
26 | ||
27 | ||
28 | ## Get and run a Shaarli image | |
29 | ||
30 | Shaarli images are available on [DockerHub](https://hub.docker.com/r/shaarli/shaarli/): | |
31 | ||
32 | - `latest`: latest branch | |
33 | - `master`: master branch | |
34 | ||
35 | These 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 | ||
41 | 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/). | |
42 | ||
43 | ```bash | |
44 | # download the 'latest' image from dockerhub | |
45 | docker pull shaarli/shaarli | |
46 | ||
47 | # create persistent data volumes/directories on the host | |
48 | docker volume create shaarli-data | |
49 | docker 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) | |
57 | docker 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 | |
66 | docker ps | grep myshaarli | |
67 | ||
68 | # to completely remove the container | |
69 | docker stop myshaarli # stop the running container | |
70 | docker ps | grep myshaarli # verify the container is no longer running | |
71 | docker ps -a | grep myshaarli # verify the container is stopped | |
72 | docker rm myshaarli # destroy the container | |
73 | docker ps -a | grep myshaarli # verify th container has been destroyed | |
74 | ||
75 | ``` | |
76 | ||
77 | ## Docker Compose | |
78 | ||
79 | A [Compose file](https://docs.docker.com/compose/compose-file/) is a common format for defining and running multi-container Docker applications. | |
80 | ||
81 | 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/). | |
82 | ||
83 | 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. | |
84 | ||
85 | Download docker-compose from the [release page](https://docs.docker.com/compose/install/): | |
86 | ||
87 | ```bash | |
88 | $ 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 | |
89 | $ sudo chmod +x /usr/local/bin/docker-compose | |
90 | # create a new directory to store the configuration: | |
91 | $ mkdir shaarli && cd shaarli | |
92 | # Download the current version of Shaarli's docker-compose.yml | |
93 | $ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/master/docker-compose.yml -o docker-compose.yml | |
94 | # Create the .env file and fill in your VPS and domain information | |
95 | # (replace <MY_SHAARLI_DOMAIN> and <MY_CONTACT_EMAIL> with your actual information) | |
96 | $ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' > .env | |
97 | $ echo 'SHAARLI_LETSENCRYPT_EMAIL=admin@mydomain.org' >> .env | |
98 | # Pull the Docker images | |
99 | $ docker-compose pull | |
100 | # Run! | |
101 | $ docker-compose up -d | |
102 | ``` | |
103 | ||
104 | ||
105 | ||
106 | ### Running dockerized Shaarli as a systemd service | |
107 | ||
108 | 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. | |
109 | ||
110 | As root, create `/etc/systemd/system/docker.shaarli.service`: | |
111 | ||
112 | ```ini | |
113 | [Unit] | |
114 | Description=Shaarli Bookmark Manager Container | |
115 | After=docker.service | |
116 | Requires=docker.service | |
117 | ||
118 | ||
119 | [Service] | |
120 | Restart=always | |
121 | ||
122 | # Put any environment you want in an included file, like $host- or $domainname in this example | |
123 | EnvironmentFile=/etc/sysconfig/box-environment | |
124 | ||
125 | # It's just an example.. | |
126 | ExecStart=/usr/bin/docker run \ | |
127 | -p 28010:80 \ | |
128 | --name ${hostname}-shaarli \ | |
129 | --hostname shaarli.${domainname} \ | |
130 | -v /srv/docker-volumes-local/shaarli-data:/var/www/shaarli/data:rw \ | |
131 | -v /etc/localtime:/etc/localtime:ro \ | |
132 | shaarli/shaarli:latest | |
133 | ||
134 | ExecStop=/usr/bin/docker rm -f ${hostname}-shaarli | |
135 | ||
136 | [Install] | |
137 | WantedBy=multi-user.target | |
138 | ``` | |
139 | ||
140 | ```bash | |
141 | # reload systemd services definitions | |
142 | systemctl daemon-reload | |
143 | # start the servie and enable it a boot time | |
144 | systemctl enable docker.shaarli.service --now | |
145 | # verify that the service is running | |
146 | systemctl status docker.* | |
147 | # inspect system log if needed | |
148 | journalctl -f | |
149 | ``` | |
150 | ||
151 | ||
152 | ||
153 | ## Docker cheatsheet | |
154 | ||
155 | ```bash | |
156 | # pull/update an image | |
157 | $ docker pull shaarli:release | |
158 | # run a container from an image | |
159 | $ docker run shaarli:latest | |
160 | # list available images | |
161 | $ docker images ls | |
162 | # list running containers | |
163 | $ docker ps | |
164 | # list running AND stopped containers | |
165 | $ docker ps -a | |
166 | # run a command in a running container | |
167 | $ docker exec -ti <container-name-or-first-letters-of-id> bash | |
168 | # follow logs of a running container | |
169 | $ docker logs -f <container-name-or-first-letters-of-id> | |
170 | # delete unused images to free up disk space | |
171 | $ docker system prune --images | |
172 | # delete unused volumes to free up disk space (CAUTION all data in unused volumes will be lost) | |
173 | $ docker system prunt --volumes | |
174 | # delete unused containers | |
175 | $ docker system prune | |
176 | ``` | |
177 | ||
178 | ||
179 | ## References | |
180 | ||
181 | - [Docker: using volumes](https://docs.docker.com/storage/volumes/) | |
182 | - [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/) | |
183 | - [Dockerfile reference](https://docs.docker.com/reference/builder/) | |
184 | - [DockerHub: GitHub automated build](https://docs.docker.com/docker-hub/github/) | |
185 | - [DockerHub: Repositories](https://docs.docker.com/userguide/dockerrepos/) | |
186 | - [DockerHub: Teams and organizations](https://docs.docker.com/docker-hub/orgs/) | |
187 | - [Get Docker CE for Debian](https://docs.docker.com/install/linux/docker-ce/debian/) | |
188 | - [Install Docker Compose](https://docs.docker.com/compose/install/) | |
189 | - [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/) | |
190 | - [Service management: Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon) | |
191 | - [Service management: Using supervisord](https://docs.docker.com/articles/using_supervisord/) | |
192 | - [Volumes](https://docs.docker.com/storage/volumes/) | |
193 | - [Volumes](https://docs.docker.com/userguide/dockervolumes/) | |
194 | - [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/) | |
195 | - [docker create](https://docs.docker.com/engine/reference/commandline/create/) | |
196 | - [Docker Documentation](https://docs.docker.com/) | |
197 | - [docker exec](https://docs.docker.com/engine/reference/commandline/exec/) | |
198 | - [docker images](https://docs.docker.com/engine/reference/commandline/images/) | |
199 | - [docker logs](https://docs.docker.com/engine/reference/commandline/logs/) | |
200 | - [docker logs](https://docs.docker.com/engine/reference/commandline/logs/) | |
201 | - [Docker Overview](https://docs.docker.com/engine/docker-overview/) | |
202 | - [docker ps](https://docs.docker.com/engine/reference/commandline/ps/) | |
203 | - [docker pull](https://docs.docker.com/engine/reference/commandline/pull/) | |
204 | - [docker run](https://docs.docker.com/engine/reference/commandline/run/) | |
205 | - [docker-compose logs](https://docs.docker.com/compose/reference/logs/) | |
206 | - 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/) |