Overview
Before you apply a Teramind update (the TMU file upload on the Settings → Update Teramind page), you should make a full backup of your databases.
A Teramind update changes both the application services and the database schema/data. If anything goes wrong during the update, a database backup is the only reliable way to restore your data. This guide walks you through making a proper backup over SSH.
Estimated time: 5–15 minutes (depends on database size). You will need: SSH access to your Teramind server and root/sudo (or the prod) account.
What Gets Backed Up
A Teramind on-prem instance stores data in two databases:
Database | What it holds | Where it runs |
PostgreSQL | Core application data: accounts, instances, settings, policies, configuration. This is the critical one for a TMU update. | On the server host, port |
ClickHouse | Business Intelligence / analytics & reporting data |
|
For a safe update, always back up PostgreSQL. Backing up ClickHouse as well is recommended if you rely on BI/reporting history.
Redis (port 6379) is a cache only and does not need to be backed up.
Step 1: Connect to your server
Run the following command in your terminal:
ssh <user>@<your-teramind-server-ip>
All commands below are run on the server. Use sudo if you are not already root.
Step 2: Create a Place to Store the Backup
Pick a directory with enough free space (ideally on a different disk or an external/mounted volume, so a disk failure doesn't take your backup with it).
# Create a timestamped backup folder
BACKUP_DIR="/var/backups/teramind/$(date +%Y%m%d-%H%M%S)"
sudo mkdir -p "$BACKUP_DIR"
echo "Backups will be saved to: $BACKUP_DIR"
# Check you have enough free space first
df -h "$BACKUP_DIR"
Step 3: Back Up PostgreSQL (required)
PostgreSQL holds the core data and is the database the update migrates. Read the connection details from the instance configuration, then dump the database.
3a. Find the Database Connection Details
The connection string is stored in the application service environment. You can read it like this:
sudo docker exec server-1 sh -lc 'env | grep MASTER_DATABASE_URL'
You will see something like:
MASTER_DATABASE_URL=postgresql://teramind:password>@127.0.0.1:5432/teramind
From that URL: user = teramind, host = 127.0.0.1, port = 5432, database = teramind.
3b. Create the PostgreSQL Backup
Use the password from the URL above. The recommended format is a compressed custom-format dump (-Fc), which is fast to create and easy to restore selectively.
# Paste the password from MASTER_DATABASE_URL (note: a literal % in the URL is
# URL-encoding, e.g. %24 means $ — use the decoded password here)
export PGPASSWORD='<your-postgres-password>'
# Dump the primary application database (custom compressed format)
pg_dump -h 127.0.0.1 -p 5432 -U teramind -Fc -d teramind \
-f "$BACKUP_DIR/teramind-postgres.dump"
# Also back up the secondary database used by some deployments
pg_dump -h 127.0.0.1 -p 5432 -U teramind -Fc -d tm_onsite \
-f "$BACKUP_DIR/tm_onsite-postgres.dump" 2>/dev/null || true
# Clear the password from your shell when done
unset PGPASSWORD
If you prefer a plain SQL file instead, replace -Fc with -Fp and use a .sql extension. Plain SQL is human-readable but larger and slower to restore.
3c. Verify the PostgreSQL Backup
A backup you can't verify is not a backup. Confirm the file exists, is non-empty, and is readable by the restore tool:
ls -lh "$BACKUP_DIR"/*.dump
# Custom-format dumps: list their contents (should print many lines, no errors)
pg_restore --list "$BACKUP_DIR/teramind-postgres.dump" | head
If pg_restore --list prints the table of contents without errors, the dump is valid.
Step 4: Back up ClickHouse (recommended for BI Analytics)
ClickHouse stores reporting/analytics data. Skip this section if you do not need historical BI data preserved across the update.
# List the ClickHouse databases (the BI database is usually tm_onsite_a)
sudo docker exec clickhouse clickhouse-client --query "SHOW DATABASES"
The simplest portable backup is to export each table to compressed files. The quickest full-data-directory snapshot, however, requires the service to be quiescent. The safe, supported approach is a native ClickHouse backup:
# Native ClickHouse backup to a tar file on disk (ClickHouse 22.8+)
sudo docker exec clickhouse clickhouse-client --query \
"BACKUP DATABASE tm_onsite_a TO Disk('backups', 'tm_onsite_a.zip')"
If the backups disk is not configured on your instance, use a per-table export instead:
sudo docker exec clickhouse sh -lc '
for T in $(clickhouse-client --query "SHOW TABLES FROM tm_onsite_a"); do
clickhouse-client --query "SELECT * FROM tm_onsite_a.$T FORMAT Native" \
| gzip > "/var/lib/clickhouse/'$T'.native.gz"
done
'
# Then copy the exported files out of the container into your backup folder:
sudo docker cp clickhouse:/var/lib/clickhouse/. "$BACKUP_DIR/clickhouse/"
If you operate ClickHouse with the optional clickhouse-backup tool (HA / cloud-replicated setups), you can instead run clickhouse-backup create and clickhouse-backup upload per your existing remote-storage configuration.
Step 5: Back Up the Configuration File (recommended)
The instance configuration is small but important for a clean restore:
sudo cp /usr/local/teramind/conf/teramind.config "$BACKUP_DIR/teramind.config.bak"
Step 6: Confirm and Secure Your Backup
# Review everything you captured
ls -lhR "$BACKUP_DIR"
# (Optional but recommended) move/copy the backup OFF this server
# e.g. to your workstation:
# scp -r <user>@<server-ip>:"$BACKUP_DIR" ./teramind-backup
A backup that lives only on the same server it protects offers limited safety. Copy it to a separate machine or storage location whenever possible.
Step 7: Update the Server
1. Login to your Teramind Dashboard.
2. Go to My Account.
3. Under the Software section, click the Select update file button.
4. Select your .tmu update file (you can download it from the Self-Hosted portal).
5. Click the Update Teramind button.
6. In the confirmation dialog, check "I made a backup" and click Confirm.
How to Restore (if an update fails)
Only restore if an update fails and you need to roll back. Restoring overwrites current data.
PostgreSQL (custom-format dump):
export PGPASSWORD='<your-postgres-password>'
# --clean drops existing objects before recreating them from the backup
pg_restore -h 127.0.0.1 -p 5432 -U teramind -d teramind --clean --if-exists \
"$BACKUP_DIR/teramind-postgres.dump"
unset PGPASSWORD
ClickHouse (native BACKUP):
sudo docker exec clickhouse clickhouse-client --query \
"RESTORE DATABASE tm_onsite_a FROM Disk('backups', 'tm_onsite_a.zip')"
If you are unsure about any restore step, contact Teramind Support before proceeding - an incorrect restore can make data loss worse.
Quick Reference (copy-paste)
# --- PostgreSQL backup (the essential one) ---
BACKUP_DIR="/var/backups/teramind/$(date +%Y%m%d-%H%M%S)"
sudo mkdir -p "$BACKUP_DIR"
sudo docker exec server-1 sh -lc 'env | grep MASTER_DATABASE_URL' # read creds
export PGPASSWORD='<your-postgres-password>'
pg_dump -h 127.0.0.1 -p 5432 -U teramind -Fc -d teramind -f "$BACKUP_DIR/teramind-postgres.dump"
pg_restore --list "$BACKUP_DIR/teramind-postgres.dump" | head # verify
unset PGPASSWORD
echo "Backup saved to $BACKUP_DIR"
Notes:
This guide applies to Teramind on-prem instances using PostgreSQL (V2 / Next-Gen). Database names and ports shown (teramind on 127.0.0.1:5432, ClickHouse tm_onsite_a) are the standard defaults; verify yours with the commands in Step 3a.