# Utility Scripts

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

## `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:

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

Verify the installation with:

```bash
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:

```powershell
.\scripts\install-stalwart-cli.ps1
```

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

```powershell
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:

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

Copy the printed value into `.env`:

```dotenv
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:

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

```bash
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

```bash
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
```