Using Vonk on Docker

We have created a Docker image for Vonk, so you can run the server in any environment that supports Docker. For this section we assume you have Docker installed on your system. If you want to install Docker for Windows, please read Installing Docker For Windows for specific installation details.

Getting started

Before you can run Vonk, you will need to pull the Docker Vonk container and request a license.

  1. Open your favourite command line tool and execute this command: > docker pull simplifier/vonk
  2. Go to the Simplifier website, login and download your evaluation license.
  3. Create a working directory for Vonk and place the license file there.

Running a Docker Vonk in SQLite mode

The easiest and the default way to run a Docker Vonk container is to run Vonk in SQLite repository mode. Note that this is not the most performant mode - see MongoDB and SQL Server options below for that.

Open your command prompt and execute this command: > docker images simplifier/vonk

You will get a list that looks like:

../../_images/docker1.png

Navigate to your working directory for Vonk and run the container with this command:

  • in cmd.exe: docker run -d -p 8080:4080 --name vonk.server -v %CD%:/app/license -e "VONK_License:LicenseFile=./license/vonk-trial-license.json" simplifier/vonk
  • in Powershell: docker run -d -p 8080:4080 --name vonk.server -v ${PWD}:/app/license -e "VONK_License:LicenseFile=./license/vonk-trial-license.json" simplifier/vonk

If your license file has a different name, use that name instead of vonk-trial-license in the command above.

Important

It looks like the command wants to retrieve your license file from a subdirectory called license. This is a result of docker copying your file before spinning the image. You should not create the subdirectory. Just keep the license file in the root of your working directory.

This will spin up a Vonk container. It maps the host port 8080 to the container port 4080 with the switch -p 8080:4080. It will give the container the name vonk.server with the switch --name vonk.server. Furthermore it mounts the current directory (where the license file resides) from the host to the container. Also it passes an environment variable VONK_License:LicenseFile to the container with the switch -e. In this example the license file is called vonk-trial-license.json. At last it will run the container in background mode with the switch -d.

To test whether the container is running correctly, type the command:
> docker ps

../../_images/docker2.png

You can also take a look at the logs for Vonk with:
> docker logs vonk.server

Open a browser and use the address http://localhost:8080/. This will show the landing page of Vonk.

To stop the container just type:
> docker stop vonk.server
And to start it again:
> docker start vonk.server
To completely remove the container:
> docker rm vonk.server

Spinning with a docker-compose file

Another way to spin up a Vonk container is to use a docker-compose file. The above example can also be established by the following docker-compose-sqlite.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
version: '3'

services:

  vonk-web:
    image: simplifier/vonk
    ports:
      - "8080:4080"
    environment:
      - VONK_Repository=SQLite
      - VONK_Administration:Repository=SQLite
      - VONK_License:LicenseFile=./license/vonk-trial-license.json
    volumes:
      - .:/app/license

Save the text above to a file in your working directory with the name docker-compose.sqlite.yml and then run the following command:
> docker-compose -f docker-compose.sqlite.yml up -d

If your license file has a different name, use that name instead of vonk-trial-license in the text above - but make sure to keep ./license as that maps to a Docker volume inside the container.

../../_images/docker3.png

To stop the container, run:
> docker-compose -f docker-compose.sqlite.yml down

Note

Strictly the settings for VONK_Repository and VONK_Administration are not needed here, since SQLite is the default setting. The settings are included to show where to configure the type of database to use. Much more information on that topic is in the paragraphs below.

Running Docker with a SQL Server container

Vonk can use also other repositories than Memory, for example SQL Server. This section describes how to spin up a Vonk container and a SQL Server container. We will use docker-compose to achieve this.

Warning

SQL Server container uses at least 3.25 GB of RAM. Make sure to assign enough memory to the Docker VM if you’re running on Docker for Mac or Windows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
version: '3'

