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