ihasmail

https://docs.ihasmail.org/
Admin
ihasmail is a stateless, responsive webmail client for Stalwart Mail Server that manages mail,...
Tokens:41,741
Snippets:302
Trust Score:4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and run from source with npm

Source: https://docs.ihasmail.org/install

Installs dependencies, builds the web and server bundles, and starts the production server on port 8080. A source install is not immutable; npm start runs as an ordinary Node process on a writable filesystem.

```bash
npm install
npm run build          # web/dist + server/dist
npm start              # serves the production build on :8080

```

--------------------------------

### Build and run production from source

Source: https://docs.ihasmail.org/install?q=

Installs dependencies, builds the web and server distributions, and starts the production server on port 8080.

```bash
npm install
npm run build          # web/dist + server/dist
npm start              # serves the production build on :8080
```

--------------------------------

### Run source install under a memory cap with systemd-run

Source: https://docs.ihasmail.org/install

Runs npm start under a cgroup with a 512 MiB memory cap and no swap, reproducing the container's behavior where one process dies and everything else stays up. Without a cap, the process grows until the host's OOM killer chooses a victim.

```bash
systemd-run --user --scope -p MemoryMax=512M -p MemorySwapMax=0 npm start

```

--------------------------------

### Run development modes with npm run dev and dev:mock

Source: https://docs.ihasmail.org/install

Development modes for a source install. npm run dev starts the server on :8080 and Vite on :5173 against a real Stalwart using STALWART_URL in .env; npm run dev:mock uses the built-in mock, which signs in as demo@example.com / demo.

```bash
npm run dev            # against a real Stalwart (STALWART_URL in .env)
npm run dev:mock       # against the built-in mock — no real mailbox needed

```

--------------------------------

### Development modes for source install

Source: https://docs.ihasmail.org/install?q=

Two development modes: one against a real Stalwart server (requires STALWART_URL in .env) and one against the built-in mock. The dev server runs on :8080 and Vite on :5173.

```bash
npm run dev            # against a real Stalwart (STALWART_URL in .env)
npm run dev:mock       # against the built-in mock — no real mailbox needed
```

--------------------------------

### Run ihasmail with a mounted policy file (docker run + policy.json)

Source: https://docs.ihasmail.org/configure?q=

Mount a policy file read-only into the container and pass its path via SETTINGS_POLICY_FILE. The policy.json example shows the defaults, enforced, and changes sections; the server reads the file once at startup and there is no reload signal.

```bash
docker run -d --name ihasmail \
  -e STALWART_URL=https://mail.example.org \
  -e APP_SECRET="$(openssl rand -hex 32)" \
  -e SETTINGS_POLICY_FILE=/etc/ihasmail/policy.json \
  -v /srv/ihasmail/policy.json:/etc/ihasmail/policy.json:ro \
  -p 8080:8080 ghcr.io/coffey-labs/ihasmail:latest
```

```json
{
  "defaults": { "externalSenderBanner": true },
  "enforced": { "externalRecipientConfirm": true },
  "changes": [
    { "version": "20260902084513", "settings": { "externalSenderBanner": true } },
    { "version": "20261014091500", "settings": { "externalLinkWarning": true } }
  ]
}
```

--------------------------------

### IMMUTABLE verification errors

Source: https://docs.ihasmail.org/immutable?q=

The server refuses to start when IMMUTABLE=1 is set but the promise is false. The first error appears when SESSION_FILE still points to /data/sessions.json; the second when /app/ is writable. Both require either fixing the configuration or unsetting IMMUTABLE.

```text
Error: IMMUTABLE is set, but SESSION_FILE is /data/sessions.json. An immutable
instance keeps no durable state of its own: pass SESSION_FILE= (empty) to hold
sessions in memory, or unset IMMUTABLE.
```

```text
Error: IMMUTABLE is set, but /app/ is writable. Run the container with
--read-only (and --tmpfs /tmp), or unset IMMUTABLE.
```

--------------------------------

### Deploy with deploy.sh: default, dry-run, and versioned

Source: https://docs.ihasmail.org/install

Run the deploy script with default settings, a dry run, or a specific version with automatic confirmation. The default uses origin/main and prompts before shipping new commits; --dry-run runs the guards and stops; a named ref with --yes skips the prompt, useful over SSH where there is no tty.

```shell
./deploy.sh                 # origin/main, asks before shipping new commits
./deploy.sh --dry-run       # run the guards and stop
./deploy.sh v2026.8.30 --yes  # a named ref, no prompt (there is no tty over ssh)

```

--------------------------------

### Start ihasmail with docker compose up

Source: https://docs.ihasmail.org/install

