Skip to main content

Installation

Follow the steps below to install and run the project successfully.

Requirements:

  • Docker, Docker Compose
  • Recommended OS: Ubuntu / any Linux distribution
  • On Windows: run the script using Git Bash

Installation Package​

.env​

This file contains environment variables used by Docker and the application. Example content:

REMOTE_HOST=app.example.com
GRAFANA_PORT=3000
BACKEND_PORT=9983
FRONTEND_PORT=8080

docker-compose.yml​

This file defines the Docker services, ports, volumes, and environment variables. It will use the values defined in the .env file.

install.sh​

This is a bash script that automates the installation and configuration process. It prompts for necessary values and launches the Docker containers.

Frontend HTTPS and certificates​

HTTPS is terminated by Nginx inside the gf-frontend container. Certificates are not included in the Docker image. They must be provided on the server where the installation package is started.

1. Prepare the certificate and private key​

Create a certs directory next to docker-compose.yml:

mkdir -p certs

Place two PEM-formatted files in this directory:

certs/
├── _.gifrost.com.certificate.pem  # server certificate
└── _.gifrost.com.key          # matching private key

re.com:1521#### What certificate is required?

Two matching PEM-formatted files are required:

  • _.gifrost.com.certificate.pem — the server certificate;
  • _.gifrost.com.key — the matching, unencrypted private key.

The filenames are conventions used by the installation package and do not determine the certificate's scope. The certificate SAN field must cover the hostname configured as REMOTE_HOST, either directly or through a wildcard entry. For example, with REMOTE_HOST=app.example.com, the SAN may contain app.example.com or *.example.com.

Where can the certificate be obtained?​

There are three common options:

  • Corporate certificate authority (CA) — for an internal deployment, ask the PKI/IT administrator for a server certificate and the private key in PEM format.
  • Public certificate authority — for a public DNS hostname, use a commercial certificate provider.
  • Self-signed certificate — use this option for testing only.
Self-signed certificate for testing​

The following command creates a certificate valid for app.example.com:

openssl req -x509 -nodes -newkey rsa:2048 -sha256 -days 365 -keyout certs/_.gifrost.com.key -out certs/_.gifrost.com.certificate.pem -subj "/CN=app.example.com" -addext "subjectAltName=DNS:app.example.com"

Replace app.example.com with the actual REMOTE_HOST value.

warning

Self-signed certificates are not trusted by browsers by default. Use them for testing; use a certificate issued by a trusted public or corporate certificate authority in production.

The private key is sensitive. Do not add the certs directory to the image or repository, and restrict access to the key file:

chmod 600 certs/_.gifrost.com.key

2. Mount the certificates into the container​

The gf-frontend service in docker-compose.yml mounts both files read-only:

services:
  gf-frontend:
    ports:
      - "${FRONTEND_PORT}:443"
    volumes:
      - ./certs/_.gifrost.com.certificate.pem:/etc/nginx/certs/fullchain.pem:ro
      - ./certs/_.gifrost.com.key:/etc/nginx/certs/privkey.pem:ro

You may use different filenames on the host by changing the left-hand side of the volumes entries. Keep the container paths on the right unchanged because Nginx reads the certificate and key from those locations.

note

The install.sh script does not create the certs directory or download certificates. The files must exist before running ./install.sh or docker compose up -d.

3. How HTTPS works in the container​

After startup, Nginx:

  • listens on port 443 and supports TLS 1.2 and TLS 1.3;
  • reads /etc/nginx/certs/fullchain.pem and /etc/nginx/certs/privkey.pem;
  • serves the compiled frontend application;
  • proxies requests under /backend/ to gf-backend:9983 on the Docker Compose network;
  • also contains a port 80 HTTP-to-HTTPS redirect, although the current docker-compose.yml publishes only container port 443 on the host.

The application is available at:

https://<REMOTE_HOST>:<FRONTEND_PORT>

For example, with REMOTE_HOST=app.example.com and FRONTEND_PORT=8080:

https://app.example.com:8080

Installation Guide​

1. Grant permission to the script file​

Make sure the script file has execution permissions:

chmod +x install.sh

2. Run the script​

Once permissions are set, launch the script:

./install.sh

Installation Script Walkthrough​

1. Internet Connectivity Check​

During the installation, the script will ask if you have an internet connection:

  • If yes:

    • You will be asked to log in to Azure Registry (required to pull images).
    • The script will use docker login and then pull the required images.

  • If no:

    • You will be asked to provide a path where local Docker image .tar files are stored.
    • The script will use docker load -input to load images from the provided .tar files.

2. Provide Configuration in the Terminal​

The script will then prompt you to enter key configuration values. If you leave any field empty, the default values will be used.

  • Frontend Port

    Enter frontend port [default: 8080]:

    This port is used to access the application's web-based user interface.

  • Backend Port

    Enter backend port [default: 9983]:

    This port allows the frontend to communicate with the backend services (APIs, data processing).

  • Grafana Port

    Enter Grafana port [default: 3000]:

    This port is used to access the Grafana dashboard for metrics and visualization.

  • Host Address (hostname/IP)

    Enter hostname/IP [default: 10.100.22.27]

    This is the IP or hostname where your application will be accessible. It is especially important when the frontend or users need to connect from a remote location.

  • Path to Configuration Directory

    Install directory [default: current]:

    This is the directory where configuration files and Docker volumes will be stored. Useful if you want to persist data or organize deployments.

note

If you leave any of these fields empty, the default values shown in brackets will be used automatically.

Once all the steps above have been completed, the setup process is fully automated. The system will configure the necessary containers, apply environment settings, and launch all services in the background.

Manual Startup​

If you prefer not to use the script:

  1. Configure .env.
  2. Run Docker Compose directly:
docker compose up -d

Your application should now be available at https://<REMOTE_HOST>:<FRONTEND_PORT>.