4 [Docker](https://docs.docker.com/get-started/overview/) is an open platform for developing, shipping, and running applications
8 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/):
11 # update your package lists
14 sudo apt-get remove docker docker-engine docker.io containerd runc
15 # install requirements
16 sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common
17 # add docker's GPG signing key
18 curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
20 sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
21 # install docker engine
23 sudo apt-get install docker-ce docker-ce-cli containerd.io
24 # Start and enable Docker service
25 sudo systemctl enable docker && sudo systemctl start docker
26 # verify that Docker is properly configured
27 sudo docker run hello-world
30 In order to run Docker commands as a non-root user, you must add the `docker` group to this user:
33 # Add docker group as secondary group
34 sudo usermod -aG docker your-user
36 # Then verify that Docker is properly configured, as "your-user"
37 docker run hello-world
40 ## Get and run a Shaarli image
42 Shaarli images are available on [DockerHub](https://hub.docker.com/r/shaarli/shaarli/) `shaarli/shaarli`:
44 - `latest`: latest branch (last release)
45 - `stable`: stable branch (last release in previous major version)
46 - `master`: master branch (development branch)
48 These images are built automatically on DockerHub and rely on:
50 - [Alpine Linux](https://www.alpinelinux.org/)
51 - [PHP7-FPM](http://php-fpm.org/)
52 - [Nginx](http://nginx.org/)
54 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/).
56 Here is an example of how to run Shaarli latest image using Docker:
59 # download the 'latest' image from dockerhub
60 docker pull shaarli/shaarli
62 # create persistent data volumes/directories on the host
63 docker volume create shaarli-data
64 docker volume create shaarli-cache
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)
76 --volume shaarli-data:/var/www/shaarli/data \
77 --volume shaarli-cache:/var/www/shaarli/cache \
78 shaarli/shaarli:latest
80 # verify that the container is running
81 docker ps | grep myshaarli
83 # to completely remove the container
84 docker stop myshaarli # stop the running container
85 docker ps | grep myshaarli # verify the container is no longer running
86 docker ps -a | grep myshaarli # verify the container is stopped
87 docker rm myshaarli # destroy the container
88 docker ps -a | grep myshaarli # verify th container has been destroyed
92 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.
96 A [Compose file](https://docs.docker.com/compose/compose-file/) is a common format for defining and running multi-container Docker applications.
98 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/).
100 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.
102 Download docker-compose from the [release page](https://docs.docker.com/compose/install/):
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
106 $ sudo chmod +x /usr/local/bin/docker-compose
109 To run Shaarli container and its reverse proxy, you can execute the following commands:
112 # create a new directory to store the configuration:
113 $ mkdir shaarli && cd shaarli
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
116 # Create the .env file and fill in your VPS and domain information
117 # (replace <shaarli.mydomain.org>, <admin@mydomain.org> and <latest> with your actual information)
118 $ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' > .env
119 $ echo 'SHAARLI_LETSENCRYPT_EMAIL=admin@mydomain.org' >> .env
120 # Available Docker tags can be found at https://hub.docker.com/r/shaarli/shaarli/tags
121 $ echo 'SHAARLI_DOCKER_TAG=latest' >> .env
122 # Pull the Docker images
123 $ docker-compose pull
125 $ docker-compose up -d
128 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).
130 ## Running dockerized Shaarli as a systemd service
132 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.
134 As root, create `/etc/systemd/system/docker.shaarli.service`:
138 Description=Shaarli Bookmark Manager Container
140 Requires=docker.service
146 # Put any environment you want in an included file, like $host- or $domainname in this example
147 EnvironmentFile=/etc/sysconfig/box-environment
149 # It's just an example..
150 ExecStart=/usr/bin/docker run \
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
158 ExecStop=/usr/bin/docker rm -f ${hostname}-shaarli
161 WantedBy=multi-user.target
165 # reload systemd services definitions
166 systemctl daemon-reload
167 # start the servie and enable it a boot time
168 systemctl enable docker.shaarli.service --now
169 # verify that the service is running
170 systemctl status docker.*
171 # inspect system log if needed
180 # pull/update an image
181 $ docker pull shaarli/shaarli:release
182 # run a container from an image
183 $ docker run shaarli/shaarli:latest
184 # list available images
186 # list running containers
188 # list running AND stopped containers
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
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/)
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/)