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://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/)