Use installation script

We provide two shell-based installer scripts to simplify PERSEUS deployment on Linux systems:

• installer-docker.sh – for Docker-based setups (rootful)
• installer-podman.sh – for Podman-based setups (rootless with system integration)

Both scripts:

• Install all required dependencies (docker / podman, nginx, etc.)
• Start the containers via Compose
• Set up an Nginx reverse proxy
• Deploy a folder structure for customization

Note

Both scripts must be run as root (sudo ./installer-*.sh).

Tested Distributions

The installer scripts have been tested on the following Linux distributions:

Distribution	Version	Docker Script	Podman Script
Debian	12 (Bookworm)	✅ Yes	✅ Yes
Ubuntu	22.04 LTS, 24.04 LTS	✅ Yes	✅ Yes
Fedora	42	✅ Yes	✅ Yes

Preparation (Before You Install)

Server Requirements

If you intend to evaluate PERSEUS in a testing setup or configure a development system, the basic requirements are adequate. For deploying PERSEUS in a live environment where numerous users will be accessing it simultaneously, the suggested requirements must be fulfilled.

	basic requirements	suggested requirements
CPU cores (AVX 512 needed)	2	8
Memory	8 GB	32 GB
Disk space	40 GB	100 GB
Root access	✅ Yes	✅ Yes
Valid SSL certificate	✅ Yes	✅ Yes

Set Environment Variables

Copy the provided .env.dist file to .env. Edit the options for your environment. You can read more about the different options in the documentation.

PERSEUS_WORKERS=16  # Change if you want to change the max. number of processes (usually 2 per CPU core available)
FIRST_OWNER=<ADMIN_LDAP_USERNAME>
FRONTEND_URL=<HOST>  # Replace <HOST> with your host, i.e. https://perseus.pc2.uni-paderborn.de
PERSEUS_PATH_PREFIX=/api

MONGODB_URI=mongodb://mongodb:27017
MONGODB_DATABASE_NAME=<DATABASE_NAME>
MONGODB_DATABASE_GRID_FS_NAME=<FILE_DATABASE_NAME>

LDAP_BIND_USER_DN="<LDAP_BIND_USER>"
LDAP_BIND_PASSWORD="<LDAP_BIND_USER_PASSWORD>"
LDAP_SERVER_URI="<LDAP_SERVER_ADDRESS>"
LDAP_BASE_DN="<LDAP_BASE_DN>"
LDAP_USER_EMAIL_ATTRIBUTE="<LDAP_USER_EMAIL>"
LDAP_USER_FULL_NAME_ATTRIBUTE="<LDAP_USER_FULLNAME>"
LDAP_USER_GROUPS_ATTRIBUTE="<LDAP_USER_GROUP>"
LDAP_USER_FILTER="<LDAP_USER_FILTER>"
LDAP_ALLOWED_GROUPS="<LDAP_LOGIN_GROUP>"
LDAP_SSL_SKIP_VERIFY="False"

DEMO=1  # Leave this line if you want to start PERSEUS in demo mode, otherwise delete it

DEMO mode

If you’re setting up a local test instance, you can leave DEMO=1 enabled. In production, remove this line. When you leave it to ‘1’ your data will be removed on every restart of PERSEUS.

Please also note that it is necessary to include an LDAP configuration in order to run the demo mode. For security reasons, we did not include a demo bypass of the authentication mechanisms. If you don’t want to or cannot connect your institutions’ LDAP, we recommend using an LDAP mock server like slapd-server-mock or mokapi.

Configure CORE_URL in docker-compose.yml

In your docker-compose.yml, locate the perseus-frontend service and set the CORE_URL environment variable to the public API URL of the backend.

#[...]

services:
    perseus-frontend:
        environment:
            - CORE_URL=https://perseus.example.org/api
#[...]

Installer for Docker

This script sets up a Docker-based deployment using either the modern docker compose plugin or legacy docker-compose, depending on what is available.

Main steps

1. Create folders backup, custom-services and custom-states
2. Update system packages using the native package manager
3. Install Docker if missing
4. Install Docker Compose plugin or legacy binary
5. Install Nginx if missing
6. Pull and start containers using Docker Compose
7. Replace Nginx config and restart Nginx

Notes:

• If Nginx default config (/etc/nginx/sites-enabled/default) exists, it will be removed to avoid conflicts.
• Containers are started using the correct Compose command (docker compose or docker-compose) automatically.
• HTTPS and certificate creation is not configured by default — you can integrate mkcert, Certbot, or use a TLS-terminating proxy (e.g., Traefik, Caddy).

Run it

Clone the repository to your server and add config files (see above). Make the script executable chmod +x installer-docker.sh and run it via sudo ./installer-docker.sh.

You can place your custom services or states in the created folders. The folders are mounted into the PERSEUS core-container.

Installer for Podman

This script configures a Podman-based deployment, using rootless containers and an isolated user called perseus.

Main steps

1. Create folders backup, custom-services and custom-states
2. Update system packages
3. Install podman if missing
4. Install podman-compose (via package manager or pip3)
5. Create user perseus (for rootless container execution)
6. Configure /etc/subuid and /etc/subgid for user namespace support
7. Install Nginx
8. Switch to perseus user and run podman-compose
9. Deploy and test Nginx config
10. Start containers and Nginx

Notes:

• If Nginx default config (/etc/nginx/sites-enabled/default) exists, it will be removed to avoid conflicts.
• HTTPS and certificate creation is not configured by default — you can integrate mkcert, Certbot, or use a TLS-terminating proxy (e.g., Traefik, Caddy).

Run it

Clone the repository to your server and add config files (see above). Make the script executable chmod +x installer-podman.sh and run it via sudo ./installer-podman.sh.

You can place your custom services or states in the created folders. The folders are mounted into the PERSEUS core-container.

Updater

To simplify the update process, we provide two scripts that stop the current containers, pull the latest versions of the images, and restart everything cleanly:

• updater-docker.sh – for Docker users
• updater-podman.sh – for Podman users

Both scripts also clean up unused containers and image layers to keep the system clean.

Example usage

We use named volumes for persistent data (like the MongoDB database) so that you can safely run the scripts in production.

# make sure you are in the directory that contains the docker-compose.yml
sudo ./updater-docker.sh

sudo ./updater-podman.sh

Backup

PERSEUS has a built-in backup mechanism. It creates a full backup of all data in the database every night. Read more about this mechanism in the documentation.

To keep the backup data permanently, the install script creates a backup directory. In the directory there are tar files that contain the backup data. You can include this data in your usual backup mechanism. PERSEUS does not automatically rotate and clean up backups. You should therefore check regularly and, if necessary, remove old backups so the hard drive does not fill up. It is good practice to implement a retention policy for backups and to archive weekly, monthly, and yearly backups using the Grandfather-Father-Son method.

Troubleshooting

MongoDB AVX Compatibility Warning

When starting the MongoDB container, you may encounter the following warning or error:

WARNING: MongoDB 5.0+ requires a CPU with AVX support, and your current system does not appear to have that!

This means that your system’s CPU does not support AVX (Advanced Vector Extensions), which MongoDB requires starting from version 5.0.

Solutions:

• Switch to a different system or virtual machine with AVX-capable hardware.
• Change CPU for your virtual machine. When you use QEMU as your hypervisor change the CPU type from “kvm64” to “host” or at least “x86_64-v3”.

More information:

• MongoDB Jira – SERVER-54407
• MongoDB Forums – Compatibility Discussion
• Docker Issue Thread

Test AVX support

You can test AVX support on Linux with:

grep avx /proc/cpuinfo

If the command returns nothing, your CPU does not support AVX.