Skip to content
Mint Service Desk Documentation centre

Getting Started

Mint Service Desk 3.4.2 user manual.

First Login

Administrator sign-in

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

Initial configuration

Complete the following configuration before using Mint Service Desk:

  1. 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.

In “Create Account”, complete the required fields marked with an asterisk *. You can add further information in “Description”.

Select the email service:

  • Gmail
  • Yahoo!
  • Microsoft Office 365
  • Other
  • Microsoft Graph Api

Enter the required settings. See Admin > Email > Accounts for account configuration details.

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.

  1. 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.

  1. 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.

Select the previously created Body component in “Select body”. Enter a template name and choose “system” under “Template type”.

Click on the button.

  1. In Settings > General > Templates, select the template you created under “Email confirmation template”.

Once you do that, just click on the button.

  1. 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 includes one predefined Agent role. The Admin section explains how to add and manage system roles.

  1. After creating the Agent, the first sign-in attempt sends a verification email to the address entered during account creation. The Agent must confirm that address before beginning work.

Create Backup

Open a shell in the database container:

docker exec -it id_container /bin/sh

Replace id_container with the database container ID. Inside the container, run:

pg_dumpall -U postgres --filename.sql

filename.sql is the name of the SQL backup file.

Exit the container:

exit

On the host, run:

docker cp id_container:/filename.sql .

docker cp id_container:/filename.sql . copies the database backup to the Mint host.

Restoring Data

Copy the database dump into the container:

docker cp filename.sql id_container:/filename.sql

Open a shell in the database container:

docker exec -it id_container /bin/sh

Restore the backup:

psql -U postgres -f filename.sql

Format of certificates

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

Example ‘pem’ certificate:

-----BEGIN CERTIFICATE-----
MIID/TCCAuWgAwIBAgIUWOtKfWa9w1Fqh7ghzA+iflYebGAwDQYJKoZIhvcNAQEL
BQAwgY0xCzAJBgNVBAYTAlBMMRMwEQYDVQQIDApUZXN0X1N0YXRlMQ4wDAYDVQQH
DAVUZXN0IDEVMBMGA1UECgwMVGVzdF9OYW1lICAgMRIwEAYDVQQLDAlUZXN0X1Vu
aXQxDzANBgNVBAMMBkNvbW1vbjEdMBsGCSqGSIb3DQEJARYOdGVzdEB0ZXN0LnRl
c3QwHhcNMjAxMDA2MDg1MjQwWhcNMzAxMDA0MDg1MjQwWjCBjTELMAkGA1UEBhMC
...
WbVPWX706/s/tAgdXzz6AnVlUrErPPy+2zk0iZoIjLh1oXaqcLea4hXyFoRj6QBm
8Z8p3Fbm3NyyeEMTj91fu5UB647yU6ZBsW+dgiYBJaPuoKUrXbqZz/cQ92jnd+TF
6FzFOvXqM36Kl/dLmYibv0VXMjYT6PnY1nikBc2ve1aMM0TUR70Jb1U7Fv1FNH7V
/JhMr7rCO9UHL91KoF9t1Lc=
-----END CERTIFICATE-----

Example ‘key’:

-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDW2KUzPcyf3mTo
HI4mm1UR9+cggDNn6Uufyur6kI2Qj+ILKBvwX/+SnBimGuEtJJjddiNJo/Ahu0LI
A01tsa0wfsGErtuGK/poPGlA47Ucq6bVbtnzDZp2Hn4bdGAHvqILRZldE8S9QT6x
hsl40JJVWN8aOrOTdyAo3OQ4CAORMOss1jod+44OTH8P/0OYQ/MLZNdwOXVBMqM9
qy28LXrxkfugGvGVIZiQGueAJSijzPmh0ydNvejhA1QnotJSb2QnVppPmtzk/sGM
...
Z4VW3myfK64qsRP3syGOFFcWDqZZe28dL/8LYb0CgYEA2W2nHVIu0cUIPT9tMvz7
nhNMuYCgP7yKWU4WCLkksLxfYL/zSdveCBddT0dFeq8chZzD4qeOHavwajYosEej
M1q9Obq7vOkDtB3GqJHNp+1CCJvzZAW2Aca5FR+mnIZ1JgzVC6f2/m0fPpyksJaL
LtosfA36JGx73J3QRshFNHg=
-----END PRIVATE KEY-----

Generating self-signed certificates

On Linux with openssl installed, generate a self-signed certificate with:

$ 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"

Replacing a certificate in Docker secrets

To replace a certificate secret, first disconnect it from the running Reverse Proxy service:

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

Remove the existing secrets from the secret store:

$ docker secret rm Certificate__pem CertificateKey__key

Create new secrets from the certificate and key:

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

Connect the new secrets 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

Automatic certificate upgrade

Add a certbot renewal command to /etc/crontab to run it at scheduled intervals.

Example entry in /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

Replacing the certificate secret while the Reverse Proxy service is running requires additional steps. Move the reverse proxy configuration to the host so that certbot can replace the certificate files directly.

The next section describes how to configure the reverse proxy on the host.

Configuration of redirections

Configure routing in the server block of nginx.conf. The built-in reverse proxy has 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 routes requests under https://domain.name/api/ to Gateway.

The second block routes https://domain.name/livereloadHub to Gateway and enables WebSocket communication.

The third block routes requests to Auth, including the login page, OpenID Connect and static resources used by the login page.

The last block routes all other requests to Frontend.

The common_location.conf file defines proxy headers, including X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Port.

SSL Configuration

Configure SSL in ssl.conf: supported protocols, encryption options and certificate paths. The default certificate directory is /etc/ssl/private/:

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

Changes in services.yml

Update the service definitions in services.yml before running the reverse proxy on the host.

  1. Expose the ports of the Frontend, Gateway and Auth services directly. For example:
gateway:
   image: mint/gateway:latest
   ...
   ports:
     - port_on_which_we_want_to_start_service:80
  1. Remove the Reverse Proxy service definition from services.yml.

Note: Use the ports defined here when configuring the reverse proxy. After starting the stack, these services are directly accessible on the host.

Configuring the reverse proxy

This example uses nginx as the HTTP reverse proxy on the host. Start with the configuration used by the built-in Reverse Proxy service.

Docker Swarm uses an overlay network. Services on that network are not accessible at localhost. Use ip addr to find the address used to access the stack.

Example output:

...
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
...

Use the address assigned to docker_gwbridge when configuring the reverse proxy. The address given in this example is 127.21.0.1.

In nginx.conf, replace the built-in Reverse Proxy destination addresses. For example, replace http://gateway with http://ip_address_docker_gwbridge:the_port_where_the_service_was_exposed. Update the other location blocks in the same way.