GETTING STARTED

The following instructions will help you to start using MINT Service Desk.

FIRST LOGIN

Type your server IP or domain address on your web browser and login with the default admin account credentials (remember to change it):

Login: admin Password: admin1

Now, in order to start using Mint Service Desk you need to:

Define a new email account from which messages will be sent. You can do it in section Email > Accounts. Right here you need to click on the small button located on the right side of the search bar.

Inside the “Create Account” view you will need to fill up the required information (fields marked with a *). Also, you can add some additional information inside the “Description” text field.

Now, in the next view, you will need to select which email you’re using. You can choose:

Gmail

Yahoo!

Microsoft Office 365

Other

Microsoft Graph Api

After that fill up the necessary information – you will find more information about creating accounts in the Admin>Email>Accounts part of this guide.

Once you finish, click on the button to finish the process and save the new email account.

You will be moved to the list of existing accounts, where you will see a new position with some information about your new email account.

Define at least one “Body” type template component which includes at least ‘{{EmailURL}}’.

You can do it in section Tickets > Components.

Right here you need to click on the small button located on the right side of the search bar.

In the view responsible for creating a new template component click on the button located right below the ‘Description’ section. Select Email > Url from the menu.

Now click on the button.

You will find detailed description regarding creating templates in the Admin>Tickets>Templates part of this guide.

Define at least one template. You can do it in Tickets > Templates section.

Right here you need to click on the small button located on the right side of the search bar.

You need to choose a previously created Body type Component from the list in the ‘Select body’ section. Also, remember to create an appropriate name for this template and select “system” from the “Template type” part of this view.

Click on the button.

Now you need to Set up ‘Email confirmation Template’. You can do it in the Settings>General>Templates and choosing already created template from the list in the ‘Email confirmation template’ section.

Once you do that, just click on the button.

Now you need to create at least one Agent type user. You can do in the Agents>Agents section. Right here you need to click on the small button located on the right side of the search bar.

Inside, in the ‘Create User’ view, you need to fill up all of the required information and click on the button once you do that. Take notice, that you need to select a correct ‘Role’ from the list.

MINT Service Desk has one already predefined Agent role. If you want to learn more about adding and managing system Roles, you will find more information in the Admin part of this guide.

Once Agent is created, the first attempt to login will send a verification email to the new Agent on his email address (given during the previous step). It will include a request to validate his email address.

Once that’s done – you are ready to go.

BACKUP AND RESTORE

CREATE BACKUP

To start the backup process, get inside the container where the database is:

docker exec -it id_container /bin/sh

id_container to the database. When you enter the container you should enter:

pg_dumpall -U postgres --filename.sql

filename.sql filename with extension sql.

Then exit the container with the command:

exit

Once out of the container you should enter the command:

docker cp id_container:/filename.sql .

docker cp id_container:/filename.sql . copies a file with a copy of the database to the MINT machine

RESTORING DATA

To start the restoring process, copy the database dump to a container:

docker cp filename.sql id_container:/filename.sql

The next step is to get to the database container:

docker exec -it id_container /bin/sh

The final step is to type the command to restore the copy:

psql -U postgres -f filename.sql

SSL CERTIFICATES

In order to get a secure SSL connection, you need to replace the generated self-signed certificates with properly signed certificates.

Format of certificates

The Reverse Proxy service expects a public certificate in crt/pem format.

Example ‘pem’ certificate:

Example ‘key’:

Generating self signed certificates

The easiest way to generate a certificate is to have Linux system with openssl installed. You can then use the command:

$ openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 \
  -keyout "privkey.key" -out "fullchain.pem" -subj \
  "/C=PL/ST=Test State/L=Test /O=Test Name\
  /OU=Test Unit/CN=Common/emailAddress=test@test.test"

Certificate replacement in docker secret

Unlike environmental variables, the secret cannot easily be replaced. To do so, the secret must first be unplugged from the running Reverse Proxy service.:

$ docker service update --secret-rm Certificate__pem --secret-rm CertificateKey__key mintsd_reverse-proxy

Then we must remove the existing secrets from the secret database.:

$ docker secret rm Certificate__pem CertificateKey__key

The next step is to create new secrets from the key and certificate. Use the following commands:

'$ docker secret create Certificate__pem certificate_name.pem'
'$ docker secret create CertificateKey__key key_name.key'

Finally, the newly created secrets have to be connected to the Reverse Proxy service.:

$ docker service update \
  --secret-add source=Certificate__pem,target=/etc/ssl/private/fullchain.pem \
  --secret-add source=CertificateKey__key,target=/etc/ssl/private/privkey.key \
  mintsd_reverse-proxy

