Skip to content
NEOGAGE

Docker / Podman

Pre-requisites

Section titled “Pre-requisites”

Swarm Mode

Section titled “Swarm Mode”

Podman doesn't require to be configured as a swarm, it will utilise secrets by default. However, Docker will need to be initialised in swarm mode, since this is the only way secrets can be used with Docker. This can be done as follows:

Terminal window
docker swarm init

Docker swarm uses 10.0.0.0/8 by default for the swarm network. If this network will conflict with your internal networks, then specify another address when initialising swarm:

Terminal window
docker swarm init --default-addr-pool 172.16.0.0/16

Either of the above will work in most cases, however if you have a server with multiple IP addresses, then you will need to specify the IP address to advertise swarm on. In this case, an additional parameter is required to specify which IP address it should be:

Terminal window
docker swarm init --advertise-addr x.x.x.x

where x.x.x.x is the IP address to advertise swarm on to add additional swarm nodes. Or a combination of both the above:

Terminal window
docker swarm init --default-addr-pool 172.16.0.0/16 --advertise-addr x.x.x.x

Network Configuration

Section titled “Network Configuration”

It’s important to segregate the Docker/Podman network if there is a possibility that other containers will be running on the Docker/Podman host in the future. Therefore to ensure that no other container can communicate with the MSSQL and NEOGAGE containers, a network is created as below:

Terminal window
docker network create --driver=overlay neogage-net

once this has been done, we are now ready to start deploying the application.

Repository Login

Section titled “Repository Login”

A login is required to be able to download the containers from our container repository. Please contact your NEOGAGE Account Manager if you haven’t been provided with one. Once the login has been obtained, it can be utilised with Docker/Podman as below:

Terminal window
docker login registry.upware.pl

you will be prompted for the login name and password.

Secrets File

Section titled “Secrets File”

A secrets file needs to be prepared with values as documented below:

# It's recommended to use an account other than the "sa" account
# Ensure the user has db create permissions.
SQL_USER=neogage
SQL_PASSWORD=MyPassword123!


# If using the MSSQL container, leave the instance blank.
# If using an external MSSQL server, an instance name may or may not be required.
# If may be enough to just provide SQL_SERVER and SQL_PORT without referencing
# the instance.
SQL_SERVER=mssql-server
SQL_INSTANCE=
SQL_PORT=1433


# Change the database names as required
SQL_DB_APP=neogage_master
SQL_DB_DATA=neogage_data


# KRB5 username - leave blank if not using KRB5.
KRB5_USER=

Once the secrets file has been prepared, this can now be created within Docker/Podman as follows:

Terminal window
docker secret create neogage-secrets neogage-secrets.txt

When running the NEOGAGE container, these secrets will be available for use by the application. The secrets file can now be removed/deleted from the server as it’s no longer required.

Installation

Section titled “Installation”

Database

Section titled “Database”

If you are using an external MSSQL database, the following steps can be skipped and you can continue with the Application section.

The first stage of installation, is to ensure the MSSQL Server container is running. First we pull the container image:

Terminal window
docker pull registry.upware.pl/mssql/server:2022

then we start the container:

Terminal window
docker service create --name mssql-server --env ACCEPT_EULA=Y --env SA_PASSWORD=MyPassword123! --env MSSQL_PID=Express --network neogage-net -p 1433:1433 --mount type=volume,src=mssql,dst=/var/opt/mssql,volume-driver=local registry.upware.pl/mssql/server:2022

This ensure the container runs with MSSQL Server Express, the appropriately configured login and password, the Docker isolated network, as well as configuring the persistent volume for the MSSQL database.

Once the MSSQL container is running, create the user account to be used for the application so that it is not using the SA login/password. This can be done by connecting to the container using SQL Server Management Studio or Azure Data Studio.

CREATE LOGIN neogage WITH PASSWORD = 'MyPassword123!';
EXEC sp_addsrvrolemember @loginame = N'neogage', @rolename = N'dbcreator';
go

change the username and password to suit your requirements. The MSSQL database will require a password that meets the default policy requirements of MSSQL and therefore the more complex the better.

Application

Section titled “Application”

The application can now be run using the secrets prepared earlier. First we pull the container image:

