Page History

Overview

This page takes you from a prepared Linux host to the first login to iDNA Applications, and describes how to operate the installation afterwards. What the host needs is described in Running iDNA on your own Linux; upgrades in Upgrading iDNA Applications.

...

• A recommended or supported distribution (see Operating Systems) with at least 4 CPU cores, 16 GB RAM and 300 GB disk space.
• The filesystems for /opt/panagenda/pgdata, /opt/panagenda/appdata and /opt/panagenda/logs are mounted, and Docker waits for them at boot (see Partitioning).
• Docker Engine and the Docker Compose plugin are installed, running and enabled at boot.
• Ports 80 and 443 are free.
• The server address users will open is registered in DNS and points to the host, and the host has the correct time zone (see Network).
• The host resolves the common names of your Domino servers, for example MailServer01 (see Domino Name Resolution / DNS).
• You can log in to the host via SSH with root rights, and copy files to it (for example with scp or WinSCP).
• For the online installer: the host reaches docker.panagenda.com over HTTPS.

...

Before the installation starts, the installer asks for the server address: the name users type in their browser to open iDNA and its Metabase reports. iDNA also uses it in the links of Metabase emails and in iDNA alert emails. The installer suggests names and checks each one in DNS, which takes a few seconds, up to a minute if DNS does not answer. It then lists them with the best one first:

...

...

The installer suggests names and checks each one in DNS, which takes a few seconds, up to a minute if DNS does not answer. It then lists them with the best one first:

======================
 Server address - please read
=====================================================================
 Users open iDNA Applications and Metabase in their browser under
 this address. Links in Metabase e-mails and subscriptions and in
 iDNA alert e-mails use it too. If users' browsers cannot reach it,
 these links break. (This does not rename the server.)
 You can change it later with 'ifa hostname'.

 This server's host name: idna (no domain)

   1) idna.example.com  points to this server (recommended)
   2) 10.20.30.40       IP address of eth0; links break if it changes
   3) idna              short name; works only if users' DNS completes it
   4) idna.localdomain  not found in DNS
   Or enter a custom host name, e.g. a DNS alias your users already know.

Select an option or enter a custom host name [1]:

What the descriptions mean:

• points to this server: DNS resolves the name to this host. Choose such a name.
• IP address of …; links break if it changes: works without DNS, but every link breaks when the address changes.
• found locally, not verified in DNS: only the host itself knows the name; your users' browsers may not reach it.
• points to …, not to this server (for an IP address: not an address of this server): correct if a load balancer, a reverse proxy or a public NAT address forwards to this host.
• short name; works only if users' DNS completes it: works only where your users' DNS completes it to the full name.
• not found in DNS: your users' browsers will probably not reach it. Register the name in DNS first, or choose another one. If the check took about a minute, the host itself may not reach a DNS server; a name you know is registered can still be typed and confirmed.
• not checked: the installer could not check the name in DNS from this host, because the host has no IPv4 address outside Docker or the DNS lookups failed.

Press Enter to accept option 1, or type the number of another option. You can also type a host name yourself, for example a DNS alias your users already know. If that name does not point to this host, the installer says what it found and asks Use it? [y/N]; answer N to return to the list. Enter only the name, without https://, port or path: at most 63 characters, or an IPv4 address. If users reach iDNA through a reverse proxy with another port or path, choose the proxy's name here and, after the installation, set PANAGENDA_METABASE_SITE_URL as well (see Configuration File). The installer confirms your choice with a line starting with "Selected:".

Without a terminal, for example when the installer runs from a script or over SSH without a terminal, it takes option 1 by itself and reports "No terminal or no answer: using option 1 (…)", with a warning if that address may not be reachable for users. Check the server address afterwards with ifa hostname.

Your choice does not rename the host. You can change it later with ifa hostname (see The ifa Command).

Installation Progress

The installer then shows "Installing iDNA Applications version …", downloads or loads the Docker images, creates the directories under /opt/panagenda, writes the configuration file and starts the containers. Depending on the download, this takes several minutes.

Step 4: Check the Result

If the installation fails, the installer ends with a message starting with "ERROR" that identifies the cause; see Troubleshooting. Otherwise, it ends with the server address and the addresses of iDNA and Metabase:

Server address: idna.example.com
  iDNA Applications:  https://idna.example.com/
  Metabase:           https://idna.example.com/metabase
  Change later: run 'ifa hostname'
  Reachability check: https://idna.example.com/metabase/api/health answered (HTTP 200).