USING LET’S ENCRYPT - FREE SSL CERTIFICATES

Let’s Encrypt allows you to generate a signed certificate for free by using the command:

$ sudo certbot certonly --nginx

Detailed installation and usage instructions can be found in the documentation:

*https://certbot.eff.org/*

NOTE: In order to run certbot application you need ports 80 and 433 and an assigned domain. Therefore, the application cannot be launched if Mint SD has already been launched and occupies the ports.

Automatic certificate upgrade

By adding the certbot command to /etc/crontab you can force a new certificate generation after a certain time.

Below you can see the example of using /etc/crontab:

$ echo "0 0,12 * * * root python -c 'import random; import time; time.sleep(random.random() * 3600)' && certbot renew -q" \
  sudo tee -a /etc/crontab > /dev/null

However, with the Reverse Proxy service running, updating the secret where it is located may be non-trivial. For best results it is good to take the reverse proxy configuration to the host machine. Thanks to this, updating the environment will only consist of replacing certificates by certbot.

Details of reverse proxy configuration can be found in the next part of this guide.

REVERSE PROXY

Reverse Proxy service is used to split traffic directed to one domain into different services. The determination to which service it should be redirected is based on url address. In the service stack, three other services are hidden directly behind Reverse Proxy. These are: Frontend, Gateway, and Auth.

Configuration of redirections

The redirection configuration is in the nginx.conf file in the server block. Built-in reverse proxy contains 4 location blocks.:

location /api/ {
  proxy_pass http://gateway/api/;
  include common_location.conf;
}

location /livereloadHub {
  proxy_pass http://gateway/livereloadHub;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "Upgrade";
}

location ~* ^/(idp|connect|\.well-known|Account|external) {
  proxy_pass http://auth;
  include common_location.conf;
}

location / {
  proxy_pass http://frontend;
  include common_location.conf;
}

The first block redirects all requests in https://domain.name/api/ format to the Gateway service.

The next block, in addition to redirecting traffic from https://domain.name/livereloadHub to the Gateway service, specifies the possibility of communication via the ‘web socket’ protocol.

The third block defines a series of redirections to the Auth service, such as the login page, OpenID connect or static resources used on the login page.

The last block redirects all other requests to the Frontend service.

The common_location.conf file contains a definition of the headers needed for the proxy to work properly. These are headers such as X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host or X-Forwarded-Port.

SSL Configuration

Basic SSL configuration can be found in ssl.conf file. The file contains the definition of supported protocols, encryption definition and certificate location, which is set to /etc/ssl/private/ by default.:

ssl_certificate             /etc/ssl/private/fullchain.pem;
ssl_certificate_key         /etc/ssl/private/privkey.key;

Reverse proxy on the host machine

The resignation from the standard reverse proxy running in the service stack allows for a wider configuration of settings.

Changes in the `services.yml` file.

To properly run services you need to make some changes to the service definition in services.yml file.

1. Ports from Frontend, Gateway and Auth services should be exposed directly. If you take one them as an example, it looks like this.:

gateway:
   image: mint/gateway:latest
   ...
   ports:
     - port_on_which_we_want_to_start_service:80

2. The definition of Reverse Proxy service must be removed from the services.yml.

Note: Ports defined in this file will be needed later in reverse proxy configuration. When you start the stack, the services will be directly visible on the host machine.

Definition of reverse proxy

HTTP reverse proxy can be defined using different HTTP servers. In this case nginx will be used. The initial configuration will be twinned to the one existing in the default Reverse Proxy service.

In Docker Swarm, the network interface driver is ‘overlay’ type. This means that services will NOT be visible at the localhost address. You can use the ip addr command to check the access address to the stack.

The result should be as follows:

...
5: docker_gwbridge: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default
    link/ether 02:42:98:4e:fe:bc brd ff:ff:ff:ff:ff:ff
    inet 172.21.0.1/16 brd 172.21.255.255 scope global docker_gwbridge
       valid_lft forever preferred_lft forever
    inet6 fe80::42:98ff:fe4e:febc/64 scope link
       valid_lft forever preferred_lft forever
...

The address assigned to the docker_gwbridge interface is the address that we will use later when defining the reverse proxy configuration. In this case it is 127.21.0.1.

Changes that need to be made in nginx.conf in relation to the built-in ‘Reverse Proxy’ are only redirection addresses. Instead of http://gateway you should use http://ip_address_docker_gwbridge:the_port_where_the_service_was_exposed. The same for other location blocks.