Terminal window
docker pull registry.upware.pl/neogage/neogage:<tag>

then we start the container:

Terminal window
docker service create --name neogage --secret source=neogage-secrets,target=/etc/neogage/app --network neogage-net -p 8080:8080 --mount type=volume,src=neodata,dst=/var/www/neogage/data,volume-driver=local registry.upware.pl/neogage/neogage:<tag>

Replace <tag> with the version number of NEOGAGE as provided by your Account Manager. You will need to wait a few minutes for the container to finish initialising itself which includes populating the MSSQL databases and initial application configuration.

Using KRB5 with NEOGAGE

Section titled “Using KRB5 with NEOGAGE”

If using KRB5 for authentication with MSSQL Database instead of basic Active Directory authentication, additional secrets need to be created. A secret is required for the content required in /etc/krb5.conf and /etc/krb5.keytab. Then create the secrets with docker or podman in the usual manner. Once this has been done, use the command below which will then mount the two KRB5 secrets inside the container for use with KRB5 authentication:

Terminal window
docker service create --name neogage --secret source=neogage-secrets,target=/etc/neogage/app --secret source=neogage-krb5-conf,target=/etc/krb5.conf --secret source=neogage-krb5-keytab,target=/etc/krb5.keytab --network neogage-net -p 8080:8080 --mount type=volume,src=neodata,dst=/var/www/neogage/data,volume-driver=local registry.upware.pl/neogage/neogage:<tag>

Air-gapped installation

Section titled “Air-gapped installation”

If you wish to deploy NEOGAGE in an air-gapped environment, it will be required to download and export the Docker container images. This can be done as follows:

Terminal window
docker save -o mssql-server-2022 registry.upware.pl/mssql/server:2022
docker save -o neogage-<tag> registry.upware.pl/neogage/neogage:<tag>

Replace <tag> with the version number of NEOGAGE as provided by your Account Manager. The exporting of the container images will take time. These can then be copied to the air-gapped server. Once copied over, they can be imported to Docker as follows:

Terminal window
docker load -i mssql-server-2022
docker load -i neogage-<tag>

Replace <tag> with the version used during the docker save command. The commands in the previous section for running the containers can then be adapted to utilise the imported container images.

Additional Configuration

Section titled “Additional Configuration”

Some additional configuration steps are required before the application can be used.

Podman

Section titled “Podman”

If using Podman, when exiting the console, the containers will stop. There are two things that need to be done to resolve this. The first is to use the following command:

Terminal window
loginctl enable-linger <username>

replacing <username> with the user that the containers were started by. If using the older method podman generate systemd this only needs to be done for non-root users. If using the newer quadlets method, this has to be done for both root and non-root users.

If using the older generate systemd method, due to using Podman 4.5 or earlier, run the following commands:

Terminal window
mkdir -p ~/.config/systemd/user
podman generate systemd --new --name mssql > mssql-server.service
podman generate systemd --new --name neogage > neogage.service
podman generate systemd --new --name neogage-proxy > neogage-proxy.service
mv *.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable mssql-server neogage neogage-proxy

if you are going to be running the containers as the root user with Podman, then place the generated systemd unit files in /etc/systemd/system/ and enable them without using the --user parameter. If you will be running these containers as a non-root user, then they need to go under /home/{username}/.config/systemd/user/ as already shown in the above example. These commands will need to be ran after the containers have been installed and are up and running.

If when running podman generate systemd, you get the following:

Terminal window
DEPRECATED command:
It is recommended to use Quadlets for running containers and pods under systemd.

then it would be best to use the new method. This deprecated message should appear on Podman 4.5 and later. Whilst the deprecated method will still work for the time being, it may disappear in the future. It also doesn’t receive updates, only bug and security fixes. Also, any changes implemented are not automatically added to generated systemd files and so means having to re-run the commands regularly to re-generate systemd units. Therefore, using the new quadlets method is preferred. The quadlet method is the same, irrespective of running as the root user or as a normal user.

First, create the directory for the quadlet systemd file:

Terminal window
mkdir -p ~/.config/containers/systemd

Create ~/.config/containers/systemd/neogage.container with the following content, replacing <tag> with the version of Neogage:

[Container]
ContainerName=neogage
Image=registry.upware.pl/neogage/neogage:<tag>
Network=neogage-net
AutoUpdate=registry
PublishPort=8080:8080
Volume=neodata:/var/www/neogage/data
Secret=source=neogage-secrets,target=/etc/neogage/app


[Unit]
Requires=mssql-server.service
After=mssql-server.service


[Service]
Restart=always


[Install]
WantedBy=default.target

a similar file will need to be created for the mssql-server and neogage-proxy podman containers. For example for mssql-server.container file:

[Container]
ContainerName=mssql-server
Image=registry.upware.pl/mssql/server:2022
Network=neogage-net
AutoUpdate=registry
PublishPort=1433:1433
Volume=mssql:/var/opt/mssql
Environment=ACCEPT_EULA=Y
Environment=SA_PASSWORD=MyPassword123!
Environment=MSSQL_PID=Express


[Service]
Restart=always


[Install]
WantedBy=default.target

and for the neogage-proxy.container file:

[Container]
ContainerName=neogage-proxy
Image=registry.upware.pl/neogage/neogage-proxy:latest
Network=neogage-net
AutoUpdate=registry
PublishPort=8443:8443
Secret=source=neogage-cert,target=/etc/nginx/ssl/neogage.crt
Secret=source=neogage-cert-key,target=/etc/nginx/ssl/neogage.key


[Unit]
Requires=neogage.service
After=neogage.service


[Service]
Restart=always


[Install]
WantedBy=default.target

there is no need to use systemctl enable for quadlets, they will automatically be enabled once the files have been created. However, do ensure that the loginctl enable-linger command has been run for whichever user you are running the containers under.

Apply License

Section titled “Apply License”

A license is required to utilise NEOGAGE which can be obtained from your Account Manager. This can be applied to the container as follows:

Terminal window
docker exec -it <neogage-container-name> update-license.py <license>

the license key needs to be provided where <license> appears in the command above. Use docker ps to obtain the container name since it is randomly generated using the name as a prefix from the docker service create commands used previously.

Create Admin User

Section titled “Create Admin User”

The admin user for the NEOGAGE application needs to be created for initial access to the system. The password will be provided on the screen output, which will need to be changed during initial login:

Terminal window
docker exec -it <neogage-container-name> create-admin-user.sh

SSL Certificate

Section titled “SSL Certificate”

The NEOGAGE container isn’t configured to use SSL by default. We recommend two options to choose from for this. The first and much simpler is to utilise our neogage-proxy container which is pre-configured to run nginx as a reverse proxy to redirect to the NEOGAGE application container. All that is required is to provide a certificate and key to run this container. These can then be loaded into secrets for us within the container. The container is configured to read the certificate and private key when the files are named neogage.crt and neogage.key with a particular directory where the secrets are loaded. The certificate and private key need to be in PEM format.

NEOGAGE Proxy Container

Section titled “NEOGAGE Proxy Container”

To prepare the secrets with the SSL certificate and key files:

Terminal window
docker secret create neogage-cert neogage.crt
docker secret create neogage-cert-key neogage.key

Then, we run the container, ensuring the secrets are loaded within the container. First we pull the container image:

Terminal window
docker pull registry.upware.pl/neogage/neogage-proxy:latest

then we run the container:

Terminal window
docker service create --name neogage-proxy --secret source=neogage-cert,target=/etc/nginx/ssl/neogage.crt --secret source=neogage-cert-key,target=/etc/nginx/ssl/neogage.key --network neogage-net -p 8443:8443 registry.upware.pl/neogage/neogage-proxy:latest

The container will then run and provide HTTPS connectivity for the NEOGAGE application.

NGINX installed on Docker/Podman Host

Section titled “NGINX installed on Docker/Podman Host”

The second option if you do not wish to use the container, is to manually install nginx on the Docker/Podman host and configure this using the sample nginx configuration below and adding this to /etc/nginx/conf.d/neogage.conf:

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name  _;


    ssl_certificate "/etc/nginx/ssl/neogage.crt";
    ssl_certificate_key "/etc/nginx/ssl/neogage.key";
    ssl_session_timeout 10m;


    client_max_body_size 100M;


    location / {
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Server $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://neogage:8080;
        proxy_buffers 32 32k;
        proxy_buffer_size 32k;
    }
}