Using Firely Server on Docker
We have created a Docker image for Firely Server, 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 Firely Server, you will need to pull the Docker Firely Server container and request a license.
Open your favourite command line tool and execute this command:
> docker pull simplifier/vonk
Go to the Simplifier website, login and download your evaluation license.
Create a working directory for Firely Server and place the license file there.
Warning
If you use Docker, you may want to run multiple instances of Firely Server (e.g. with Kubernetes). Read Running imports with multiple instances for caveats with the Administration endpoint.
Running a Docker Firely Server in SQLite mode
The easiest and the default way to run a Docker Firely Server container is to run Firely Server 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:
Navigate to your working directory for Firely Server and run the container with this command:
in cmd.exe:
docker run -d -p 8080:4080 --name vonk.server -v %CD%/firelyserver-license.json:/app/firelyserver-license.json simplifier/vonk
in Powershell:
docker run -d -p 8080:4080 --name vonk.server -v ${PWD}/firelyserver-license.json:/app/firelyserver-license.json simplifier/vonk
If your license file has a different name, use that name instead of firelyserver-license
on the left side of the -v parameter in the command above. E.g. -v ${PWD}/my-fancy-license.json:/app/firelyserver-license.json
This will spin up a Firely Server 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 local licensefile into the /app
directory, which is the directory where Firely Server resides in the container. Finally 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
You can also take a look at the logs for Firely Server with:
> docker logs vonk.server
Open a browser and use the address http://localhost:8080/
. This will show the landing page of Firely Server.
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
Adjust settings when running in a Docker container
In the paragraph above we showed how to use -v
to mount the license file into the app directory. We can use the same technique to mount a custom settings file or logsettings file. Or a directory to host the SQLite database outside of the container. Or have the logfile written to your working directory. Below is a full example using PowerShell. For creating appsettings.instance.json
refer to Firely Server settings. For creating logsettings.instance.json
refer to Log settings.
appsettings.instance.json
{
"SQLiteDbOptions": {
"ConnectionString": "Data Source=./resourcedata/vonkdata.db;Cache=Shared",
"AutoUpdateDatabase": true
}
}
logsettings.instance.json
Settings for console and levels not included for brevity.
{
"Serilog": {
"WriteTo": [
{
"Name": "Async",
"Args": {
"configure": [
{
"Name": "File",
"Args": {
"path": "./log/vonk.log",
"rollingInterval": "Day",
"fileSizeLimitBytes": "",
"retainedFileCountLimit": "7",
"outputTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} {UserId} {Username} [{Application}] [{Level}] [Machine: {MachineName}] [ReqId: {RequestId}] {Message}{NewLine}{Exception}",
"restrictedToMinimumLevel": "Information"
}
}
]
}
},
],
"Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ],
"Properties": {
"Application": "Firely Server",
"Environment": "Default"
}
}
}
Powershell
mkdir logs
mkdir resourcedata //do not use 'data' - the administration database is already in that folder in the container
//create the appsettings.instance.json above
//create the logsettings.instance.json above
docker run -d -p 8080:4080 --name firely.server `
-v ${PWD}/firelyserver-license.json:/app/firelyserver-license.json `
-v ${PWD}/appsettings.instance.json:/app/appsettings.instance.json `
-v ${PWD}/logsettings.instance.json:/app/logsettings.instance.json `
-v ${PWD}/resourcedata:/app/resourcedata `
-v ${PWD}/log:/app/log `
simplifier/vonk:4.0.0
You should see a vonkdata.db
appear in the ./resourcedata
folder, and a log file in the ./log
folder. From here you can experiment with other settings. You can also easily keep different settings files side-by-side, mapping the one you want to test into the container, e.g. -v ${PWD}/some-weird-settings.json:/app/appsettings.instance.json
.
Spinning up with a docker-compose file
Another way to spin up a Firely Server container is to use a docker-compose file. The above example can also be established by the following docker-compose-sqlite.yml
:
1version: '3'
2
3services:
4
5 vonk-web:
6 image: simplifier/vonk
7 ports:
8 - "8080:4080"
9 environment:
10 - VONK_Repository=SQLite
11 - VONK_Administration:Repository=SQLite
12 - VONK_License:LicenseFile=./license/firelyserver-trial-license.json
13 volumes:
14 - .:/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 firelyserver-trial-license
in the text above - but make sure to keep ./license
as that maps to a Docker volume inside the container.
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
Firely Server can use also other repositories than Memory, for example SQL Server. This section describes how to spin up a Firely Server 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.
Warning
If you also run the Administration database on SQL Server, please read Retain the import history.
1version: '3'
2
3services:
4 vonk-web:
5 image: simplifier/vonk
6 ports:
7 - "8080:4080"
8 depends_on:
9 - vonk-sqlserver-db
10 environment:
11 - VONK_Repository=SQL
12 - VONK_SqlDbOptions:ConnectionString=Initial Catalog=VonkStu3;Data Source=vonk-sqlserver-db,1433;User ID=sa;Password=SQLServerStrong(!)Password*
13 - VONK_SqlDbOptions:SchemaName=vonk
14 - VONK_SqlDbOptions:AutoUpdateDatabase=true
15 - VONK_SqlDbOptions:AutoUpdateConnectionString=Initial Catalog=VonkStu3;Data Source=vonk-sqlserver-db,1433;User ID=sa;Password=SQLServerStrong(!)Password*
16 - VONK_Administration:Repository=SQL
17 - VONK_Administration:SqlDbOptions:ConnectionString=Initial Catalog=VonkAdmin;Data Source=vonk-sqlserver-db,1433;User ID=sa;Password=SQLServerStrong(!)Password*
18 - VONK_Administration:SqlDbOptions:SchemaName=vonkadmin
19 - VONK_Administration:SqlDbOptions:AutoUpdateDatabase=true
20 - VONK_Administration:SqlDbOptions:AutoUpdateConnectionString=Initial Catalog=VonkAdmin;Data Source=vonk-sqlserver-db,1433;User ID=sa;Password=SQLServerStrong(!)Password*
21 - VONK_License:LicenseFile=./license/firelyserver-trial-license.json
22 volumes:
23 - .:/app/license
24
25 vonk-sqlserver-db:
26 image: microsoft/mssql-server-linux
27 ports:
28 - "1433:1433"
29 environment:
30 - ACCEPT_EULA=Y
31 - SA_PASSWORD=SQLServerStrong(!)Password*
32 healthcheck:
33 test: /opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P 'SQLServerStrong(!)Password*' -Q 'SELECT 1 FROM VonkSTU3.sys.tables'
34 interval: 1m30s
35 timeout: 10s
36 retries: 3
Save the text above to a file in your working directory with the name docker-compose.mssqlserver.yml
. Make sure your Firely Server license file is named
firelyserver-trial-license.json
and is residing in your working directory (see Getting started on how to obtain the license), not in a subdirectory named license
(that is an internal directory inside the container).
If your license file has a different name, use that name instead of firelyserver-trial-license
in the text above.
Then use this command to spin up a Firely Server container and SQL container:
> docker-compose -f docker-compose.mssqlserver.yml up -d
Open a browser and use the address http://localhost:8080/
. This will show the landing page of Firely Server.
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 Firely Server 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.
Warning
If you also run the Administration database on SQL Server, please read Retain the import history.
To run the Firely Server container we will use the following docker-compose file:
1version: '3'
2
3services:
4
5 vonk-web:
6 image: simplifier/vonk
7 ports:
8 - "8080:4080"
9 environment:
10 - VONK_Repository=SQL
11 - VONK_SqlDbOptions:ConnectionString=Database=VonkStu3;Server=my_host\<myInstanceName>;User ID=<myUser>;Password=<myPassword>
12 - VONK_SqlDbOptions:SchemaName=vonk
13 - VONK_SqlDbOptions:AutoUpdateDatabase=true
14 - VONK_SqlDbOptions:AutoUpdateConnectionString=Database=VonkStu3;Server=my_host\<myInstanceName>;User ID=<DLLUser>;Password=<myPassword>
15 - VONK_Administration:Repository=SQL
16 - VONK_Administration:SqlDbOptions:ConnectionString=Database=VonkAdmin;Server=my_host\<myInstanceName>;User ID=<myUser>;Password=<myPassword>
17 - VONK_Administration:SqlDbOptions:SchemaName=vonkadmin
18 - VONK_Administration:SqlDbOptions:AutoUpdateDatabase=true
19 - VONK_Administration:SqlDbOptions:AutoUpdateConnectionString=Database=VonkAdmin;Server=my_host\<myInstanceName>;User ID=<DLLUser>;Password=<myPassword>
20 - VONK_License:LicenseFile=./license/firelyserver-trial-license.json
21 volumes:
22 - .:/app/license
23 extra_hosts:
24 - "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 lines 11, 14, 16 and 19 the connection string to the database server is stated. Change the
Server
to your database server and instance name.Also change the
User ID
andPassword
on lines 11, 14, 16 and 19 to your credentials.Furthermore we have to tell Docker which IP address the host uses. This is done on line 24. 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 Firely Server license file is named firelyserver-trial-license.json
and is residing in your working directory
(see Getting started on how to obtain the license), not in a subdirectory named license
(that is an internal directory inside the container). Or use the name of your license file instead of firelyserver-trial-license
in the text above.
You can run the Firely Server container as follows:
> docker-compose -f docker-compose.mssqlserver_host.yml up -d
A database will automatically be created if is not already present on the database server. See this page for an overview of permissions the database user needs for creating the database and/or schema.
Open a browser and use the address http://localhost:8080/. This will show the landing page of Firely Server.
Warning
When you have a firewall installed on your host machine, it can block traffic from your Firely Server 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 Firely Server container and a MongoDB container using a docker-compose. We assume you already have MongoDB installed.
Warning
If you also run the Administration database on MongoDb, please read Retain the import history.
1version: '3'
2
3services:
4
5 vonk-web:
6 image: simplifier/vonk
7 environment:
8 - VONK_Repository=MongoDb
9 - VONK_MongoDbOptions:ConnectionString=mongodb://vonk-mongo-db/vonkstu3
10 - VONK_MongoDbOptions:EntryCollection=vonkentries
11 - VONK_Administration:Repository=MongoDb
12 - VONK_Administration:MongoDbOptions:ConnectionString=mongodb://vonk-mongo-db/vonkadmin
13 - VONK_Administration:MongoDbOptions:EntryCollection=vonkentries
14 - VONK_License:LicenseFile=./license/firelyserver-trial-license.json
15 volumes:
16 - .:/app/license
17 ports:
18 - "8080:4080"
19
20 vonk-mongo-db:
21 image: mongo
Save the text above to a file in your working directory with the name docker-compose.mongodb.yml
. Make sure your Firely Server license file is named firelyserver-trial-license.json
and is residing in your working directory (see Getting started on how to obtain the license), not in a subdirectory named license
(that is an internal directory inside the container).
If your license file has a different name, use that name instead of firelyserver-trial-license
in the text above.
Use this command to spin up a Firely Server 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 Firely Server.