Porta VM Disaster Backup and Restore

This page covers:

• how Porta VM creates and stores database backups,
• how to take one manually,
• how to restore from one,
• and how to recover from data loss affecting one or several machines in a replication group.

For diagnosing why a failure happened in the first place, see the Porta VM Troubleshooting guide.

Caution

Recovery procedures on this page include destructive steps that wipe a machine’s database. Always take a manual backup before starting unless an automatic backup younger than three hours is known to be safe and intact.

How automatic backups work

Every three hours, Porta creates a backup of the database on a non-primary machine (usually the arbiter) and stores it inside the porta container at:

/var/www/storage/app/Porta-Backups

Each backup is a ZIP archive containing an SQL dump of the database. The archive name has the format:

machine_type-machine-connection_name-backup-Y-m-d-H-i-s.zip

For example, a backup created on the arbiter at 14:30 on 2026-05-20 would be named arbiter-machine-mysql-3-backup-2026-05-20-14-30-00.zip.

Note

These archives are intended for disaster recovery from catastrophic data loss. They are not a substitute for application-level export of show data — Porta show data, media references, and template definitions all live in the same database and are restored together.

Alternate setups

The location and frequency change depending on the topology:

• Single-machine setup: backups are created on the single machine.
• Single machine with an isolated backup machine: backups are created on both machines independently.
• Three-machine replication group: backups run on the arbiter by default. Verify by looking for the most recent backup ZIP inside each machine’s porta container.

Container and port reference

Machine role	Database container	MySQL port	Replication port
Main	porta-db	3306	33061
Backup	porta-db-2	3307	33062
Arbiter	porta-db-3	3308	33063

Checking replication health before recovery

Before any destructive recovery step, capture the current state of the replication group so you can confirm afterwards that the recovery worked:

• porta_all_group_status shows the replication group as reported by every machine. Requires correct /etc/hosts entries on the machine running it.
• porta_group_status shows the replication group as reported by this machine only.
• porta_main_db_logs, porta_backup_db_logs, and porta_arbiter_db_logs show the MySQL error log on each role. Use the _follow variants to tail live output.

Manually creating a backup

Take a manual backup any time, especially before a destructive operation like a database reset.

Inside the VM, run:

porta_backup_db

The resulting backup is saved inside the porta container at /var/www/storage/app/Porta-Backups, with the same naming format as automatic backups.

Tip

The manual backup helper uses the same artisan command (php artisan backup:run --only-db --disable-notifications) as the automatic schedule, so the output is interchangeable with the scheduled backups.

Restoring from a backup

Inside the VM, run:

porta_restore_db

The helper prompts with a list of available backup files in the local backups directory. Enter the number corresponding to the backup you want to restore and press Enter.

Caution

Restoring overwrites the current database contents on the target machine. If the target machine is part of a healthy replication group, removing this machine’s data without coordinating with the rest of the group can cause a replication state mismatch. Use the multi-node disaster recovery procedure when more than one machine is affected.

Single-node disaster recovery

Use this procedure when one machine in a replication group has lost data, but the other machines in the group are healthy and have an authoritative copy of the data.

There is no need to use a backup file in this case — the broken database can simply be reset, after which it will join the existing group as a new member and replication will fill it in from the surviving machines.

1. Confirm the rest of the group is healthy:

   porta_all_group_status

   At least one machine must show MEMBER_STATE of ONLINE and MEMBER_ROLE of PRIMARY. The other surviving machine should be ONLINE.

2. On the broken machine only, take a manual backup if the database is at least running (even if replication is failing). This is a precaution in case the machine has data the rest of the group does not:

   porta_backup_db

3. On the broken machine, reset its database:

   Warning

   porta_reset_db wipes all data in the database container on this machine. Only run it on the machine you are recovering.

   porta_reset_db

4. Wait for the container to come back up. It will join the existing group and begin replicating data from the surviving machines. The amount of time depends on how much data has to be transferred.

5. Re-check the group:

   porta_all_group_status

   When the recovered machine reaches ONLINE, the restoration is complete.

Multi-node disaster recovery

Use this procedure when two or more machines have lost data, or when the entire site has gone down and no machine still holds the authoritative current data.

1. Identify the machine that holds the backup you want to restore from. Ideally this is the machine that has the most recent backup, regardless of role.

2. If any database container on any machine is currently down, start it so its data is accessible. Replication will fail to start, which is expected — only the database service itself needs to be running:

   docker start porta-db    # or porta-db-2, porta-db-3 depending on role

3. Take a manual backup on each machine that can be brought up, even if its data is suspect. This is a precaution against losing recoverable transactions:

   porta_backup_db

   Backups live in the porta container, not in the database container, so taking a backup here does not interfere with the reset in the next step.

4. Stop each machine’s database container so the next step starts from a clean slate. From each machine:

   docker stop porta-db    # or porta-db-2, porta-db-3

5. On the machine holding the desired backup, reset that machine’s database:

   Warning

   porta_reset_db wipes the database container on this machine. The backup ZIPs in /var/www/storage/app/Porta-Backups survive because they live in the porta container, not the database container.

   porta_reset_db

6. Restore from the chosen backup on the same machine:

   porta_restore_db

   When prompted, select the backup you identified in step 1.

7. Wait for the restore to complete. This machine is now the authoritative primary.

8. On each of the other machines, reset the database so they will rejoin the new group as fresh members and replicate from the restored primary:

   porta_reset_db

9. Each machine should join the group and begin replicating data from the restored primary. Confirm with:

   porta_all_group_status

   When every machine reaches ONLINE, the restoration is complete.

Failover recovery with Unreal Engine

When a PX running Porta fails, the Unreal project rendering on the connected RX needs to be pointed at the backup PX so the show can continue. This is controlled by batch files on the RX desktop.

Total machine failure — power or network loss

If the main PX has completely lost power or network connectivity:

1. On the RX, run the desktop batch file make px2 primary.bat to switch the running Unreal project to the backup PX.
2. Continue the show on the backup PX while the main PX is repaired.
3. Once the main PX is recovered, run make px1 primary.bat on the RX to switch back.

Partial machine failure — service or performance loss

If the main PX is still running but its socket server is degraded or its performance has dropped:

1. On the failed PX, stop the Porta socket server:

   docker stop porta-socket

2. On the RX, run make px2 primary.bat to switch the running Unreal project to the backup PX.

3. Continue the show on the backup PX while the main PX is investigated.

4. When the main PX is healthy again, restart its socket server:

   docker start porta-socket

   Then run make px1 primary.bat on the RX to switch back.