Start ihasmail with docker compose to keep sessions across restarts. It publishes port 8080, mounts the named volume ihasmail-data at /data where SESSION_FILE defaults to /data/sessions.json, and sets TRUST_PROXY=1 and IMAGE_PROXY=1. This gives the instance its own state, unlike the immutable shape.

```bash
docker compose up --build -d

```

--------------------------------

### docker run command for ihasmail with Stalwart

Source: https://docs.ihasmail.org/configure?q=

Starts ihasmail with STALWART_URL, STALWART_SERVERS_FILE, and APP_SECRET. Mounts the servers.json file read-only and exposes port 8080.

```bash
docker run -d --name ihasmail \
  -e STALWART_URL=https://mail.example.org \
  -e STALWART_SERVERS_FILE=/etc/ihasmail/servers.json \
  -v /srv/ihasmail/servers.json:/etc/ihasmail/servers.json:ro \
  -e APP_SECRET="$(openssl rand -hex 32)" \
  -p 8080:8080 ghcr.io/coffey-labs/ihasmail:latest
```

--------------------------------

### Pass a policy file to Docker with SETTINGS_POLICY_FILE

Source: https://docs.ihasmail.org/configure

Mount a policy file read-only into the container and name it with SETTINGS_POLICY_FILE. The server only reads the file at startup; there is no reload signal, so editing the policy requires restarting the container.

```bash
docker run -d --name ihasmail \
  -e STALWART_URL=https://mail.example.org \
  -e APP_SECRET="$(openssl rand -hex 32)" \
  -e SETTINGS_POLICY_FILE=/etc/ihasmail/policy.json \
  -v /srv/ihasmail/policy.json:/etc/ihasmail/policy.json:ro \
  -p 8080:8080 ghcr.io/coffey-labs/ihasmail:latest

```

```json
{
  "defaults": { "externalSenderBanner": true },
  "enforced": { "externalRecipientConfirm": true },
  "changes": [
    { "version": "20260902084513", "settings": { "externalSenderBanner": true } },
    { "version": "20261014091500", "settings": { "externalLinkWarning": true } }
  ]
}

```

--------------------------------

### Run ihasmail with Docker (immutable mode)

Source: https://docs.ihasmail.org/immutable

Starts an immutable ihasmail container with a read-only filesystem, a tmpfs for /tmp, and an empty SESSION_FILE. Requires an .env.production file and maps host port 8090 to container port 8080.

```bash
docker run -d --name ihasmail --restart unless-stopped \
  --read-only --tmpfs /tmp \
  -e IMMUTABLE=1 -e SESSION_FILE= \
  --env-file .env.production \
  -p 127.0.0.1:8090:8080 \
  ihasmail:local

```

--------------------------------

### Run ihasmail immutably with docker run

Source: https://docs.ihasmail.org/install

Build and run ihasmail in the recommended immutable mode: the container is read-only with no volume, so the instance is its image plus an environment file. Set STALWART_URL and APP_SECRET in .env first; the run publishes to 127.0.0.1:8090 for a reverse proxy and uses IMMUTABLE=1 with SESSION_FILE empty. IMMUTABLE=1 is checked at startup, so a half-applied switch refuses to boot, and sessions live in memory, signing everyone out on each deploy.

```bash
git clone https://github.com/Coffey-Labs/ihasmail.git
cd ihasmail
cp .env.example .env
# edit .env: STALWART_URL, and APP_SECRET=$(openssl rand -base64 48)
docker build -t ihasmail:local .
docker run -d --name ihasmail --restart unless-stopped \
  --read-only --tmpfs /tmp \
  -e IMMUTABLE=1 -e SESSION_FILE= \
  --env-file .env -p 127.0.0.1:8090:8080 \
  ihasmail:local

```

--------------------------------

### Find disk-write operations in server source

Source: https://docs.ihasmail.org/immutable?q=

Use this command to locate every disk-write operation in the server source. The output shows that only two files write: sessions.ts, which holds the optional session file, and config.ts, which performs a startup probe that writes only to prove it cannot. This confirms that with the session file disabled, no other path writes to disk.

```shell
grep -r "writeFile\|createWriteStream\|mkdir\|rename" server/src/
→ sessions.ts   the optional session file
→ config.ts     the startup probe, which writes only to prove that it cannot
```

--------------------------------

### Build Docker image with version from commit

Source: https://docs.ihasmail.org/install?q=

Computes the version from the commit date and PR/short SHA, then builds the image with IHASMAIL_VERSION set. The tag replaces '+' with '-' because Docker tags cannot contain '+'. If omitted, the build reports 0.0.0 instead of failing.

```bash
V="$(node scripts/version.mjs)"                  # 2026.8.30+pr129
docker build --build-arg IHASMAIL_VERSION="$V" -t "ihasmail:${V/+/-}" .
```
Tokens:
Raw