From 97870f35121bed42ac126652d81bc43416b44356 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Thu, 3 Sep 2020 11:58:09 +0200 Subject: doc: Docker minor improvements --- doc/md/Docker.md | 59 ++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 40 insertions(+), 19 deletions(-) diff --git a/doc/md/Docker.md b/doc/md/Docker.md index 3640ef26..c152fe92 100644 --- a/doc/md/Docker.md +++ b/doc/md/Docker.md @@ -4,33 +4,45 @@ ## Install Docker -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/): +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/): ```bash # update your package lists -$ sudo apt update +sudo apt update # remove old versions -$ sudo apt-get remove docker docker-engine docker.io containerd runc +sudo apt-get remove docker docker-engine docker.io containerd runc # install requirements -$ sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common +sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common # add docker's GPG signing key curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add - # add the repository -$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" +sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" # install docker engine -$ sudo apt-get update -$ sudo apt-get install docker-ce docker-ce-cli containerd.io +sudo apt-get update +sudo apt-get install docker-ce docker-ce-cli containerd.io +# Start and enable Docker service +sudo systemctl enable docker && sudo systemctl start docker # verify that Docker is properly configured -root@stretch-shaarli-02:~$ docker run hello-world +sudo docker run hello-world ``` +In order to run Docker commands as a non-root user, you must add the `docker` group to this user: + +```bash +# Add docker group as secondary group +sudo usermod -aG docker your-user +# Reboot or logout +# Then verify that Docker is properly configured, as "your-user" +docker run hello-world +``` ## Get and run a Shaarli image -Shaarli images are available on [DockerHub](https://hub.docker.com/r/shaarli/shaarli/): +Shaarli images are available on [DockerHub](https://hub.docker.com/r/shaarli/shaarli/) `shaarli/shaarli`: -- `latest`: latest branch -- `master`: master branch +- `latest`: latest branch (last release) +- `stable`: stable branch (last release in previous major version) +- `master`: master branch (development branch) These images are built automatically on DockerHub and rely on: @@ -40,6 +52,8 @@ These images are built automatically on DockerHub and rely on: 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/). +Here is an example of how to run Shaarli latest image using Docker: + ```bash # download the 'latest' image from dockerhub docker pull shaarli/shaarli @@ -60,7 +74,7 @@ docker run --detach \ --rm \ --volume shaarli-data:/var/www/shaarli/data \ --volume shaarli-cache:/var/www/shaarli/cache \ - shaarli/shaarli + shaarli/shaarli:latest # verify that the container is running docker ps | grep myshaarli @@ -74,23 +88,30 @@ docker ps -a | grep myshaarli # verify th container has been destroyed ``` +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. + ## Docker Compose A [Compose file](https://docs.docker.com/compose/compose-file/) is a common format for defining and running multi-container Docker applications. 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/). -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. +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. Download docker-compose from the [release page](https://docs.docker.com/compose/install/): ```bash $ 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 $ sudo chmod +x /usr/local/bin/docker-compose +``` + +To run Shaarli container and its reverse proxy, you can execute the following commands: + +```bash # create a new directory to store the configuration: $ mkdir shaarli && cd shaarli -# Download the current version of Shaarli's docker-compose.yml -$ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/master/docker-compose.yml -o docker-compose.yml +# Download the latest version of Shaarli's docker-compose.yml +$ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/latest/docker-compose.yml -o docker-compose.yml # Create the .env file and fill in your VPS and domain information # (replace and with your actual information) $ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' > .env @@ -101,9 +122,9 @@ $ docker-compose pull $ docker-compose up -d ``` +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). - -### Running dockerized Shaarli as a systemd service +## Running dockerized Shaarli as a systemd service 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. @@ -154,9 +175,9 @@ journalctl -f ```bash # pull/update an image -$ docker pull shaarli:release +$ docker pull shaarli/shaarli:release # run a container from an image -$ docker run shaarli:latest +$ docker run shaarli/shaarli:latest # list available images $ docker images ls # list running containers -- cgit v1.2.3