The last line is a check from the host itself that the address answers. Any HTTP status counts; right after an installation it is often not 200, because Metabase is still starting. If instead the installer reports "could not reach … from this server", wait a few minutes and open the address in a browser; if it does not open, check DNS, firewalls and proxies between the host and the address. The installation itself is complete in either case. A warning also appears if the server address is an IP address, a short name or a name that does not point to the host. Without curl on the host, the installer skips the check.

Check that the iDNA containers are running:

docker ps --filter name=panagenda_

All containers listed (their names start with panagenda_) show the status "Up". On the first start, iDNA needs a few minutes before the web interface responds.

Step 5: Log In for the First Time

1. Open https://<server address>/, the address the installer showed at the end, in a browser. Until you install your own certificate, the browser warns about the connection: iDNA comes with a panagenda certificate that does not match your server address (see Using Your Own TLS Certificate).
2. Log in with the default credentials and upload your license, as described in User Web Portal.
3. Change the default password right away (see Change Password).
4. Continue with the configuration in the Setup Guide, starting with the content packages.

After the Installation

Using Your Own TLS Certificate

Replace the panagenda certificate with a certificate for your server address, so that browsers trust the connection:

1. Save the certificate as certfile.pem (PEM format, followed by any intermediate certificates) and the private key as keyfile.key (PEM format, without a passphrase). Keep exactly these file names.
2. Copy both files to /opt/panagenda/appdata/volumes/nginx/.
3. Restart iDNA:

   Code Block
   language bash
   ifa restart

If you only have a PFX file, extract the key and the certificates with OpenSSL. With OpenSSL 3 and older PFX files, add the option -legacy.

openssl pkcs12 -in yourfile.pfx -nocerts -nodes -out keyfile.key
openssl pkcs12 -in yourfile.pfx -nokeys -out certfile.pem

To return to the panagenda certificate, delete both files and run ifa restart.

Configuration File

The installer creates the configuration file /opt/panagenda/appdata/ifa/config with the server address you chose and the values it detects on the host. Later runs do not replace the file; they only change single settings: the server address when you choose one, and the time zone after you confirm it. Settings you may want to change:

The file may also contain PANAGENDA_CONFIRMED_HOSTNAME. The installer and ifa hostname write it to remember that the server address was confirmed; do not edit it.

Apply changes with:

ifa recreate

Note: "ifa recreate" recreates the iDNA containers, so iDNA is unavailable for a few minutes; stopping the containers alone can take up to two minutes. "ifa restart" does not apply configuration changes.

To change the server address later, run ifa hostname (see The ifa Command). If you change the time zone of the host, update PANAGENDA_TIMEZONE and run "ifa recreate". If the file and the host disagree at the next upgrade, the installer asks which value to keep.

The ifa Command

Operate iDNA with the command ifa as root:

Logs

• Installer: /opt/panagenda/logs/ifa-upgrade_<date>_<time>.log, one file per run. Attach it to every support request about an installation or upgrade.
• Services: /opt/panagenda/logs/<service>/, for example idna, dda, postgres or nginx. iDNA deletes these files after 7 to 14 days.
• Containers: docker logs panagenda_<service> shows the latest output of a container; add -f to follow it.

Backups

Back up the iDNA database regularly, and always before an upgrade:

docker exec -u postgres panagenda_postgres pg_dumpall > /backup/idna-$(date +%Y%m%d-%H%M).sql

Replace /backup with a directory on a filesystem with enough free space, preferably not the root filesystem: the backup of a large database is large as well. For a complete restore at file level, also back up /opt/panagenda/appdata/volumes/ and /opt/panagenda/pgdata/.

Uninstalling

To remove iDNA Applications from the host, run:

ifa uninstall

After you type uninstall to confirm, the command removes the iDNA containers, their network and images, the ifa command, the SELinux rule if present, and the directory /opt/panagenda with everything in it, including the database. There is no backup and no way back. Docker itself stays installed.

With filesystems of their own for the iDNA directories, their content is deleted, but the mount points stay and the command reports that it cannot remove them. Remove the entries in /etc/fstab, the logical volumes and the file /etc/systemd/system/docker.service.d/panagenda-mounts.conf yourself if you no longer need them.

Troubleshooting

...

================================================
 Server address - please read
