Docker

In order to establish an Arrowhead Local Cloud with docker you will need to:

1. Pull or build one docker image for the database and one for the core systems. (one time)
2. Configure properly the core systems. (one time)
3. Create docker containers from the images for the database and core systems. (one time)
4. Start/stop the docker containers. (any time)

Docker images

You will need two images: One for creating database container(s) and one for creating core system containers.

Database image

You can pull the existing image or build your own if you want to customize the environment according to your needs.

Pull

docker pull aitiaiiot/arrowhead-database:<version>

Example

docker pull aitiaiiot/arrowhead-database:4.6.1

Build

If you not go with the pull option, then go to the project root folder and execute:

docker build -t <your-image-name> -f docker/Dockerfile-database .

-t: Labels the image with a human readable name: For example: arrowhead-database:4.6.1.
-f: Defines the path to the docker file what should be used for building the image.

Example:

docker build -t arrowhead-database:4.6.1 -f docker/Dockerfile-database .

Once it is done you will have an arrowhead database installed on Ubuntu 20.04 docker image.

To customize the mysql-server installation you may edit the /docker/Dockerfile-database.

Hint: MySQL connections configuration

Core System image

You can pull the existing image or build your own if you want to customize the environment according to your needs.

Pull

docker pull aitiaiiot/arrowhead-system:<version>

Example

docker pull aitiaiiot/arrowhead-system:4.6.1

Build

If you not go with the pull option, then go to the project root folder and execute:

docker build -t <your-image-name> -f docker/Dockerfile-system .

-t: Labels the image with a human readable name: For example: arrowhead-systems:4.6.1.
-f: Defines the path to the docker file what should be used for building the image.

Example:

docker build -t arrowhead-system:4.6.1 -f docker/Dockerfile-system .

Once it is done you will have the core systems builded on Debian 11.1 docker image with open-jdk 11.0.12.
The `/opt/arrowhead folder within the file system of the image will contain the necessary arrowhead files for one specific core system after the docker container initialization. All other unnecesarry system files will be removed during the container initialization.

Instantiate docker containers from the images

Database instance

Create a container (a database instance) from the database image with the command:

docker create --name <your-container-name> -p <host-port>:3306 -v <your-volume-name>:/var/lib/mysql <your-image-name>

--name: Gives a human readable name to the container. For example: arrowhead-database-mycloud1.
-p: Binds a port on the host machine to a container port in order to being accessable from outside of the container.
-v: Defines a volume in order to keep the database data persistent. In our case docker will store the database files in the host machine typically under /var/lib/docker/volumes/ folder in case of linux distributions.

Example:

docker create --name arrowhead-database-mycloud1 -p 3306:3306 -v arrowhead-database-mycloud1:/var/lib/mysql arrowhead-database:4.6.1

This way you can create as much runnable database containers for as much different arrowhead cloud instances as it is necessary.

To start the container use the following command:

docker start <your-container-name>

Example:

docker start arrowhead-database-mycloud1

Hint: Customize core systems mysql user passwords in a docker container

Core System instance

At this stage the image contains the default core system configurations, which should be owerwritten for a specific container instance:

Customize application.properties config file

The default application.properties files are located in the /src/main/resources folder. Copy the property file into a suitable folder in the host machine, but do not change the file name. For example: ~/<core-system-name>/application.properties. These files will be binded to the docker container in order to serve a proper and editable config file to the core system instance.

The following properties must be changed:

spring.datasource.url

The default database address is localhost, which in case of docker containers is the container itself, but we have to use the database address as it was exposed earlier to host machine: spring.datasource.url=jdbc:mysql://<database-host-machine-address>:<database-host-machine-port>/arrowhead?serverTimezone=Europe/Budapest

domain.name and domain.port

Here we have to specify the address where the host machine is available and the port where the core system docker container will be exposed.

sr_address and sr_port

Every core system (except Service Registry itself) needs the address of Service Registry. Here we have to specify the address where its host machine is available and the port where Service Registry docker container was exposed (Service Registry's domain.port property).

Provide custom certificates (for secure mode only)

server.ssl.key-store and server.ssl.trust-store

Certificate files also will be mounted to the docker container, therefore you have to place your certificates into a suitable folder in the host machine and 'file:' has to be used instead of 'classpath'.
server.ssl.key-store=file:<your-certificate-folder-name>/<certificate-file>
server.ssl.trust-store=file:<your-certificate-folder-name>/truststore.p12
server.ssl.key-alias=<alias-name-in-your-certificate>

Caveat: If your certificate was created by the certificate generator tool by AITIA International Inc., then the certificate alias name equals to the certificate common name. Example: authorization.demo.aitia.arrowhead.eu

Learn more about the certificates.
Create your own certificates.

Caveat: Make sure your certificates are containing the host machine's address as Subject Alternative Name (SAN) or alternatively you can disable the hostname verification mechanism by setting the disable.hostname.verifier property to true (less secure option).

Example (assuming 10.0.0.5 is the host machine IP address for every docker container)

spring.datasource.url=jdbc:mysql://10.0.0.5:3306/arrowhead?serverTimezone=Europe/Budapest
...
domain.name=10.0.0.5
domain.port=8445
...
sr_address=10.0.0.5
sr_port=8443
...
server.ssl.key-store=file:certificates/authorization.p12
server.ssl.trust-store=file:certificates/truststore.p12
server.ssl.key-alias=authorization.demo.aitia.arrowhead.eu

Create the core system instance container

Now you can create a container (a core system instance) from the core system image with the command:

docker create --name <your-container-name> -p <host-port>:<container-port> --mount type=bind,source=<absolute-path-to-your-application-properties-file>,target=/opt/arrowhead/application.properties --mount type=bind,source=<absolute-path-to-your-certificate-folder>,target=/opt/arrowhead/<your-certificate-folder-name> -e SYSTEM_NAME=<core-system-name> <your-image-name>

--name: Gives a human readable name to the container. For example: arrowhead-serviceregistry-mycloud1.
-p: Binds a port on the host machine to a container port in order to being accessable from outside of the container. <host-port> must be the same as what was set in the application.properties file at domain.port and <container-port> must be the same as what was at server.port
--mount: Attach a file or folder to a container when it is created. It allows you to share files between the host machine and the container.
-e: Set an environment variable. SYSTEM_NAME environment variable must be set in order to initialize the required core system. The provided system name has to match to one of the system folder name within the project root folder.

Example:

docker create --name arrowhead-authorization-mycloud1 -p 8445:8445 --mount type=bind,source=/home/joe/arrowhead/mycloud1/authorization/application.properties,target=/opt/arrowhead/application.properties --mount type=bind,source=/home/joe/arrowhead/mycloud1/authorization/certificates,target=/opt/arrowhead/certificates -e SYSTEM_NAME=authorization arrowhead-system:4.6.1

This way you can create as much runnable core system containers for as much different arrowhead cloud instances as it is necessary.

To start the container use the following command:

Example

docker start arrowhead-authorization-mycloud1

What's next?

Make your application system Arrowhead compliant or run some demo.