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 Applications on Your Own Linux Host; upgrades in Upgrading iDNA Applications (NEW).

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 supported distribution 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 host has its fully qualified host name and the correct time zone.
• 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 then asks the following questions; answer each with Y or N.

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 on every run, including upgrades.

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.

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 names the cause; see Troubleshooting. Otherwise, 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://<host name>/ 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 host name (see Using Your Own TLS Certificate).
2. Log in with the default credentials and upload your license, as described in Web Interface.
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 host name, 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 values it detects on the host, and never overwrites it afterwards. Settings you may want to change:

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.

If you change the host name or time zone of the host later, update the configuration file and run "ifa recreate". At the next upgrade, the installer also asks whether to adopt the changed values.

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