DeskAlerts v12 — On-Prem Docker Deployment (System Administrator)

DeskAlerts 12 - Preview Version

DeskAlerts 12 is currently under active development and is not production-ready.

This version is available for testing purposes only.
To request access, please contact DeskAlerts Support team.

---

Table of contents

• What you receive
• 1. Server requirements
• 2. Install Docker
• 3. Place the package on the server
• 4. Load Docker images
• 5. Configure .env
• 6. Host data directories
• 7. TLS certificates
• 8. Start the stack
• 9. Post-installation verification
• 10. Autostart after reboot
• 11. Backup
• 12. Version upgrade
• 13. Troubleshooting
• Appendix A — import-images.sh
• Appendix B — Related documentation

---

What you receive

A typical delivery package looks like this:

deskalerts-server-<VERSION>/
├── MANIFEST.txt
├── CHECKSUMS.sha256
├── images/
│   ├── deskalerts-app.tar[.gz]
│   ├── mssql-2022.tar[.gz]      # if in-stack MSSQL
│   └── rabbitmq-4.1.tar[.gz]   # if in-stack RabbitMQ
├── deploy/
│   ├── compose.yml
│   ├── compose.mssql.yml        # optional
│   ├── compose.rabbitmq.yml     # optional
│   └── .env.example
├── sso-gateway/                 # optional — AD SSO MSI
└── docs/
    └── ON_PREM_DOCKER_DEPLOYMENT_ADMIN.md

Read MANIFEST.txt first — it lists the exact version, included images, and compose overlays for your deployment.

---

1. Server requirements

Parameter	Minimum	Recommended
OS	Linux x86_64 (Ubuntu 22.04/24.04, RHEL 8+, Debian 12)	Ubuntu LTS
CPU	4 vCPU	8+ vCPU
RAM	16 GB	32 GB
Disk	50 GB SSD	100+ GB SSD
Network	LAN, DNS name for the server	Static IP / DNS

Inbound ports:

Port	Service	Notes
443	nginx	Primary HTTPS access
1433	MSSQL	Only if external DB access is needed; can stay internal for in-stack MSSQL

Outbound connections (optional):

• Customer SMTP server (port 25/587).
• Active Directory / LDAP (389/636) — audience sync.
• Cline API (HTTPS) — only if Stats Assistant AI is enabled.
• Not required for core operation: Docker Hub, npm, public internet.

2. Install Docker

Follow official Docker documentation to install Docker on your Linux host

3. Place the package on the server

You should receive a tar.gz archive from DeskAlerts support which contains all necessary Docker required to run DeskAlerts server in Docker, named similar to deskalerts-server-12.1.0.2.tar.gz

sudo mkdir -p /opt/deskalerts
sudo chown "$USER":"$USER" /opt/deskalerts
cd /opt/deskalerts

Verify integrity:

cd deskalerts-server-12.1.0.2
sha256sum -c CHECKSUMS.sha256

4. Load Docker images

cd /opt/deskalerts/deskalerts-server-12.1.0.2/images

gunzip -k deskalerts-server-12.1.0.2.tar.gz

docker load -i deskalerts-app.tar

# for in-stack infrastructure:
docker load -i mssql-2022.tar
docker load -i rabbitmq-4.1.tar

Verify:

docker images | grep -E 'deskalerts/|mssql/server|rabbitmq'

