# How to build and run Docker images

**URL:** <https://forum.universal-credit-system.org/t/how-to-build-and-run-docker-images/123>\
**Category:** Documents and Sources\
**Created:** [July 24, 2025, 7:31pm UTC](https://forum.universal-credit-system.org/t/how-to-build-and-run-docker-images/123 "2025-07-24T19:31:45Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![m0e](https://forum.universal-credit-system.org/user_avatar/forum.universal-credit-system.org/m0e/32/74_2.png) [@m0e](https://forum.universal-credit-system.org/u/m0e)\
**Post date:** [July 24, 2025, 7:31pm UTC](https://forum.universal-credit-system.org/t/how-to-build-and-run-docker-images/123/1 "2025-07-24T19:31:45Z")

</div>

**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](https://www.universal-credit-system.org/en/Downloads)).

**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:

```auto
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:

```auto
tar -xvf docker.tar

```

The files are extracted into the subfolder **docker/**. Step into this directory

```auto
cd docker/

```

**Build the image**

Execute the script docker\_build.sh (you may have to use sudo in front):

```auto
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):

```auto
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:

```auto
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):

```auto
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):

```auto
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):

```auto
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):

```auto
sudo ./docker_remove_volume.tar

```