doc/md/Docker.md

   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 ```bash
  86 Download 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
 109 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.
 110
 111 As root, create `/etc/systemd/system/docker.shaarli.service`:
 112
 113 ```ini
 114 [Unit]
 115 Description=Shaarli Bookmark Manager Container
 116 After=docker.service
 117 Requires=docker.service
 118
 119
 120 [Service]
 121 Restart=always
 122
 123 # Put any environment you want in an included file, like $host- or $domainname in this example
 124 EnvironmentFile=/etc/sysconfig/box-environment
 125
 126 # It's just an example..
 127 ExecStart=/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
 135 ExecStop=/usr/bin/docker rm -f ${hostname}-shaarli
 136
 137 [Install]
 138 WantedBy=multi-user.target
 139 ```
 140
 141 ```bash
 142 # reload systemd services definitions
 143 systemctl daemon-reload
 144 # start the servie and enable it a boot time
 145 systemctl enable docker.shaarli.service --now
 146 # verify that the service is running
 147 systemctl status docker.*
 148 # inspect system log if needed
 149 journalctl -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/)