services:

  vonk-web:
    image: simplifier/vonk
    ports:
      - "8080:4080"
    depends_on:
      - vonk-server-db
    environment:
      - VONK_Repository=SQL
      - VONK_SqlDbOptions:ConnectionString=Initial Catalog=VonkStu3;Data Source=vonk-sqlserver-db,1433;User ID=vonk;Password=Tester01
      - VONK_SqlDbOptions:SchemaName=vonk
      - VONK_SqlDbOptions:AutoUpdateDatabase=true
      - VONK_SqlDbOptions:AutoUpdateConnectionString=Initial Catalog=VonkStu3;Data Source=vonk-sqlserver-db,1433;User ID=sa;Password=SQLServerStrong(!)Password*
      - VONK_Administration:Repository=SQL
      - VONK_Administration:SqlDbOptions:ConnectionString=Initial Catalog=VonkAdmin;Data Source=vonk-sqlserver-db,1433;User ID=vonk;Password=Tester01
      - VONK_Administration:SqlDbOptions:SchemaName=vonkadmin
      - VONK_Administration:SqlDbOptions:AutoUpdateDatabase=true
      - VONK_Administration:SqlDbOptions:AutoUpdateConnectionString=Initial Catalog=VonkAdmin;Data Source=vonk-sqlserver-db,1433;User ID=sa;Password=SQLServerStrong(!)Password*
      - VONK_License:LicenseFile=./license/vonk-trial-license.json
    volumes:
      - .:/app/license
      - script-volume:/app/data

  vonk-sqlserver-db:
    image: microsoft/mssql-server-linux
    ports:
      - "1433:1433"
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=SQLServerStrong(!)Password*
      - dbName=VonkStu3
      - dbPath=/var/opt/mssql/data/
      - AdminDbName=VonkAdmin
      - AdminDbUsername=vonk
      - AdminDbPassword=Tester01
      - dbUsername=vonk
      - dbPassword=Tester01
   healthcheck:
     test: /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P 'SQLServerStrong(!)Password*' -Q 'SELECT 1 FROM VonkSTU3.sys.tables'
     interval: 1m30s
     timeout: 10s
     retries: 3
   volumes:
      - script-volume:/app/data
    command: bash -c "sleep 10 && cat /app/data/install_vonkdb.sh | tr -d '\r' | sh &  /opt/mssql/bin/sqlservr"

volumes:
  script-volume:

Save the text above to a file in your working directory with the name docker-compose.mssqlserver.yaml. Make sure your Vonk license file is named vonk-trial-license.json and is residing in your working directory (see Getting started on how to obtain the license). If your license file has a different name, use that name instead of vonk-trial-license in the text above.

Then use this command to spin up a Vonk container and SQL container:
> docker-compose -f docker-compose.mssqlserver.yaml up -d

Open a browser and use the address http://localhost:8080/. This will show the landing page of Vonk.

Warning

Wait for about 2 minutes, because it takes a while to fire up the SQL container

Running Docker with a SQL Server on host

Another possibility is to run a Vonk container with a SQL Server repository on the host. You will need a Microsoft SQL Server running on your host. The version of SQL Server must at least be version 2012.

To run the Vonk container we will use the following docker-compose file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
version: '3'

services:

  vonk-web:
    image: simplifier/vonk
    ports:
      - "8080:4080"
    environment:
      - VONK_Repository=SQL
      - VONK_SqlDbOptions:ConnectionString=Database=VonkStu3;Server=<myServerName\myInstanceName>;User ID=<myUser>;Password=<myPassword>
      - VONK_SqlDbOptions:SchemaName=vonk
      - VONK_SqlDbOptions:AutoUpdateDatabase=true
      - VONK_SqlDbOptions:AutoUpdateConnectionString=Database=VonkStu3;Server=<myServerName\myInstanceName>;User ID=<DLLUser>;Password=<myPassword>
      - VONK_Administration:Repository=SQL
      - VONK_Administration:SqlDbOptions:ConnectionString=Database=VonkAdmin;Server=<myServerName\myInstanceName>;User ID=<myUser>;Password=<myPassword>
      - VONK_Administration:SqlDbOptions:SchemaName=vonkadmin
      - VONK_Administration:SqlDbOptions:AutoUpdateDatabase=true
      - VONK_Administration:SqlDbOptions:AutoUpdateConnectionString=Database=VonkAdmin;Server=<myServerName\myInstanceName>;User ID=<DLLUser>;Password=<myPassword>
      - VONK_License:LicenseFile=./license/vonk-trial-license.json
    volumes:
      - .:/app/license
    extra_hosts:
      - "my_host:192.0.2.1"

