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.
- 1 Introduction
- 2 Docker installation
- 3 Data container
- 4 Running the backend
- 5 Running jp or Primitivus
- 6 Running Libervia
- 7 General information
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:
- 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
- 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).
Please follow official documentation to see how to install Docker on your platform: .
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 firstname.lastname@example.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).
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
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:
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.
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"
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
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:
You can see the ports used with
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
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
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:
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.
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.
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:
On next start or restart, the port 8000 will then be used for HTTP.
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.
You can check the status of Libervia with the following command:
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
the optional --no-stream argument will just show the last statistics instead of display them continuously.
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).
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
Docker has several useful features. To get help, just enter:
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:
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: