Overview
This thread is about how to build and run images of the UCS wallet in docker/podman containers. Containers add additional layers of security: the whole setup is contained and when used correctly the access on the wallet data is further restricted. Beside docker these Dockerfiles and the related scripts can also be used to build and run podman containers. All commands assume that you have already installed docker/podman.
Instructions for installing docker/podman are not included in this thread.
For more information on docker or podman please have a look at the official homepages. A PDF version of this thread (“Docker Setup”) can be found in the download section of the official webpage (here).
A Dockerfile for each type of node
The following instructions are for building and running an alpine linux (alpine:latest) based docker image containing the latest version of the Universal Credit System Wallet (ucs_client.sh). The provided Dockerfiles are used to create the images. There are four node types and there is a separate Dockerfile for each node type. In addition there are server images for each node type having the features UCA LINK, Webapi and Webwallet enabled.
Here is a list of all available Dockerfiles:
docker/Dockerfile_client_full_archival.txt
docker/Dockerfile_client_full.txt
docker/Dockerfile_client_light_archival.txt
docker/Dockerfile_client_light.txt
docker/Dockerfile_server_full_archival_sync.txt
docker/Dockerfile_server_full_archival_sync_webapi.txt
docker/Dockerfile_server_full_archival_sync_webapi_webwallet.txt
docker/Dockerfile_server_full_archival_sync_webwallet.txt
docker/Dockerfile_server_full_archival_webapi.txt
docker/Dockerfile_server_full_archival_webapi_webwallet.txt
docker/Dockerfile_server_full_archival_webwallet.txt
docker/Dockerfile_server_full_sync.txt
docker/Dockerfile_server_full_sync_webapi.txt
docker/Dockerfile_server_full_sync_webapi_webwallet.txt
docker/Dockerfile_server_full_sync_webwallet.txt
docker/Dockerfile_server_full_webapi.txt
docker/Dockerfile_server_full_webapi_webwallet.txt
docker/Dockerfile_server_full_webwallet.txt
docker/Dockerfile_server_light_archival_sync.txt
docker/Dockerfile_server_light_archival_sync_webapi.txt
docker/Dockerfile_server_light_archival_sync_webapi_webwallet.txt
docker/Dockerfile_server_light_archival_sync_webwallet.txt
docker/Dockerfile_server_light_archival_webapi.txt
docker/Dockerfile_server_light_archival_webapi_webwallet.txt
docker/Dockerfile_server_light_archival_webwallet.txt
docker/Dockerfile_server_light_sync.txt
docker/Dockerfile_server_light_sync_webapi.txt
docker/Dockerfile_server_light_sync_webapi_webwallet.txt
docker/Dockerfile_server_light_sync_webwallet.txt
docker/Dockerfile_server_light_webapi.txt
docker/Dockerfile_server_light_webapi_webwallet.txt
docker/Dockerfile_server_light_webwallet.txt
The client images (Dockerfile_client_) expect user input while the server images (Dockerfile_server_) are meant to run as service. Along with the Dockerfiles comes a set of scripts to support you in the build and deployment process:
| script | explanation |
|---|---|
| docker_access.sh | access running container via exec command and start a shell |
| docker_build.sh | build docker images |
| docker_export_volume.sh | export the persistent storage (volume) used by the docker container as tar-file |
| docker_inspect.sh | remove the persistent storage (volume) used by the docker container |
| docker_launch.sh | run the container and start GUI mode (not for sync or webwallet images) |
| docker_remove_volume.sh | remove the persistent storage (volume) used by the docker container |
| docker_run.sh | run containers in detached mode (for sync and webwallet images) |
Instructions
When building the image a folder /home/ucs_node owned and exclusively accessible by a special user named ‘ucs_node’ will be created that contains the installation of the wallet (see Dockerfiles). The image mounts a docker volume (‘ucs_client’,‘-v ucs_client:/home/ucs_node’) as persistent storage for all wallet related data.
Not all images start up with ucs_node as user! If not you first have to switch the user before you can call ucs_client.sh directly on operating system level. This is required to avoid that user root creates write protected files inside the wallet directory that cannot be removed or modified by the designated wallet user ucs_node :
| Image type | Startup user | run ./ucs_client.sh |
|---|---|---|
| normal / client | ucs_node | Yes |
| sync | ucs_node | Yes |
| webapi | root | No, switch to ucs_node first: su – ucs_node -c ./ucs_client.sh |
| webwallet | root | No, switch to ucs_node first: su – ucs_node -c ./ucs_client.sh |
| sync+webapi | root | No, switch to ucs_node first: su – ucs_node -c ./ucs_client.sh |
| sync+webwallet | root | No, switch to ucs_node first: su – ucs_node -c ./ucs_client.sh |
| sync+webapi+webwallet | root | No, switch to ucs_node first: su – ucs_node -c ./ucs_client.sh |
Unpack the docker components
Unpack the docker components using tar:
tar -xvf docker.tar
The files are extracted into the subfolder docker/. Step into this directory
cd docker/
Build the image
Execute the script docker_build.sh (you may have to use sudo in front):
sudo ./docker_build.sh
You now have to select a Dockerfile for the Build.
Run the Container (not for sync/webapi/webwallet images)
To run the image of ucs_client in GUI mode execute the script docker_launch.sh (you may have to use sudo in front):
sudo ./docker_launch.sh
You now have to select a image to run as container. The main menu screen of the wallet will be displayed awaiting user input.
To run the container in CMD mode you need to execute docker run and handover a command that is being passed through to the image:
docker run -v ucs_client:/var/ucs/wallet -v ucs_client:/home/ucs_node/ -it IMG_ID COMMAND
Run the Container (sync/webapi/webwallet images only)
Execute the script docker_run.sh (you may have to use sudo in front):
sudo ./docker_run.sh
You now have to select a image to run as container.
Inspect the Container
Execute the script docker_inspect.sh (you may have to use sudo in front):
sudo ./docker_inspect.sh
You now have to select a image to run as container. This script will overwrite the image’s CMD instruction and handover a interactive shell inside the container. As a consequence the images CMD will be overwritten and won’t startup the way they normally do. For normal client images this means ucs_client.sh doesn’t start up at all, while for all other image types this is not a problem since only logfiles are being displayed and the processes are running in the background:
| Image type | CMD overwritten |
|---|---|
| normal / client | /var/ucs/wallet/ucs_client.sh |
| sync | tail -f /home/ucs_node/wallet/log/server.log /home/ucs_node/wallet/log/receiver.log /home/ucs_node/wallet/log/sender.log |
| webapi | tail -f /var/log/nginx/access.log |
| webwallet | tail -f /var/log/nginx/access.log |
| sync+webapi | tail -f /home/ucs_node/wallet/log/server.log /var/log/nginx/access.log |
| sync+webwallet | tail -f /home/ucs_node/wallet/log/server.log /var/log/nginx/access.log |
| sync+webapi+webwallet | tail -f /home/ucs_node/wallet/log/server.log /var/log/nginx/access.log |
Export the Volume
A docker volume is used as persistent storage. You can export the content of this volume for backup purposes by running docker_export_volume.sh (you may have to use sudo in front):
sudo ./docker_export_volume.tar
Because of data integrity of the tar-file it is highly desirable to export only volumes that are not used by running containers.
Remove the Volume
A docker volume is used as persistent storage. You can delete the volume using docker_remove_volume.sh (you may have to use sudo in front):
sudo ./docker_remove_volume.tar