Usage of lstu with Docker
You can build a Docker image to start
lstu in a breeze!
What is bundled with this image
The image starts an
lstu instance ready to work with a SQLite, MySQL or PostgreSQL database. It is based on alpine 3.7.
- Some knowledge of Docker
- Docker 17.06.0+
docker image: if we make a comparison with code, a docker image is like an Object class definition. Everything is declared in it and you cannot change anything. You
buildan image (from instructions).
docker container: with the same comparison, a docker container is like an instance of the previous Object. You can then interact with the object, change properties, execute methods, ... You
runa container (from an image).
- docker volumes: again with the same comparison, not saving your persistent data (sessions files, database files, ...) into a docker volume is like interacting with and object instance and not saving its state: you loose everything if you instanciate again the object. You bind a volume (directory or file) to a running container.
Build the image
You can build your own image of
lstu with this command:
docker build --pull -t myorg/lstu . (last dot is important)
There is also a convenience script that integrate the commit hash, build date and version number within the image. You can execute this script with
IMAGE_NAME=myorg/lstu ./hooks/build. This script is also used by the Docker Automated Build system.
The lstu image does not contain a valid
lstu.conf by default. So we need to setup one and then, when you run an lstu container, you need to give the file to the container, generally by binding it to the container.
So, configure lstu as you would normally (duplicate the lstu.conf.template and update it), but also update the hypnotoad's listen property to
0.0.0.0:8080 for the web server to listen to any ip/interface given by docker (because in docker, we generally don't care about ips, the Docker network stack giving a non-predictable ip at each container start. It's routing and a service-discovery mechanism that does the magic).
Then choose any of the three methods below (plain Docker, docker-compose, Docker Swarm) to start a container:
With plain Docker
You can start a container with the following command (example for a SQLite backend):
docker run -p 8080:8080 -v "$(pwd)/lstu.conf:/home/lstu/lstu.conf" -v "$(pwd)/lstu.db:/home/lstu/lstu.db" lstu
Because each time you run a container its content is replaced by the original content of the image, do not forget to set the volumes (the
-v thing) in order for their content to persist between image launches. Here we bind the config file so that the container is able to read it, but we also bind the SQLite database file so that this time the file is persistend between container restarts.
With Docker Compose, starting a database and lstu is easier than never! You can look at the
docker-compose.yml file example to start. This setup use MariaDB as database, running in a separated container.
- Duplicate the
lstu.conf.templatefile and name it
lstu.conf. This file will be used in the container as the lstu config file.
- Simply execute this command in the source directory of lstu:
The first time you launch this command, Docker will download the mariadb image and build the lstu image. It will take some time but only this first time (or when source code is changed), as later everything will be cached.
In a Docker Swarm
Like with docker-compose, you can easily start an lstu instance in a Docker Swarm with the
docker-stack.yml file. The only thing here is that we embraced the Swarm-way by externally declaring the
lstu.conf file as a Docker config for replication across nodes.
The image is also set up for bootstraping a local development environment. Simply set the container command to
dev to enter this mode (see the
docker-compose.dev.yml file). The container is then waiting for you to connect on it. The local directory is bind mounted in the container so that every change you make on your host is available in the container.
Launch the container on a first terminal
docker-compose -f docker-compose.dev.yml up
Then connect to it with the root user (by default, a restricted user is used). So, in a second terminal:
docker-compose -f docker-compose.dev.yml exec -u root app_dev sh
Go back to wiki's homepage.