All deskalerts/* images must be tagged with the version from MANIFEST.txt.

5. Configure .env

cd /opt/deskalerts/deskalerts-server-12.1.0.2/deploy
cp .env.example .env
chmod 600 .env
nano .env   # or vim

Required parameters

Variable	Description	Example
DESKALERTS_VERSION	Image tag (from MANIFEST)	12.1.0.2
DESKALERTS_SERVER_URL	Public server URL	https://alerts.company.local
DESKALERTS_DB_SERVER	SQL host	mssql (in-stack) or sql01.company.local
DESKALERTS_DB_NAME	Database name	DeskAlerts
DESKALERTS_DB_USER	SQL login	sa or dedicated user
DESKALERTS_DB_PASSWORD_64	DB password in Base64	see below
DESKALERTS_DB_PASSWORD_RAW	Plain SA password (MSSQL overlay)	in-stack only
DESKALERTS_DB_VERSION	Version string stored in DB	12.1.0.2 (on-prem)
DESKALERTS_MS_MOUNT_FOLDER_SOURCE	Host path for media	/opt/deskalerts/data/media
DESKALERTS_MS_MOUNT_FOLDER_TARGET	Path inside container	/app/wwwroot

Encode the DB password:

echo -n 'YourStrong!Passw0rd' | base64 -w0
# output → DESKALERTS_DB_PASSWORD_64

Secrets (change defaults)

Variable	Purpose
DESKALERTS_JWT_KEY	JWT for Workflows (≥ 32 characters)
DESKALERTS_SSO_INTERNAL_SECRET	SSO Gateway ↔ Auth shared secret
DESKALERTS_SETTINGS_API_KEY	Inter-service key for Settings
DESKALERTS_RABBITMQ_PASSWORD	RabbitMQ password (if overlay is enabled)

RabbitMQ (recommended for production)

# generate a password
RABBIT_PASS="$(openssl rand -base64 24)"

# in .env:
DESKALERTS_RABBITMQ_USER=deskalerts
DESKALERTS_RABBITMQ_PASSWORD=<RABBIT_PASS>
DESKALERTS_RABBITMQ_VHOST=deskalerts
DESKALERTS_RABBITMQ_URI=amqp://deskalerts:<RABBIT_PASS>@rabbitmq:5672/deskalerts
DESKALERTS_RABBITMQ_MGMT_URI=http://deskalerts:<RABBIT_PASS>@rabbitmq:15672

In-stack MSSQL

DESKALERTS_DB_MOUNT_FOLDER=/opt/deskalerts/data/mssql

DESKALERTS_DB_PASSWORD_RAW must match the value encoded in DESKALERTS_DB_PASSWORD_64.

External MSSQL / Azure SQL

• Do not use compose.mssql.yml.
• Set DESKALERTS_DB_SERVER=your-sql-host.
• Set DESKALERTS_DB_AZURE_SQL=true for Azure SQL.
• Ensure port 1433 is reachable from containers.

SMTP

DESKALERTS_SMTP_SERVER=smtp.company.local
DESKALERTS_SMTP_PORT=587
DESKALERTS_SMTP_SSL=true
DESKALERTS_SMTP_AUTH=true
DESKALERTS_SMTP_USER=alerts@company.local
DESKALERTS_SMTP_PASSWORD=...

Stats Assistant (optional)

Leave DESKALERTS_ASSISTANT_CLINE_API_KEY empty if outbound internet is unavailable — the rest of the system works normally.

AD SSO (Windows)

1. Install the SSO Gateway MSI on a domain-joined Windows Server (see sso-gateway/INSTALLER.md in the package).
2. In .env:

   DESKALERTS_SSO_GATEWAY_URL=http://<sso-host>:58009
   DESKALERTS_SSO_INTERNAL_SECRET=<shared-secret>

3. DESKALERTS_SSO_INTERNAL_SECRET in .env must equal INTERNAL_SECRET in the MSI configuration.

6. Host data directories

export DA_ROOT=/opt/deskalerts/data
mkdir -p "$DA_ROOT/media/wwwroot/admin/"{images,upload,csv,xlsx,shared-assets,digital-signage-assets}
mkdir -p "$DA_ROOT/media/wwwroot/images/upload_image"
mkdir -p "$DA_ROOT/media/wwwroot/brand"
mkdir -p "$DA_ROOT/media/logs/SyncLog"
mkdir -p "$DA_ROOT/mssql"   # if in-stack MSSQL

# main runs as non-root; MSSQL overlay uses root (user 0:0)
sudo chown -R 1000:1000 "$DA_ROOT/media" || true
sudo chown -R 10001:0 "$DA_ROOT/mssql" || true

In .env:

DESKALERTS_MS_MOUNT_FOLDER_SOURCE=/opt/deskalerts/data/media
DESKALERTS_MS_MOUNT_FOLDER_TARGET=/app/wwwroot
DESKALERTS_DB_MOUNT_FOLDER=/opt/deskalerts/data/mssql

7. TLS certificates

By default nginx generates a self-signed certificate on first start.

Production — custom certificate

Uncomment the volumes section for the nginx service in compose.yml and mount a Let's Encrypt or corporate certificate:

volumes:
  - type: bind
    source: /opt/deskalerts/ssl/live/alerts.company.local
    target: /opt/letsencrypt/live/alerts.company.local
  - type: bind
    source: /opt/deskalerts/ssl/archive/alerts.company.local
    target: /opt/letsencrypt/archive/alerts.company.local

Directory layout follows Certbot conventions (fullchain.pem, privkey.pem).

DESKALERTS_SERVER_URL must match the certificate CN/SAN.

8. Start the stack

cd /opt/deskalerts/deskalerts-server-12.1.0.2/deploy
export DESKALERTS_VERSION=12.1.0.2   # from MANIFEST

In-stack MSSQL + RabbitMQ

docker compose \
  --env-file .env \
  -f compose.yml \
  -f compose.mssql.yml \
  -f compose.rabbitmq.yml \
  up -d --no-build --wait --wait-timeout 300

External database, no RabbitMQ

docker compose --env-file .env -f compose.yml up -d --no-build --wait --wait-timeout 300

--no-build is critical on an isolated server: it prevents Compose from trying to build images from source.

Startup order (automatic)

1. logs-init — prepares the shared log volume (container exits with code 0); db-manager — runs migrations (exits with code 0).
2. main, auth, connection, workflows, settings, smtp, reports, ai — after both one-shots have completed.
3. nginx — after the services it proxies are healthy (pwa starts on its own).

First startup may take 5–15 minutes (MSSQL initialization + migrations).

9. Post-installation verification

docker compose --env-file .env -f compose.yml -f compose.mssql.yml -f compose.rabbitmq.yml ps

Expected state:

• db-manager — exited (0)
• all other app services — running (healthy)

curl -k -I "https://localhost/"
curl -k "https://localhost/auth/health"

From a client browser: https://<DESKALERTS_SERVER_URL>/ — login page.

Change the admin password immediately after first login.

Logs when troubleshooting

docker compose logs logs-init
docker compose logs db-manager
docker compose logs main --tail 100
docker compose logs nginx --tail 50

Besides the container output, every application service writes file logs into the shared volume deskalerts-logs, mounted at /var/log/deskalerts/<service>/ (an errors stream and a 48-hour info stream per service). The logs-init one-shot makes the volume writable before anything starts; a service folder missing there means that service is not writing, not a filter.

The same tree is what the diagnostics bundle is built from: an administrator downloads it in the admin UI under Settings → Logging Configuration (da-diagnostics-<timestamp>.zip) — a plain ZIP with the server logs of all services and the browser's own diagnostics, passed through a sanitizer (secrets removed, user names, e-mails, addresses and host names replaced by stable pseudonyms). It can be opened with any archiver before it is sent to DeskAlerts support; the bundle is also what the AI assistant attaches to a bug report. How support reads it: docs/DIAGNOSTICS_SUPPORT_GUIDE.md (in the DeskAlerts repository).

10. Autostart after reboot

Containers with restart: unless-stopped / on-failure start automatically when the Docker systemd unit is enabled:

sudo systemctl enable docker

11. Backup

Data	Path / object
MSSQL database	/opt/deskalerts/data/mssql (in-stack) or standard SQL Server backup
Media and exports	/opt/deskalerts/data/media
Configuration	/opt/deskalerts/.../deploy/.env (store encrypted)
RabbitMQ	volume rabbitmq-data → docker volume inspect
Server file logs	volume deskalerts-logs (/var/log/deskalerts/<service>/) — optional; keep it when a support case is open, the diagnostics bundle reads from it

12. Version upgrade

1. Obtain a new package from DeskAlerts support (delta or full).
2. docker compose down (without -v to keep volumes).
3. docker load new images.
4. Update DESKALERTS_VERSION and DESKALERTS_DB_VERSION in .env.
5. docker compose ... up -d --no-build --wait.
6. db-manager applies migrations on startup.

Back up the database and media before upgrading.

13. Troubleshooting

Symptom	Likely cause	Action
db-manager exited non-zero	Wrong password / SQL unreachable	Check DESKALERTS_DB_*, db-manager logs
main unhealthy	Database not ready	Wait for MSSQL; docker compose logs mssql
502 from nginx	Service still starting	docker compose ps, wait for healthcheck
pull access denied	Image not loaded	docker load, verify DESKALERTS_VERSION tag
Compose tries to build	Missing --no-build	Add --no-build
SSO not working	SPN / gateway URL	MSI logs, DESKALERTS_SSO_GATEWAY_URL
Email not sent	SMTP or RabbitMQ	Check SMTP env; for outbox — DESKALERTS_RABBITMQ_URI
Stats Assistant empty	No Cline API key / no internet	Expected in air-gap; disable or allow HTTPS

---

Appendix A — import-images.sh

#!/usr/bin/env bash
set -euo pipefail
IMG_DIR="${1:?Usage: import-images.sh /path/to/images}"

for tar in deskalerts-app mssql-2022 rabbitmq-4.1; do
  file="${IMG_DIR}/${tar}.tar"
  [ -f "${file}.gz" ] && gunzip -dk "${file}.gz"
  [ -f "$file" ] && docker load -i "$file" && echo "Loaded $file"
done

docker images | grep -E 'deskalerts/|mssql/server|rabbitmq'

Appendix B — Related documentation

• compose.yml, compose.mssql.yml, compose.rabbitmq.yml — in the deploy/ folder
• docs/RABBITMQ_GUIDE.md — message bus (in DeskAlerts repository)
• apps/servers/dotnet/DeskAlerts.SsoGateway/deploy/INSTALLER.md — AD SSO Gateway
• docs/DIAGNOSTICS_SUPPORT_GUIDE.md — diagnostics bundle (server logs of all services + browser diagnostics, sanitized) and the support-side inspector tool

---