Save the text above to a file in your working directory with the name docker-compose.mssqlserver_host.yml. Before we spin up the container we have to adjust the docker-compose.mssqlserver_host.yml:

  • On line 9 the connection string to the database server is stated. Change the Data Source to your database server. In this exampe we are using a named instance sql2016 on the host my_host.
  • Also change the User ID and Password on line 9 to your credentials.
  • Furthermore we have to tell Docker which IP address the host uses. This is done on line 17. In this case the host (named my_host) uses IP address 192.0.2.1. Change this to the appropriate address.

After saving your settings, make sure your Vonk license file is named vonk-trial-license.json and is residing in your working directory (see Getting started on how to obtain the license). Or use the name of your license file instead of vonk-trial-license in the text above.

You can run the Vonk container as follows:
> docker-compose -f docker-compose.mssqlserver_host.yaml up -d

We have to create the Vonk database on the host. For this we need two SQL scripts which are located in the Vonk container. Perform the following commands in the working directory to copy the scripts and execute them on your local SQL server:

> docker cp vonk_vonk-web_1:/app/data ./scripts
> cd scripts
> sqlcmd -S my_host\sql2016 -d master -v dbName = VonkSTU3 dbPath= "C:\Program Files\Microsoft SQL Server\MSSQL13.SQL2016\MSSQL\DATA\" -i 01-CreateDatabaseAndSchema.sql
> sqlcmd -S my_host\sql2016 -d master -v dbName = VonkSTU3 dbUsername = vonk dbPassword = Tester01  -i 02-CreateDBUser.sql

You might want to change the dbPath and provide the sqlcmd user (SA) credentials with the parameters -U and -P.

Open a browser and use the address http://localhost:8080/. This will show the landing page of Vonk.

Warning

When you have a firewall installed on your host machine, it can block traffic from your Vonk container to your host. Provide an inbound rule to allow traffic from the container to the host.

Run Docker with a MongoDB container

This section describes how to spin up a Vonk container and a MongoDB container using a docker-compose. We assume you already have MongoDB installed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
version: '3'

services:

  vonk-web:
    image: simplifier/vonk
    environment:
      - VONK_Repository=MongoDb
      - VONK_MongoDbOptions:ConnectionString=mongodb://vonk-mongo-db/vonkstu3
      - VONK_MongoDbOptions:EntryCollection=vonkentries
      - VONK_Administration:Repository=MongoDb
      - VONK_Administration:MongoDbOptions:ConnectionString=mongodb://vonk-mongo-db/vonkadmin
      - VONK_Administration:MongoDbOptions:EntryCollection=vonkentries
      - VONK_License:LicenseFile=./license/vonk-trial-license.json
    volumes:
      - .:/app/license
    ports:
      - "8080:4080"

  vonk-mongo-db:
    image: mongo

Save the text above to a file in your working directory with the name docker-compose.mongodb.yml. Make sure your Vonk license file is named vonk-trial-license.json and is residing in your working directory (see Getting started on how to obtain the license). If your license file has a different name, use that name instead of vonk-trial-license in the text above.

Use this command to spin up a Vonk container and MongoDB container:
> docker-compose -f docker-compose.mongodb.yml up -d

Open a browser and use the address http://localhost:8080/. This will show the landing page of Vonk.