---
path: onboarding/admin-onboarding/infrastructure-operations.mdx
title: Infrastructure deployment and operations
sidebar_label: Infrastructure operations
sidebar_position: 9
slug: infrastructure-operations
pagination_next: null
pagination_prev: null
description: >-
  Guide for DevOps engineers deploying and operating Passwork: Docker deployment,
  high availability architecture, zero-downtime updates, MongoDB backup automation,
  health check monitoring, and air-gapped installation.
keywords:
  - Passwork
  - Docker
  - deployment
  - high availability
  - fault tolerance
  - MongoDB
  - backup
  - update
  - health check
  - air-gapped
  - operations
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

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](https://passwork.pro/tech-guides/standard-installation/linux/intro/)
- [Standard installation: Windows Server](https://passwork.pro/tech-guides/standard-installation/windows-server/intro/)
- [Manual installation: Linux](https://passwork.pro/tech-guides/manual-installation/linux/intro/)

---

## Docker deployment quick reference

The Docker build is the recommended deployment path. The full installation is described in [Standard installation: Linux — online installation](https://passwork.pro/tech-guides/standard-installation/linux/online-installation/).

**Minimum server requirements** before deploying — see [Technical requirements](https://passwork.pro/tech-guides/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](https://passwork.pro/tech-guides/fault-tolerance/intro/).

### 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](#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:**

<Tabs className="tabs-container">
  <TabItem className="tab-item-container" value="shell" label="shell">

  ```shell
  cd /<passwork>/
  ./update.sh
  ```
  </TabItem>
</Tabs>

:::danger 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](https://portal.passwork.pro).
2. Copy both files to `/<passwork>/` on the server.
3. Run:

<Tabs className="tabs-container">
  <TabItem className="tab-item-container" value="shell" label="shell">

  ```shell
  cd /<passwork>/
  ./offline_update.sh
  ```
  </TabItem>
</Tabs>

To skip signature verification if you trust the source:

<Tabs className="tabs-container">
  <TabItem className="tab-item-container" value="shell" label="shell">

  ```shell
  ./offline_update.sh --skip
  ```
  </TabItem>
</Tabs>

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](#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](https://passwork.pro/tech-guides/passwork-update/docker/).

### Linux (non-Docker)

See [Update Passwork: Linux](https://passwork.pro/tech-guides/passwork-update/linux/) and [Update Passwork: Windows Server](https://passwork.pro/tech-guides/passwork-update/windows-server-powershell-module/).

---

## 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)

```bash
#!/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:

```bash
# /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](https://passwork.pro/tech-guides/databases/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](https://passwork.pro/tech-guides/api-and-integrations/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](https://passwork.pro/tech-guides/administration/background-tasks/cron-setup-for-linux/intro/).

### 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](https://passwork.pro/tech-guides/administration/action-history/syslog-and-eventviewer/).

---

## 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](https://passwork.pro/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](https://passwork.pro/tech-guides/standard-installation/linux/offline-installation/)
- [Standard installation: Windows Server — offline installation](https://passwork.pro/tech-guides/standard-installation/windows-server/offline-installation/)
- [Desktop app: air-gapped installation](https://passwork.pro/tech-guides/administration/desktop/get-desktops/air-gapped/)

---

## External components updates

MongoDB and PHP require periodic updates independently of Passwork updates.

For version-specific update guides:
- [MongoDB update](https://passwork.pro/tech-guides/administration/passwork-components-update/mongodb/intro/)
- [PHP update](https://passwork.pro/tech-guides/administration/passwork-components-update/php/intro/)