SignetMail docs Open portal

#Operations

Day-to-day running of a SignetMail server: updating, monitoring, backups, restoring and renewing certificates. All commands run on the server in the folder with docker-compose.yml (for example /opt/signetmail/cloud).

#Overview and users

Overview in the portal shows how many people in the directory get a signature, how many received it in the last 30 days through the Outlook add-in or the Windows agent, and how many signatures, rules and campaigns are live. Users lists everyone with their signature and the last time the add-in or the agent delivered it, with filters for without a signature and with a signature but no activity in 30 days — the quickest way to find PCs where the agent is not installed or people whose Outlook does not run the add-in. Click a name to see Who gets which signature for that person.

#Notifications

Notifications in the portal lists what is waiting for you: signature drafts submitted for your review, campaigns waiting for approval (for Admins of that organization) and, for Owners, a failed directory synchronization or a license that needs attention. The number next to the menu item updates on every page change.

#Synchronizing the directory by hand

The directory is read at start-up and then every 60 minutes (SignetMail:Directory:SyncIntervalMinutes). When you have just changed a job title or phone number in Entra ID or Google Workspace and want it in signatures now, press Synchronize now on Overview. It reads the directory immediately and reports how many people came back.

The button is available to Admins and Owners, and can be used once a minute per organization so the directory source is not hammered. The periodic synchronization in the background is unaffected by it.

#Daily checks (30 seconds)

curl -s https://<host>/health            # {"status":"ok","lastSyncUtc":"…"} — sync time should be < ~2 h old
sudo docker compose ps                   # both services "running"
sudo docker compose logs --tail 100 signetmail-api

Warning signs: lastSyncUtc stuck in the past (Graph permissions or certificate problem), repeated errors in the log, a container restarting.

#Updating

The recommended way is the update script. It takes a backup, pulls the new image, waits for /health and rolls back automatically to the previous version if the server does not come up:

cd /opt/signetmail/cloud
./update.sh

Caddy waits up to 30 seconds and retries requests while the container restarts (lb_try_duration), so the few seconds of an update are normally invisible to users. SignetMail is not in the mail path, so mail keeps flowing in any case.

Manually the same is:

sudo docker compose pull
sudo docker compose up -d

Then verify /health and sign in to the portal. When release notes mention changes to docker-compose.yml, Caddyfile or .env.example, download the new deployment bundle into an empty folder (curl -fsSL https://github.com/AljazEferl/signetmail-releases/releases/latest/download/signetmail-deploy.tar.gz | tar xz) and compare with your files.

To control versions, set SIGNETMAIL_VERSION=1.0.0 (a release) or sha-<commit> in .env instead of latest; rolling back is then a matter of setting the previous value and running docker compose up -d.

#Operating system patches

The operating system patches itself (dnf-automatic, security updates only). Most patches need no restart. A kernel update needs a reboot of about a minute; containers start again on their own. Do it in a quiet window, for example weekly at night:

30 3 * * 0 /opt/signetmail/cloud/update.sh --reboot-if-needed

The script reboots only when needs-restarting -r says it is required.

#True zero downtime

Not needed for most installations. If you must have it (for example an SLA), run two servers behind a load balancer with a shared PostgreSQL database (SignetMail__Database__Provider=Postgres) and update one at a time. See the roadmap in the README.

#Backups

What to protect: the data/ folder (SQLite database with organizations, signatures, versions, rules, access, audit log, statistics and the uploads/ images), your .env, and certs/graph.pfx (or be ready to create a new certificate).

#Encrypted backups to a private GitHub repository

backup.sh creates a consistent snapshot (sqlite3 .backup), packs it, encrypts it with AES-256 (PBKDF2, 600 000 iterations) and pushes it to a private repository with a repository-specific deploy key. The last 30 encrypted copies are kept.

One-time setup:

  1. Create an empty private repository, for example signetmail-backups.
  2. On the server create a key used only for it:
    ssh-keygen -t ed25519 -N "" -f ~/.ssh/backup_deploy
    cat ~/.ssh/backup_deploy.pub
    
    Add the public key in the repository under Settings → Deploy keys → Add deploy key, with Allow write access.
  3. Create the encryption passphrase and store a copy in your password manager:
    openssl rand -base64 32 > .backup-passphrase && chmod 600 .backup-passphrase
    echo 'BACKUP_GIT_REMOTE=git@github.com:<user>/signetmail-backups.git' >> .env
    sudo dnf -y install git      # if git is missing
    ./backup.sh
    
  4. Schedule it daily:
    crontab -e
    0 3 * * * /opt/signetmail/cloud/backup.sh
    

Warning. The passphrase is the only way to open a backup. Store it outside the server (password manager). Never paste it into chats or tickets; if it leaked, generate a new one — new backups use it, old ones stay readable with the old one.

Local copies also remain in backups/.

#Restoring

On a clean server (with the stack installed but stopped):

git clone git@github.com:<user>/signetmail-backups.git
openssl enc -d -aes-256-cbc -pbkdf2 -iter 600000 \
  -in signetmail-<timestamp>.tar.gz.enc -pass file:.backup-passphrase | tar -xz

You get signetmail.db and uploads/. Then:

sudo docker compose down
sudo cp signetmail.db data/ && sudo cp -r uploads data/
sudo chown -R 1654 data
sudo docker compose up -d

Test a restore at least once, before you need it.

#Renewing the Graph certificate

certs/graph.cer expires 730 days after creation. Before that date:

  1. Generate a new pair: move the old certs/graph.* away and run ./setup.sh again.
  2. In Entra → Certificates & secrets upload the new graph.cer (keep the old one until the new one works).
  3. Restart: sudo docker compose restart signetmail-api and check /health.
  4. Remove the old certificate from Entra.

If it expires unnoticed the directory sync fails: lastSyncUtc stops advancing and changes in Entra ID (new employees, new titles) no longer reach signatures.

#TLS certificate

Caddy renews the Let's Encrypt certificate automatically. It needs ports 80 and 443 open and the DNS record intact. If the site shows a certificate warning, check sudo docker compose logs caddy.

#Changing configuration

Edit .env and run sudo docker compose up -d; containers whose settings changed are recreated. Examples: changing PORTAL_ALLOWED_IPS, switching the version, rotating GRAPH_CERT_PASSWORD (after re-running setup.sh).

#Moving to another server

  1. Take a backup and restore it on the new server (see above).
  2. Copy .env and certs/.
  3. Switch the DNS record to the new IP. Caddy requests a new certificate for the new server.
  4. Update nothing in Entra if the host name is unchanged.

#Log locations

sudo docker compose logs [service] — rotated automatically (5 × 10 MB per container). The Windows agent logs to %LOCALAPPDATA%\SignetMail\agent.log on each PC.

#Monitoring suggestions

  • An external uptime monitor on https://<host>/health.
  • An alert if lastSyncUtc is older than three hours.
  • A calendar reminder for the Graph certificate expiry.
  • A calendar reminder to test the restore twice a year.
SignetMail documentation · version main