Customer Hosted: Migrating the Virtru Self-Hosted Gateway to a New Server

Overview

This guide outlines the recommended steps for migrating an existing Virtru Self-Hosted Gateway deployment to a new server. This is applicable for organizations looking to change infrastructure, upgrade operating systems, or relocate services for high availability or scaling reasons.

Pre-Migration Checklist

Before beginning the migration, ensure the following:

• Access to both the old and new servers (SSH/root access).
• Docker or Podman installed on the new server.
• The new server meets the minimum system requirements:
  • 2–4 CPUs (recommended more than 4 for performance)
  • 8–16 GB RAM
  • 60–120 GB disk space
• All necessary DNS and firewall rules are in place (e.g., allow port 25, 587, 443).
• Backup of .env file, TLS certificates, volume data, and DKIM files from the old server.
• Refer to the our document on installing additional server(s) for a high level overview. 

Step 1: Prepare the New Server

Install dependencies:

sudo su

# Podman
yum install podman

# OR

# Docker CE
sudo curl -sSL https://get.docker.com/ | sh

Create working directories:

sudo su
mkdir -p /var/virtru/vg/
mkdir -p /var/virtru/scripts/

Pull the latest container image:

curl -s https://api.github.com/repos/virtru/gateway-install-script/releases/latest \
| grep "browser_download_url.*sh" \
| cut -d : -f 2,3 \
| tr -d \" \
| sudo wget -qi -

Installation:

This part is especially recommended because it creates all the required subdirectories, initializes the container(s) needed to run the gateway successfully. You can copy and paste the configuration from the old server onto the new server afterward.

cd /var/virtru/scripts
sh deploy-gateway-vX.X.sh

Step 2: Backup and Transfer from the Old Server

Backup your existing directories:

Before making any changes/updates, perform a full backup of all directories and files.

cd /var/virtru
mkdir -p backup
cd backup
cp -r /var/virtru/vg .

Stop container(s) on the old server:

# Display container ID
podman ps
# or
docker ps

# Stop container
podman stop <container_id>
# or
docker stop <container_id>

Copy required files:

Manually open each config or install file, copy the content, the paste it in note editor. You will correspond the content to the file on your new server.

cd /var/virtru/vg/env          # Copy .env files
cd /var/virtru/vg/dkim         # Copy .pem and .pub DKIM files
cd /var/virtru/vg/tls          # Copy TLS certs (.crt, .key, fullchain, etc.)
cd /var/virtru/vg/scripts      # Copy any .sh scripts

Alternatively, use SCP to transfer files:

scp -r /var/virtru/vg/* user@NEW_SERVER:/var/virtru/vg/

Step 3: Configure New Server

After copying the files over to the new server

• Review .env file and update GATEWAY_HOSTNAME if the FQDN is changing.
• Confirm IPs, domains, and relay settings are still valid.

sudo chown -R root:root /var/virtru/vg
sudo chmod -R 600 /var/virtru/vg/env/*.env

Edit the setup script to reference the correct container version:

• Release Notes: Customer Hosted Gateway

cd /var/virtru/vg/scripts
vim setup-mode-port.sh

# Update this line to the latest container image:
 containers.virtru.com/gateway:v<version-number>

Start the container(s):

sh setup-mode-port.sh

Verify logs:

docker logs -f <container_name>
# or
podman logs -f <container_name>

Step 4: DNS & Mail Flow Update

• Update DNS records:
  • Point MX or A records to the new server’s IP/FQDN.
• Update SPF/DKIM/DMARC records if needed.
• Update mail flow rules (in O365 or GSuite):
  • Replace old server IP with new IP in connector or compliance rules.

Step 5: Test the Gateway

• Send a test email to ensure:
  • Email reaches the gateway
  • Email is processed/encrypted and routed back
  • Logging works correctly

Use swaks to simulate SMTP delivery:

swaks --to test@yourdomain.com --server your.gateway.ip --from sender@yourdomain.com

Step 6: Decommission the Old Server

After successful testing and validation:

• Shut down containers
• Wipe sensitive data (optional)
• Remove DNS references

Troubleshooting Tips

• Run docker ps or podman ps to verify containers are running.
• Check /var/virtru/vg/logs for SMTP or policy errors.
• Ensure TLS certs match the GATEWAY_HOSTNAME.
• Confirm necessary ports are open.

Appendix: Useful Commands