doc/md/Docker.md

   1
   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
   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/):
   9
  10 ```bash
  11 # update your package lists
  12 sudo apt update
  13 # remove old versions
  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 -
  19 # add the repository
  20 sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
  21 # install docker engine
  22 sudo apt-get update
  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
  28 ```
  29
  30 In 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
  34 sudo usermod -aG docker your-user
  35 # Reboot or logout
  36 # Then verify that Docker is properly configured, as "your-user"
  37 docker run hello-world
  38 ```
  39
  40 ## Get and run a Shaarli image
  41
  42 Shaarli images are available on [DockerHub](https://hub.docker.com/r/shaarli/shaarli/) `shaarli/shaarli`:
  43
  44 - `latest`: latest branch (last release)
  45 - `stable`: stable branch (last release in previous major version)
  46 - `master`: master branch (development branch)
  47
  48 These 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
  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/).
  55
  56 Here is an example of how to run Shaarli latest image using Docker:
  57
  58 ```bash
  59 # download the 'latest' image from dockerhub
  60 docker pull shaarli/shaarli
  61
  62 # create persistent data volumes/directories on the host
  63 docker volume create shaarli-data
  64 docker 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)
  72 docker 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 \
  78            shaarli/shaarli:latest
  79
  80 # verify that the container is running
  81 docker ps | grep myshaarli
  82
  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
  89
  90 ```
  91
  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.
  93
  94 ## Docker Compose
  95
  96 A [Compose file](https://docs.docker.com/compose/compose-file/) is a common format for defining and running multi-container Docker applications.
  97
  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/).
  99
 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.
 101
 102 Download docker-compose from the [release page](https://docs.docker.com/compose/install/):
 103
 104 ```bash
 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
 107 ```
 108
 109 To run Shaarli container and its reverse proxy, you can execute the following commands:
 110
 111 ```bash
 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
 124 # Run!
 125 $ docker-compose up -d
 126 ```
 127
 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).
 129
 130 ## Running dockerized Shaarli as a systemd service
 131
 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.
 133
 134 As root, create `/etc/systemd/system/docker.shaarli.service`:
 135
 136 ```ini
 137 [Unit]
 138 Description=Shaarli Bookmark Manager Container
 139 After=docker.service
 140 Requires=docker.service
 141
 142
 143 [Service]
 144 Restart=always
 145
 146 # Put any environment you want in an included file, like $host- or $domainname in this example
 147 EnvironmentFile=/etc/sysconfig/box-environment
 148
 149 # It's just an example..
 150 ExecStart=/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
 158 ExecStop=/usr/bin/docker rm -f ${hostname}-shaarli
 159
 160 [Install]
 161 WantedBy=multi-user.target
 162 ```
 163
 164 ```bash
 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
 172 journalctl -f
 173 ```
 174
 175
 176
 177 ## Docker cheatsheet
 178
 179 ```bash
 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
 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/)
 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/)