Installing iDNA Applications on Linux

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.

New installations and upgrades use the same installer. It checks the host, downloads or unpacks the iDNA Docker images, creates the directories under /opt/panagenda, writes the configuration and starts the containers. It installs iDNA Applications 3.5.0 or later.

Before You Start

Check that the host is ready:

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

Installation

Step 1: Download the Installer

Download one of the two packages. Both install the same version; the offline package also contains the Docker images.

• Online installer (about 1 MB): downloads the Docker images from docker.panagenda.com during the installation.
• Offline installer (2 to 2.5 GB): for hosts without internet access.

Copy the package to the host, for example to /root.

Step 2: Unpack the Package

Log in to the host via SSH and open a root shell. Unpack the package and delete the zip file to free the space:

sudo -i
cd /root
unzip idnaapplications-upgrade-online.zip
rm idnaapplications-upgrade-online.zip

The online package contains the file ifa-upgrade.sh, the offline package the file ifa-upgrade-offline.sh. Use the file names of the offline package if you downloaded that one.

Offline installer: while it runs, the offline installer unpacks about 8 GB into /tmp. Check the free space with df -h /tmp. If /tmp has less than 8 GB free, for example because it is held in memory (tmpfs), let the installer use a directory on a larger filesystem instead (see Not Enough Disk Space).

Step 3: Run the Installer

Start the installer in the root shell:

sh ./ifa-upgrade.sh

The installer first shows where it writes its log file (/opt/panagenda/logs/ifa-upgrade_<date>_<time>.log) and checks the host. It stops with an error message if a required tool is missing, if it does not run as root, or if port 80 or 443 is in use (see Troubleshooting). It may then ask the following questions.

The line "Dedicated /opt_panagenda_* partitions not found; treating as generic Linux host" is expected, also when you created filesystems of your own for the iDNA directories.

Docker Storage Location

The installer shows where Docker stores its images and containers:

Docker images for iDNA will be stored in: /var/lib/docker

This is the Docker daemon's current data-root and the installer will
not change it. On a fresh customer host this is normally
/var/lib/docker. If the path shown is on a partition with insufficient
space (or otherwise wrong for your environment), abort now, edit
/etc/docker/daemon.json to relocate data-root, restart the Docker
daemon, and re-run this installer.

Is this configuration correct? [Y/N]

Answer Y if the path is on a filesystem with enough space; with the recommended partitioning, this is the root filesystem. Answer N to stop the installation, for example to move Docker's data to another filesystem first.

Security Notice

SECURITY NOTICE
The 'cron' container in this stack mounts /var/run/docker.sock to
manage the iDNA containers themselves. On a host that runs other
Docker workloads, this gives the cron container effective root access
to every container on this Docker daemon.

If this host is dedicated to iDNA Applications, this is the expected
configuration. If this host runs other Docker workloads that must be
isolated from iDNA, abort now.

Continue? [Y/N]

On a host dedicated to iDNA, answer Y. If the host runs other containers that must be isolated from iDNA, answer N and use a dedicated host (see Dedicated Host).

The installer asks both questions only during a new installation, the security notice only if other containers are already running on the host. Upgrades ask neither.

SELinux

With a standard Docker installation, Docker does not enforce SELinux on containers, and the installer only reports:

SELinux is Enforcing on the host, but Docker does not enforce SELinux on containers; bind mounts will work without labeling.

Only if Docker is configured to enforce SELinux on containers does the installer ask whether it may label /opt/panagenda for the containers:

SELinux is Enforcing and Docker enforces SELinux on containers. To let
the iDNA containers access their host bind mounts, the installer can
apply a persistent file-context rule and relabel /opt/panagenda once:

    semanage fcontext -a -t container_file_t '/opt/panagenda(/.*)?'
    restorecon -R /opt/panagenda
...
Apply these now? [Y/N]

Answer Y to apply the rule. If your security policy does not allow application installers to change SELinux settings, answer N, run the two commands as root yourself and start the installer again.

Server Address

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:

=====================================================================
 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:

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

If you need help, contact support@panagenda.com and attach the installer log.