Docker/en

De Goffiwiki
Aller à : navigation, rechercher


This page describes the installation of Salut à Toi with Docker.

Note: if you want to quickly launch and try Libervia, you can use directly the libervia container managing script, it will download and run everything automatically and easily.

Introduction

Docker is a tool to manage lightweight containers; it makes the installation of SàT easy on GNU/Linux-based platforms (or on other platforms, using a GNU/Linux virtual machine running Docker).

Using Docker has advantages and disadvantages:

PROS

  • it's easy to install
  • apps are isolated, which is more secure (it's more difficult for an attacker to take profit of a security bug)
  • it doesn't take a lot of CPU/RAM resources (similar to native application, with very little overhead)
  • the containers should work the same way everywhere
  • it's trivial and efficient to commit changes and revert to a previous image

CONS

  • the app is less integrated than a native app. In particular, you can't access easily the host's file system (in our case, it's annoying to send a file through a SàT frontend)
  • it uses more disk space than native apps, as a basic GNU/Linux distribution is needed in the Docker image (but if the same base is used on several containers, it's reused)
  • updates are a bit more complicated than using your distribution's native tools

It's especially useful if you want to give a quick try to SàT/one of its frontends, or if you want to have an easy way to deploy isolated version of Libervia. If you want to use a frontend locally we recommend to use native apps because the integration will be better (X notifications, possibility to send files, etc).

Docker installation

Please follow official documentation to see how to install Docker on your platform: [1].

Note that Docker can be available on non GNU/Linux platforms through Boot2Docker and/or Vagrant or other virtual machine software.

Note also that images available on docker hub (i.e. the ones you'll get here) are for 64 bits GNU/Linux. If you want to build on a other architecture, ask us for help on sat@chat.jabberfr.org XMPP room.

You may need to add your user to the docker group; on Debian use this command (as root):

adduser your_user docker

Then logout/login again, restart your X session, or use the newgrp docker command (or just restart your computer if you're not sure).

Data container

Note: these instructions are not needed if you use the Libervia container manager script (see below)

To keep persistent data, an image has been specially made to create data container. To launch it, just enter:

docker run --name sat_data salutatoi/data

It is is not mandatory to use this image, but it make things easy if you want to keep data after stopping the containers.

This image can be used in other containers with the --volumes-from=sat_data option. Do not remove this container if data are not saved! It would remove all persistent data.

To save data, you can use:

docker run --rm --volumes-from sat_data -v $(pwd):/backup debian:jessie tar zcvf /backup/your_backup_file.tar.gz -C / -h volumes

This is done by the Libervia container manager script (see below).

Running the backend

Note: these instructions are not needed if you use the Libervia container manager script (see below)

To download/run the backend, just enter this:

docker run -d --name sat -ti --volumes-from sat_data salutatoi/sat:latest

SàT's backend will then run in the background.

  • the -d option detach the container.
  • The --name sat is important, as it will allow to link this container to the frontends' ones.
  • the -ti option allow pseudo-terminal/interactive
  • the --volumes-from sat_data use sat_data to keep persistent data (sat_data must be launched before of course)

Running jp or Primitivus

To run jp or Primitivus, the command is similar, but you need to link to the backend with the alias "sat" (of course the backend container must be run before any frontend container).

jp

As jp has a command line interface, you may need to use the "-t" (pseudo-tty) and "-i" (interactive) options:

docker run --rm -ti --link sat:sat salutatoi/jp:latest

We recommend to create an alias:

alias jp-docker="docker run --rm -ti --link sat:sat salutatoi/jp:latest"

To check if it's working, you can do:

jp-docker --version

You should see something like:

jp 0.6.0D (repository data unknown) Copyright (C) 2009-2016 Jérôme Poisson, Adrien Cossa
This program comes with ABSOLUTELY NO WARRANTY;
This is free software, and you are welcome to redistribute it under certain conditions.

Primitivus

As Primitivus is a console interface, you need to use the "-t" (pseudo-tty) and "-i" (interactive) options:

docker run --rm -ti --link sat:sat salutatoi/primitivus:latest

Here also, we recommend to create an alias:

alias primitivus-docker="docker run --rm -ti --link sat:sat salutatoi/primitivus:latest"

Running Libervia

Libervia container manager script

Libervia need to use several containers and a version of Prosody specially prepared for it. A script has been written to manage everything easily (download/start/stop/update/backup/etc). You can download it here:

To download and make it executable, just do:

wget https://repos.goffi.org/sat_docs/raw-file/tip/docker/libervia_cont.sh && chmod a+x libervia_cont.sh

Once docker is installed, you can directly launch ./libervia_cont.sh, it will download and start libervia and show you instructions, including the HTTP port to use with your browser to try it (if the displayed IP address is 0.0.0.0, just replace it with localhost or 127.0.0.1).

To see the admin account's password, type:

docker start --rm --volumes-from sat_data debian:jessie cat /home/sat/ADMIN_PWD

You can also use options. To see them, enter

./libervia_cont.sh start --help

2 options are importants:

-p or --public 
use same ports as in container, and expose all ports, this is needed for an installation available to public.
-d DOMAIN or --domain DOMAIN 
use the domain indicated, default to libervia.int. The SAT_CONT_DOMAIN environment variable can also be used

For example, if you want to use mylibervia.int as domain, you can enter:

./libervia_cont.sh start -p -d mylibervia.int

To stop Libervia, just enter

./libervia_cont.sh stop

Note that all containers except sat_data will be removed. Do NOT remove sat_data if you have no backup and you want to keep persistent data.

To update the container, use:

./libervia_cont.sh update

You can see the ports used with

./libervia_cont.sh ports

This is also displayed at the end of the start command.

Backup and restore

To backup data, just enter:

./libervia_cont.sh backup [save_path]

This will create a backup tar.gz with the current date/time. save_path can be optionally specified, it default to current working directory. The SAT_CONT_BACKUP_DIR can also be used to specified the backup directory.

To restore later the backup, simply enter

./libervia_cont.sh restore sat_data_backup_<backup_date_time>.tar.gz

You must not have any sat_data container running, as a new one will be created with the backup

Changing configuration

By default a configuration is done to try quickly Libervia, with a HTTP and HTTPS servers and self-signed certificate (generated on first launch).

But you may want to tune the configuration, to do so, it's easy, just enter

./libervia_cont.sh config

This will launch your editor with the container configuration of SàT/Libervia (the sat.conf file). To use this configuration, you can restart the containers after edition:

./libervia_cont.sh restart

You can optionally use some options after restart which will be passed to the start command (e.g. -p to have public ports).

You may also want to change Prosody configuration, to do so, just enter

./libervia_conf.sh config prosody

You'll may have to restart the container like for sat.conf

Using you own certificate

To use your own certificate for Prosody and Libervia's HTTPS server, you can use the SAT_CONT_TLS_DIR environment variable, with the absolute path to the dir where your private key and public certificates are.

export SAT_CONT_TLS_DIR=/path/to/your/certificate_dir/

By defaut Prosody and Libervia look for "libervia.key" for the private key and "libervia.crt" for the public certificate, but this can be changed using "./libervia_conf.sh config [libervia|prosody]" like explained above.

Note that the certificates need to be accessible by Prosody and Libervia. You have two ways to do that:

  • you may let have them accessible publicly (not secure option because your private key could be read by anybody on your machine),
  • or you may make them accessible only to the group id "9999" which correspond to the "tls_cert" group in containers.

As an alternative, you can also put your certificate/private key in the /usr/share/sat/certificates directory of your sat_data container.

Specifying ports

When using public option (-p) it may be desirable to use other ports than the exposed ones. This is done by using the SAT_CONT_PORT_<port> environment variable where <port> correspond to the port you want to change.

For instance, if you want to use port 8000 instead of 8080 for libervia's HTTP server, you just have to export SAT_CONT_PORT_8080 like this:

export SAT_CONT_PORT_8080=8000

On next start or restart, the port 8000 will then be used for HTTP.

Docker arguments

Custom Docker arguments can be passed to all containers (but sat_data) by using the SAT_CONT_DK_EXTRA environment variable. This can be used e.g. to mount a host directory:

export SAT_CONT_DK_EXTRA="-v ~/photos:/photos:ro"

would mount your ~/photo directory to /photos in container in read-only mode. See docker help run or man docker-run for more informations.

Misc

You can check the status of Libervia with the following command:

./libervia_cont.sh status

You'll have a message giving the status to you with the following exit code:

  • 0: the service is running normally
  • 1: the service is not running
  • 2: the container exists, but no HTTP or HTTPS server is available

You can also have resource statistics on containers using

./libervia_cont.sh stats

the optional --no-stream argument will just show the last statistics instead of display them continuously.

General information

Getting logs

Docker has a command to easily get logs, so to get backend logs, you can just type:

docker logs sat

Of course, this also works with other container (libervia, prosody, etc).

Environment variables

You can pass environment variable to SàT backend or frontends when running it with the "-e" option. For example, to have debug logs on the backend, use:

docker run -d --name sat -e SAT_LOG_LEVEL=debug salutatoi/sat:latest

Tips

Docker has several useful features. To get help, just enter:

docker help

or:

docker help [command]

You can commit the current state of a container to a new image by doing something like:

docker commit sat

This is especially useful before doing an update, to revert state in case of regression.

/!\ Beware: a volume container (i.e. sat_data) can't be committed, use libervia_cont.sh backup instead.

You can stop/pause/unpause/restart and kill a container, e.g.:

docker stop sat

You can get a list of currently running containers:

docker ps

Or all the containers:

docker ps -a

Make sure to understand the difference between an image and a container: an image is the base of a container, when you commit the state of a container, you get a new image. You can check docker documentation to better understand.

To get a list of the images, just do:

docker images