ep-stalwart-v2/scripts/README.md

Utility Scripts

These scripts support the EternityMail Docker Compose deployment. Run them from the repository root.

Full server backup and restore

backup-server.sh and backup-server.ps1 create a portable .tar.gz backup containing all Stalwart named volumes, Roundcube database/configuration, and deployment settings. They stop the mail services for a consistent backup and start them after completion.

restore-server.sh and restore-server.ps1 restore that archive to Linux or Docker Desktop. They refuse to overwrite a deployment unless passed --force or -Force; that option permanently replaces current mail and Roundcube data. See the repository README for migration steps and commands.

install-stalwart-cli.sh

Installs the latest official stalwart-cli release on Linux. The upstream installer places the binary in the system executable path, normally /usr/local/bin.

Requirements:

• Linux
• curl
• sudo, unless the script is run as root

Usage:

chmod +x scripts/install-stalwart-cli.sh
./scripts/install-stalwart-cli.sh

Verify the installation with:

stalwart-cli --version

install-stalwart-cli.ps1

Installs the latest official stalwart-cli release on Windows using the upstream PowerShell installer. The official installer uses a user-local executable directory and updates the user PATH.

Requirements:

• Windows PowerShell 5.1 or PowerShell 7+
• Internet access to GitHub Releases

Usage from PowerShell:

.\scripts\install-stalwart-cli.ps1

Open a new terminal if the current shell cannot find the command, then verify it:

stalwart-cli --version

The scripts always download the current release from the official Stalwart CLI GitHub repository. Review the upstream release and installer before using them in a restricted or audited environment.

generate-des-key.sh

Generates a random 24-character alphanumeric value for Roundcube's RC_DES_KEY setting.

Requirements:

• Linux, macOS, or another Unix-like shell
• /dev/urandom

Usage:

chmod +x scripts/generate-des-key.sh
scripts/generate-des-key.sh

Copy the printed value into .env:

RC_DES_KEY=<generated-value>

Keep this value stable after Roundcube has been deployed. Changing it can make existing encrypted session data unreadable.

generate-des-key.ps1

Generates the same type of 24-character key using PowerShell.

Requirements:

• PowerShell 5.1 or PowerShell 7+

Usage from PowerShell:

.\scripts\generate-des-key.ps1

Copy the printed value into RC_DES_KEY in .env.

setup-data-dirs.sh

Creates the host directories used by the Stalwart and Roundcube containers and assigns ownership of the Stalwart directories to uid/gid 2000, which is the user used by the Stalwart image.

Requirements:

• Linux or another Unix-like host
• Permission to create and change ownership under DATA_ROOT

The script does not read .env automatically. Set DATA_ROOT explicitly when running it:

chmod +x scripts/setup-data-dirs.sh
sudo DATA_ROOT=/opt/eternitymail ./scripts/setup-data-dirs.sh

When DATA_ROOT is omitted, the script uses /opt/eternitymail.

The created directories are:

• $DATA_ROOT/stalwart/etc
• $DATA_ROOT/stalwart/data
• $DATA_ROOT/stalwart/certs
• $DATA_ROOT/roundcube-db
• $DATA_ROOT/roundcube-config

Only $DATA_ROOT/stalwart is changed to uid/gid 2000:2000; the MariaDB container manages its own data-directory permissions.

Typical order

cp .env.example .env
scripts/generate-des-key.sh
sudo DATA_ROOT=/opt/eternitymail ./scripts/setup-data-dirs.sh
docker compose config --quiet
docker compose up -d