=====================================================================
 Users open iDNA Applications and Metabase in their browser under
 this address. Links in Metabase e-mails and subscriptions and in
 iDNA alert e-mails use it too. If users' browsers cannot reach it,
 these links break. (This does not rename the server.)
 You can change it later with 'ifa hostname'.

 This server's host name: idna-apps (no domain)

   1) idna-apps.acme.com     points to this server (recommended)
   2) 10.20.30.40            IP address of eth0; links break if it changes
   3) idna-apps              short name; works only if users' DNS completes it
   4) idna-apps.localdomain  not found in DNS
   Or enter a custom host name, e.g. a DNS alias your users already know.

Select an option or enter a custom host name [1]:

What the descriptions mean:

• points to this server: DNS resolves the name to this host. Choose such a name.
• IP address of …; links break if it changes: works without DNS, but every link breaks when the address changes.
• found locally, not verified in DNS: only the host itself knows the name; your users' browsers may not reach it.
• points to …, not to this server (for an IP address: not an address of this server): correct if a load balancer, a reverse proxy or a public NAT address forwards to this host.
• short name; works only if users' DNS completes it: works only where your users' DNS completes it to the full name.
• not found in DNS: your users' browsers will probably not reach it. Register the name in DNS first, or choose another one. If the check took about a minute, the host itself may not reach a DNS server; a name you know is registered can still be typed and confirmed.
• not checked: the installer could not check the name in DNS from this host, because the host has no IPv4 address outside Docker or the DNS lookups failed.

Press Enter to accept option 1, or type the number of another option. You can also type a host name yourself, for example a DNS alias your users already know. If that name does not point to this host, the installer says what it found and asks Use it? [y/N]; answer N to return to the list. Enter only the name, without https://, port or path: at most 63 characters, or an IPv4 address. If users reach iDNA through a reverse proxy with another port or path, choose the proxy's name here and, after the installation, set PANAGENDA_METABASE_SITE_URL as well (see Configuration File). The installer confirms your choice with a line starting with "Selected:".

Without a terminal, for example when the installer runs from a script or over SSH without a terminal, it takes option 1 by itself and reports "No terminal or no answer: using option 1 (…)", with a warning if that address may not be reachable for users. Check the server address afterwards with ifa hostname.

Your choice does not rename the host. You can change it later with ifa hostname (see The ifa Command).

Installation Progress

The installer then shows "Installing iDNA Applications version …", downloads or loads the Docker images, creates the directories under /opt/panagenda, writes the configuration file and starts the containers. Depending on the download, this takes several minutes.

Step 4: Check the Result

If the installation fails, the installer ends with a message starting with "ERROR" that identifies the cause; see Troubleshooting. Otherwise, it ends with the server address and the addresses of iDNA and Metabase:

Server address: idna-apps.acme.com
  iDNA Applications:  https://idna-apps.acme.com/
  Metabase:           https://idna-apps.acme.com/metabase
  Change later: run 'ifa hostname'
  Reachability check: https://idna-apps.acme.com/metabase/api/health answered (HTTP 200).

The last line is a check from the host itself that the address answers. Any HTTP status counts; right after an installation it is often not 200, because Metabase is still starting. If instead the installer reports "could not reach … from this server", wait a few minutes and open the address in a browser; if it does not open, check DNS, firewalls and proxies between the host and the address. The installation itself is complete in either case. A warning also appears if the server address is an IP address, a short name or a name that does not point to the host. Without curl on the host, the installer skips the check.

Check that the iDNA containers are running:

docker ps --filter name=panagenda_

All containers listed (their names start with panagenda_) show the status "Up". On the first start, iDNA needs a few minutes before the web interface responds.

Step 5: Log In for the First Time

1. Open https://<server address>/, the address the installer showed at the end, in a browser. Until you install your own certificate, the browser warns about the connection: iDNA comes with a panagenda certificate that does not match your server address (see Using Your Own TLS Certificate).
2. Log in with the default credentials and upload your license, as described in User Web Portal.
3. Change the default password right away (see Change Password).
4. Continue with the configuration in the Setup Guide, starting with the content packages.

After the Installation

Using Your Own TLS Certificate

Replace the panagenda certificate with a certificate for your server address, so that browsers trust the connection:

1. Save the certificate as certfile.pem (PEM format, followed by any intermediate certificates) and the private key as keyfile.key (PEM format, without a passphrase). Keep exactly these file names.
2. Copy both files to /opt/panagenda/appdata/volumes/nginx/.

3. Restart iDNA:

   Code Block
   language bash
   ifa restart

If you only have a PFX file, extract the key and the certificates with OpenSSL. With OpenSSL 3 and older PFX files, add the option -legacy.

openssl pkcs12 -in yourfile.pfx -nocerts -nodes -out keyfile.key
openssl pkcs12 -in yourfile.pfx -nokeys -out certfile.pem

