aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md
diff options
context:
space:
mode:
authorArthurHoaro <arthur@hoa.ro>2020-09-03 11:58:09 +0200
committernodiscc <nodiscc@gmail.com>2020-09-12 14:31:45 +0200
commit97870f35121bed42ac126652d81bc43416b44356 (patch)
treeb26f77ec59b7c25800599d751212db72cfc65870 /doc/md
parent68855686dbbc734003581524b45cb26240917dad (diff)
downloadShaarli-97870f35121bed42ac126652d81bc43416b44356.tar.gz
Shaarli-97870f35121bed42ac126652d81bc43416b44356.tar.zst
Shaarli-97870f35121bed42ac126652d81bc43416b44356.zip
doc: Docker minor improvements
Diffstat (limited to 'doc/md')
-rw-r--r--doc/md/Docker.md59
1 files 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 @@
4 4
5## Install Docker 5## Install Docker
6 6
7Install [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/): 7Install [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 8
9```bash 9```bash
10# update your package lists 10# update your package lists
11$ sudo apt update 11sudo apt update
12# remove old versions 12# remove old versions
13$ sudo apt-get remove docker docker-engine docker.io containerd runc 13sudo apt-get remove docker docker-engine docker.io containerd runc
14# install requirements 14# install requirements
15$ sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common 15sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common
16# add docker's GPG signing key 16# add docker's GPG signing key
17curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add - 17curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
18# add the repository 18# add the repository
19$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" 19sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
20# install docker engine 20# install docker engine
21$ sudo apt-get update 21sudo apt-get update
22$ sudo apt-get install docker-ce docker-ce-cli containerd.io 22sudo apt-get install docker-ce docker-ce-cli containerd.io
23# Start and enable Docker service
24sudo systemctl enable docker && sudo systemctl start docker
23# verify that Docker is properly configured 25# verify that Docker is properly configured
24root@stretch-shaarli-02:~$ docker run hello-world 26sudo docker run hello-world
25``` 27```
26 28
29In 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
33sudo usermod -aG docker your-user
34# Reboot or logout
35# Then verify that Docker is properly configured, as "your-user"
36docker run hello-world
37```
27 38
28## Get and run a Shaarli image 39## Get and run a Shaarli image
29 40
30Shaarli images are available on [DockerHub](https://hub.docker.com/r/shaarli/shaarli/): 41Shaarli images are available on [DockerHub](https://hub.docker.com/r/shaarli/shaarli/) `shaarli/shaarli`:
31 42
32- `latest`: latest branch 43- `latest`: latest branch (last release)
33- `master`: master branch 44- `stable`: stable branch (last release in previous major version)
45- `master`: master branch (development branch)
34 46
35These images are built automatically on DockerHub and rely on: 47These images are built automatically on DockerHub and rely on:
36 48
@@ -40,6 +52,8 @@ These images are built automatically on DockerHub and rely on:
40 52
41Additional 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/). 53Additional 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 54
55Here is an example of how to run Shaarli latest image using Docker:
56
43```bash 57```bash
44# download the 'latest' image from dockerhub 58# download the 'latest' image from dockerhub
45docker pull shaarli/shaarli 59docker pull shaarli/shaarli
@@ -60,7 +74,7 @@ docker run --detach \
60 --rm \ 74 --rm \
61 --volume shaarli-data:/var/www/shaarli/data \ 75 --volume shaarli-data:/var/www/shaarli/data \
62 --volume shaarli-cache:/var/www/shaarli/cache \ 76 --volume shaarli-cache:/var/www/shaarli/cache \
63 shaarli/shaarli 77 shaarli/shaarli:latest
64 78
65# verify that the container is running 79# verify that the container is running
66docker ps | grep myshaarli 80docker ps | grep myshaarli
@@ -74,23 +88,30 @@ docker ps -a | grep myshaarli # verify th container has been destroyed
74 88
75``` 89```
76 90
91After 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
77## Docker Compose 93## Docker Compose
78 94
79A [Compose file](https://docs.docker.com/compose/compose-file/) is a common format for defining and running multi-container Docker applications. 95A [Compose file](https://docs.docker.com/compose/compose-file/) is a common format for defining and running multi-container Docker applications.
80 96
81A `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/). 97A `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 98
83Shaarli 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. 99Shaarli 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.
84 100
85Download docker-compose from the [release page](https://docs.docker.com/compose/install/): 101Download docker-compose from the [release page](https://docs.docker.com/compose/install/):
86 102
87```bash 103```bash
88$ 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 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
89$ sudo chmod +x /usr/local/bin/docker-compose 105$ sudo chmod +x /usr/local/bin/docker-compose
106```
107
108To run Shaarli container and its reverse proxy, you can execute the following commands:
109
110```bash
90# create a new directory to store the configuration: 111# create a new directory to store the configuration:
91$ mkdir shaarli && cd shaarli 112$ mkdir shaarli && cd shaarli
92# Download the current version of Shaarli's docker-compose.yml 113# Download the latest version of Shaarli's docker-compose.yml
93$ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/master/docker-compose.yml -o docker-compose.yml 114$ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/latest/docker-compose.yml -o docker-compose.yml
94# Create the .env file and fill in your VPS and domain information 115# Create the .env file and fill in your VPS and domain information
95# (replace <MY_SHAARLI_DOMAIN> and <MY_CONTACT_EMAIL> with your actual information) 116# (replace <MY_SHAARLI_DOMAIN> and <MY_CONTACT_EMAIL> with your actual information)
96$ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' > .env 117$ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' > .env
@@ -101,9 +122,9 @@ $ docker-compose pull
101$ docker-compose up -d 122$ docker-compose up -d
102``` 123```
103 124
125After 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).
104 126
105 127## Running dockerized Shaarli as a systemd service
106### Running dockerized Shaarli as a systemd service
107 128
108It 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. 129It 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.
109 130
@@ -154,9 +175,9 @@ journalctl -f
154 175
155```bash 176```bash
156# pull/update an image 177# pull/update an image
157$ docker pull shaarli:release 178$ docker pull shaarli/shaarli:release
158# run a container from an image 179# run a container from an image
159$ docker run shaarli:latest 180$ docker run shaarli/shaarli:latest
160# list available images 181# list available images
161$ docker images ls 182$ docker images ls
162# list running containers 183# list running containers