Infrastructure deployment and operations

This page is for DevOps engineers and system administrators responsible for deploying, scaling, and maintaining the Passwork server infrastructure. It provides an operational overview and links to the detailed technical documentation for each area.

---

Deployment options

Method	When to use
Docker (recommended)	Most deployments; easiest to update and maintain
Linux (manual)	Air-gapped or highly controlled environments
Windows Server	Organizations standardized on Windows infrastructure

For installation instructions, see:

• Standard installation: Linux
• Standard installation: Windows Server
• Manual installation: Linux

---

Docker deployment quick reference

The Docker build is the recommended deployment path. The full installation is described in Standard installation: Linux — online installation.

Minimum server requirements before deploying — see Technical requirements.

Post-installation checklist:

• Passwork accessible at target URL over HTTPS
• SSL certificate valid and trusted
• SMTP configured and test email delivered
• License applied and user count confirmed
• Admin account created with 2FA enabled
• Background tasks (cron) running

---

High availability architecture

Passwork supports a fault-tolerant architecture for organizations that require high availability. It requires the advanced license.

Minimum HA configuration

Load balancer (HAProxy, Nginx, Traefik, or cloud LB)
    ├── Passwork app server 1
    ├── Passwork app server 2
    └── Passwork app server N

MongoDB replica set (minimum 3 nodes)
    ├── Primary
    ├── Secondary 1
    └── Secondary 2 (or Arbiter)

Key properties:

• No sticky sessions required — sessions are stored in MongoDB and valid across all app servers
• When one app server fails, the load balancer routes traffic to remaining healthy nodes automatically
• When the MongoDB Primary fails, the replica set elects a new Primary automatically

For detailed HA configuration, see Fault tolerance.

Load balancer health check

Configure your load balancer to probe the /api/v1/app/health-check endpoint on each app server. See Health check and monitoring below for the endpoint format and token configuration.

---

Updates

Docker

Passwork distributes updates as signed archives, not as Docker Hub images. The update.sh script included in your Passwork installation directory handles the full update process: it checks group membership, downloads the latest signed archive, verifies the digital signature, creates a database and config backup, then applies the update.

Online update:

shell

cd /<passwork>/
./update.sh

Proxy environments

The script uses curl. If your network requires a proxy, set the environment variables first: export http_proxy=http://proxy.example.com:8080 export https_proxy=http://proxy.example.com:8080

Offline update (air-gapped servers):

1. Download the latest Passwork archive and .sig signature file from the Customer Portal.
2. Copy both files to /<passwork>/ on the server.
3. Run:

shell

cd /<passwork>/
./offline_update.sh

To skip signature verification if you trust the source:

shell

./offline_update.sh --skip

Both scripts create a database backup (./backup/mongo-*.dump) and a config archive (./conf-*.tar.gz) before making any changes.

HA deployments — rolling update:

Update servers one at a time to maintain availability:

1. Remove server N from the load balancer pool
2. Run ./update.sh on server N
3. Verify the health check passes (see Health check and monitoring below)
4. Return server N to the pool
5. Repeat for remaining servers

For the full update reference, see Update Passwork: Docker.

Linux (non-Docker)

See Update Passwork: Linux and Update Passwork: Windows Server.

---

MongoDB backup

Backups are the most critical operational task for an on-premise Passwork deployment. A database loss without a backup means permanent data loss.

Automated backup script (Docker)

#!/bin/bash
set -euo pipefail

PASSWORK_DIR="/<passwork>"
BACKUP_DIR="/backups/passwork"
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/passwork_${DATE}.archive"

mkdir -p "$BACKUP_DIR"

# Create dump
docker compose -f "${PASSWORK_DIR}/docker-compose.yml" exec -T mongodb \
  mongodump --archive --gzip | gzip > "${BACKUP_FILE}.gz"

echo "Backup created: ${BACKUP_FILE}.gz"

# Retain last 30 days
find "$BACKUP_DIR" -name "passwork_*.gz" -mtime +30 -delete

Schedule via cron:

# /etc/cron.d/passwork-backup
# Daily backup at 02:00
0 2 * * * root /opt/scripts/backup-passwork.sh >> /var/log/passwork-backup.log 2>&1

Backup storage recommendations

• Store backups in a separate location from the Passwork server (object storage, NAS, offsite)
• Encrypt backup archives before transfer or storage
• Store the Passwork encryption key (config.env) separately from the database backup
• Test restoration every 1–3 months

For backup and restore commands, see MongoDB: backup creation and restoration examples.

---

Health check and monitoring

Health check endpoint

GET /api/v1/app/health-check
Authorization: Bearer <HEALTH_CHECK_TOKEN>

Returns HTTP 200 with a JSON status object. Integrate with your monitoring tool (Prometheus blackbox exporter, Datadog synthetics, Zabbix HTTP check, Nagios, etc.).

For endpoint details, see Health check.

Background tasks monitoring

LDAP synchronization, password expiration checks, and email notifications run as background tasks. If cron stops running, LDAP group membership becomes stale.

Monitor background task status:

1. In Passwork admin panel → Settings → Background tasks — check "Last run" timestamps
2. Set an external alert if the health check endpoint stops responding
3. Set a cron monitor (e.g. Cronitor, Dead Man's Snitch, or a custom heartbeat) to alert if the backup cron job doesn't run on schedule

For cron configuration, see Background tasks: cron setup for Linux.

Key metrics to monitor

Metric	Alert threshold	Where to check
Health check HTTP status	≠ 200	Load balancer / monitoring tool
MongoDB replica set primary	No primary for > 30s	MongoDB monitoring
Disk usage (backup storage)	> 80%	OS monitoring
Cron last run	> 2× expected interval	Cron monitor
SSL certificate expiry	< 30 days remaining	Certificate monitoring
Background task errors	Any error	Passwork admin panel

---

Syslog and SIEM integration

Passwork can forward all action history events in CEF (Common Event Format) to the local syslog or Windows Event Log, which your SIEM collector can then pick up.

Enable in Settings → Action History → Settings → Record action history to syslog or Windows Event Log.

For configuration details, see Event forwarding overview.

---

Air-gapped and offline deployments

Passwork supports fully offline installation for environments without internet access.

Key considerations:

• Download the offline installation package from the Customer Portal before disconnecting
• The Docker image must be pulled and saved on an internet-connected machine, then transferred via docker save / docker load
• Updates follow the same process — download offline package, transfer, apply

For offline installation guides:

• Standard installation: Linux — offline installation
• Standard installation: Windows Server — offline installation
• Desktop app: air-gapped installation

---

External components updates

MongoDB and PHP require periodic updates independently of Passwork updates.

For version-specific update guides:

• MongoDB update
• PHP update

LLM version