To return to the panagenda certificate, delete both files and run ifa restart.

Configuration File

The installer creates the configuration file /opt/panagenda/appdata/ifa/config with the server address you chose and the values it detects on the host. Later runs do not replace the file; they only change single settings: the server address when you choose one, and the time zone after you confirm it. Settings you may want to change:

The file may also contain PANAGENDA_CONFIRMED_HOSTNAME. The installer and ifa hostname write it to remember that the server address was confirmed; do not edit it.

Apply changes with:

ifa recreate

Note: "ifa recreate" recreates the iDNA containers, so iDNA is unavailable for a few minutes; stopping the containers alone can take up to two minutes. "ifa restart" does not apply configuration changes.

To change the server address later, run ifa hostname (see The ifa Command). If you change the time zone of the host, update PANAGENDA_TIMEZONE and run "ifa recreate". If the file and the host disagree at the next upgrade, the installer asks which value to keep.

The ifa Command

Operate iDNA with the command ifa as root:

Logs

• Installer: /opt/panagenda/logs/ifa-upgrade_<date>_<time>.log, one file per run. Attach it to every support request about an installation or upgrade.
• Services: /opt/panagenda/logs/<service>/, for example idna, dda, postgres or nginx. iDNA deletes these files after 7 to 14 days.
• Containers: docker logs panagenda_<service> shows the latest output of a container; add -f to follow it.

Backups

Back up the iDNA database regularly, and always before an upgrade:

docker exec -u postgres panagenda_postgres pg_dumpall > /backup/idna-$(date +%Y%m%d-%H%M).sql

Replace /backup with a directory on a filesystem with enough free space, preferably not the root filesystem: the backup of a large database is large as well. For a complete restore at file level, also back up /opt/panagenda/appdata/volumes/ and /opt/panagenda/pgdata/.

Uninstalling

To remove iDNA Applications from the host, run:

ifa uninstall

After you type uninstall to confirm, the command removes the iDNA containers, their network and images, the ifa command, the SELinux rule if present, and the directory /opt/panagenda with everything in it, including the database. There is no backup and no way back. Docker itself stays installed.

With filesystems of their own for the iDNA directories, their content is deleted, but the mount points stay and the command reports that it cannot remove them. Remove the entries in /etc/fstab, the logical volumes and the file /etc/systemd/system/docker.service.d/panagenda-mounts.conf yourself if you no longer need them.

Troubleshooting

• "this installer must be run as root or with sudo": run the installer in a root shell (sudo -i) or with sudo.
• "the following required tools are missing": install the tools the message names and start the installer again. On Ubuntu, fdisk is a package of its own (apt install fdisk).
• "required port(s) … are already in use": another service, for example Apache or nginx, uses port 80 or 443. Find it with ss -tlnp 'sport = :80' or ss -tlnp 'sport = :443', stop or reconfigure it, and start the installer again.
• SELinux error about semanage or restorecon: install the package policycoreutils-python-utils and start the installer again.
• "exec format error" when the containers start: the host has an ARM processor. iDNA requires x86_64.
• iDNA cannot reach a Domino server by its name: check the name resolution inside iDNA. The first command must show the IP address of the Domino server, the second shows the search domains iDNA uses, the third checks the Notes port:

  Code Block
  language bash
  docker exec panagenda_idna getent hosts MailServer01 docker exec panagenda_idna cat /etc/resolv.conf docker exec panagenda_idna nc -zv -w 5 MailServer01 1352

  If the name resolves on the host but not inside iDNA, compare the search domains with those of the host. On RHEL and AlmaLinux, also check whether the name is only in the host's /etc/hosts, which iDNA does not see there (see Domino Name Resolution / DNS). After you change the DNS settings of the host, run ifa restart; if that does not help, restart the host.
• iDNA cannot reach Domino servers or other systems: the internal Docker network may collide with a network in your environment. Run ifa diagnose-network; if it reports a collision, change PANAGENDA_COMPOSE_NETWORK_SUBNET (see Configuration File). The check cannot see networks the host has no route to; ask your network team if in doubt.
• Links in Metabase or in emails do not open, or Metabase shows another address than users type: the server address is a name or IP address that users cannot reach. Run ifa hostname and choose the name your users use.
• iDNA shows no data after a reboot: a filesystem for the iDNA directories was not mounted when Docker started. Run ifa down, mount the filesystems, run ifa start, and add the setting that makes Docker wait for them (see Partitioning).

...