Hatching Frontend

Installing and configuring Hatching Frontend

In this document, we will assume the frontend is made available using URL https://triage.example/ - you can safely change this to match your deployment environment.

It is also possible to define an IP address right away instead of "triage.example", just replace "triage.example" with the IP address etc.

Install Hatching Frontend and nginx:

apt install nginx python hatching-frontend

Create a Postgres database and add a user for the frontend database:

sudo -u postgres createuser triage-www
sudo -u postgres createdb -O triage-www triage-www

Automatically configure nginx and Hatching Frontend by running the following script. Change the domain accordingly.

triage-setup frontend

The configuration file of the Hatching Frontend (the file is located at /var/lib/triage-frontend/frontend.yaml) and should not require any changes.

The nginx configuration is located in /etc/nginx/sites-available/triage. The following generated configuration is present there:

# Default handler
server {
    listen 80  default_server;
    #listen 443 ssl default_server;
    listen [::]:80 default_server;
    #listen [::]:443 ssl default_server;
    #ssl_certificate /var/lib/acme/live/triage.example/fullchain;
    #ssl_certificate_key /var/lib/acme/live/triage.example/privkey;

    server_name  _;
    return 444;
}

# Triage on-premise frontend
server {
    # Hostname/domain/IP of server
    server_name triage.example;
    listen 80;
    listen [::]:80;

    # TLS should be configured and enabled. By default it is disabled. 
    # Replace the certificate and key paths with valid paths.
    #listen 0.0.0.0:443 ssl http2;
    #listen [::]:443 ssl http2;
    #include snippets/acme.conf;
    #ssl_certificate /var/lib/acme/live/triage.example/fullchain;
    #ssl_certificate_key /var/lib/acme/live/triage.example/privkey;

    # Proxy the Triage-frontend service. This serves both the UI and API.
    # The frontend service configuration is located at /var/lib/triage-frontend/frontend.yaml
    location / {
        proxy_pass http://127.0.0.1:9012;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
        client_max_body_size 1G;
        include proxy_params;
    }

    # NGINX should serve the static files of the UI to improve performance.
    # The static files are automatically updated when updating the hatching-frontend package.
    location = /favicon.ico {
        alias /usr/share/triage-frontend/ui/static/icons/favicon.ico;
    }
    location /static/ {
        alias /usr/share/triage-frontend/ui/static/;
    }
    # The documentation for the API and UI usage.
    location /docs/ {
        alias /usr/share/triage-frontend/docs/;
    }
}

It is possible to create a company and user when Triage Frontend has been set up.

Triage Frontend can be configured so that users need to be manually created, or it can use LDAP for authentication.

Follow these steps for manual user creation and these steps for LDAP authentication.

Enabling invite emails

An SMTP server needs to be configured to enable sending email invites. This can be achieved by adding a mail section to /var/lib/triage-frontend/frontend.yaml as shown below.

mail:
  host: <SMTP server hostname/IP>
  port: <SMTP port>
  username: <Username for logging in>
  password: <Password for the username>
  from_addr: noreply@<Your mail domain>
  from_name: Hatching Triage

Note that SMTP configuration is not required to use invites. If you do not configure an SMTP server, the invite link has to be manually shared with the invitee.

Plaintext communication is not supported. This means the SMTP server must support TLS or STARTTLS.

Restart triage-frontend once this is configured.

Starting Hatching Frontend

Once configured, Hatching Frontend may be (re)started with:

systemctl restart triage-frontend nginx

In order to check the status of the various components, a status call may be of help::

systemctl status triage-frontend nginx

Creating a company

When Triage Frontend has been set up, add a company and a user with administrative privileges:

sudo -u triage-www triage-frontend-cli \
    -c /var/lib/triage-frontend/frontend.yaml setup-company \
    -company <COMPANY> -email <EMAIL> -name <FULL-NAME> \
    -password <PASSWORD> -phone <PHONE>

For example, the above command may look as follows:

sudo -u triage-www triage-frontend-cli \
    -c /var/lib/triage-frontend/frontend.yaml setup-company \
    -company Hatching -email support@hatching.io -name "Kees Baas" \
    -password KeesBaas01 -phone 0031752073090

Creating a company and using LDAP authentication

A configuration file needs to be created at /var/lib/triage-frontend/ldap.yaml to use LDAP authentication.

Copy the following contents and edit the host and basedn according to your LDAP settings. The company ID must be be a random UUID.

Optional configuration values

bind_attribute
- The LDAP attribute to use when binding users. Defaults to cn.

companyid: 04329a56-edaf-4916-bb25-a11c5ee427eb
host: localhost:389
basedn: dc=example,dc=org

Running the following command must be done before attempting to login.

When the configuration file has been created, add a company:

sudo -u triage-www triage-frontend-cli \
    -c /var/lib/triage-frontend/frontend.yaml \
    -ldapc /var/lib/triage-frontend/ldap.yaml setup-company -company <name>

The first user to log in with their LDAP credentials will receive the admin role in Triage Frontend. This user is able to change the roles of other users that log in after this moment.

For example, the above command may look as follows:

sudo -u triage-www triage-frontend-cli \
    -c /var/lib/triage-frontend/frontend.yaml \
    -ldapc /var/lib/triage-frontend/ldap.yaml setup-company -company Company1

Restart Triage Frontend after the company has been created. This is required to enable the use of LDAP.

systemctl restart triage-frontend

Using Hatching Frontend

Use a web browser to open https://triage.example/ and log in using the credentials you provided for the administrator in the previous step or an LDAP user. You can now use the Hatching Frontend to the full extent.