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.
Check that the host is ready:
/opt/panagenda/pgdata, /opt/panagenda/appdata and /opt/panagenda/logs are mounted, and Docker waits for them at boot (see Partitioning).Download one of the two packages. Both install the same version; the offline package also contains the Docker images.
Copy the package to the host, for example to /root.
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).
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.
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 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.
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.
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 (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:
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).
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.
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.
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).Replace the panagenda certificate with a certificate for your server address, so that browsers trust the connection:
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./opt/panagenda/appdata/volumes/nginx/.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.
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:
| Setting | Purpose |
|---|---|
PANAGENDA_HOSTNAME | The server address: the name users open in their browser, also used for the Metabase reports and in the links of alert emails. Chosen during the installation; change it with ifa hostname rather than in the file. |
PANAGENDA_TIMEZONE | The time zone of the containers. Detected from the host. |
PANAGENDA_COMPOSE_NETWORK_SUBNET | The private /24 subnet of the internal Docker network, by default 192.168.238.0/24. Change it if your network already uses this subnet. |
PANAGENDA_METABASE_SITE_URL | The address of the Metabase reports, by default https://<PANAGENDA_HOSTNAME>/metabase. Set it only if users reach Metabase through a reverse proxy with another port or path, in the form https://proxy.example.com:8443/metabase; for another name, change the server address with ifa hostname instead. While it is set, the installer does not ask for the server address. |
PANAGENDA_POSTGRES_SHM_SIZE | Shared memory of the database, by default 2gb. Lower it only on small test hosts with less than 4 GB RAM. |
PANAGENDA_ENABLE_MCP | Enables the MCP server for AI clients, by default false (see Setting up the MCP Server). |
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.
Operate iDNA with the command ifa as root:
| Command | What it does |
|---|---|
ifa start | Starts the containers if they are not running. |
ifa stop | Stops the containers. |
ifa restart | Restarts the containers. |
ifa down | Stops and removes the containers; all data is kept. |
ifa recreate | Stops, removes and starts the containers. Use it after changing the configuration file. |
ifa hostname | Shows the current server address and lets you choose a new one on the same screen as during the installation (needs a terminal). If you choose a different address, it asks whether to apply it right away, which makes iDNA unavailable for a few minutes, and shows the addresses as at the end of the installation. If you apply right away, the reachability check may report "could not reach" only because the containers are still starting. |
ifa hostname <name> | Checks the name and saves it as the server address without questions; if the name does not point to this host, it says what it found. Apply it with ifa recreate. |
ifa diagnose-network | Checks whether the internal Docker network collides with networks known to the host. Changes nothing. |
ifa uninstall | Removes iDNA Applications including the database (see Uninstalling). |
/opt/panagenda/logs/ifa-upgrade_<date>_<time>.log, one file per run. Attach it to every support request about an installation or upgrade./opt/panagenda/logs/<service>/, for example idna, dda, postgres or nginx. iDNA deletes these files after 7 to 14 days.docker logs panagenda_<service> shows the latest output of a container; add -f to follow it.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/.
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.
sudo -i) or with sudo.apt install fdisk).ss -tlnp 'sport = :80' or ss -tlnp 'sport = :443', stop or reconfigure it, and start the installer again.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.ifa hostname and choose the name your users use.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.