Porta VM Support Checklist

Run this checklist on a live Porta VM deployment as the first step when something isn’t working. It takes about five minutes top-to-bottom and is designed to surface the most common sources of configuration drift — IP changes, stopped containers, stale /etc/hosts entries, and integration misconfiguration — before deeper troubleshooting.

Throughout this page:

• <VM-IP> means the Porta VM’s IPv4 address on the local network — the static IP, if one is configured.
• <HOST-IP> means the Windows host’s IPv4 address (often on a d3net adapter).
• The VM SSH user is always portavm.

Identify the deployment

• The VM is running. In VirtualBox on the Windows host, the Porta VM is in state Running. Headless mode is fine.

• The VM hostname is unique.

  Connect to the VM using SSH (replace the command below with your own values):

  • portavm is the username you will be connecting as
  • VM-IP is the VM’s IPv4 address on the network

  ssh portavm@<VM-IP>
  
  # Example: ssh portavm@192.168.50.9

  Caution

  The terminal prompt after connecting should not show portavm@Porta-VM if you run more than one Porta VM. If it does, the identity reset was never run after import, and ARP, DHCP, and database replication will conflict.

• Capture the VM’s IP and hostname. Inside the VM run:

  ~/scripts/vm_info.sh

  This prints:

  • The hostname.
  • The IPv4 address.
  • The MAC address.
  • The contents of /etc/hosts.

• Capture the Porta version. Inside the VM run porta_check_version (available on VM image 0.9.14.2 and newer).

• Capture the Porta Manager version. Inside the VM run mngr_check_version (available on VM image 0.9.14.2 and newer).

Docker containers

Run docker ps -a inside the VM. The expected baseline is:

Porta application stack

The application stack runs one set of these, named according to the machine’s role in the replication group:

• porta is running, with ports 8080 (UI) and 8000 (API) published.
• One of the following is running:
  • porta-db (ports 3306 / repl 33061) — main machine.
  • porta-db-2 (ports 3307 / repl 33062) — backup machine.
  • porta-db-3 (ports 3308 / repl 33063) — arbiter machine.
• porta-socket is running, with port 6001 published.
• porta-redis is running, with port 6379 published.

Porta Manager stack

Every Porta VM runs the Porta Manager stack regardless of role:

Note

Container names are likely suffixed with -1 (e.g. porta-manager-app-1) due to the way Docker handles naming. This is normal and expected.

• porta-manager-app is running, with port 88 published.
• porta-manager-horizon is running. No published port.
• porta-manager-task is running. No published port.
• porta-manager-db is running, with port 3310 published.
• porta-manager-redis is running, with port 6378 published.

Caution

Any container using a portadisguise/… image with a name that doesn’t appear in the lists above must be stopped and removed. Then restart porta and porta-socket.

Porta application access

• Porta is being accessed in the browser at http://<VM-IP>:8080, not http://localhost:8080.
  • The VM is a separate host on the network, and localhost reaches the Windows machine, which is not running Porta.
• The same rule applies to the API: http://<VM-IP>:8000.
• The database status icon in the Porta UI is green.
• The database health dashboard is all green at http://<VM-IP>:8000/health.
• The Horizon queue dashboard at http://<VM-IP>:8000/horizon shows no piled-up failed jobs.
• In Porta, under Window → Settings → Integrations → Socket Server, the URL is http://<VM-IP>:6001.
• In Porta, under Window → Settings → Channels, the expected channels are listed.
  • If they aren’t, click the sync button in the channel panel.
• In Porta, under Window → Settings → Preference, the following are enabled if you use group sequences:
  • “Enable Play Groups”
  • “Enable play group sequence”
• In Porta, under Window → Settings → Preference, “Local Live Preview” is set to your preferred value.

Porta Manager access

• Porta Manager is reachable at http://<VM-IP>:88.

  Note

  Port 88, not 8080. The default Porta Manager admin sign-in is superadmin@disguise.one with the Porta VM password provided by Disguise.

• In Porta Manager, under Porta Configuration Management → Machines, the IP address shown for each machine row matches the actual static IP of that VM.

  Tip

  If a machine row’s IP doesn’t match reality, that is almost certainly the underlying cause of any “Porta lost the database” or “Bridge can’t connect” symptom. See Changing the IP of Porta On Prem.

Designer, Unreal, and Porta Bridge

• Designer is running, with the expected project open.

• The active Designer project matches the page, template, and channel that Porta is configured to use.

• Unreal (if used) is running, plugins are up to date, and the expected project is open.

• Unreal’s Porta plugin settings reference the correct Porta instance:

  • Connection URL: http://<VM-IP>:6001 or http://porta-socket.server:6001
  • API URL: http://<VM-IP>:8000 or http://porta.server:8000

• If using the porta-socket.server or porta.server hostnames, the Unreal machine’s Windows hosts file maps them to the VM’s current static IP.

• Porta Bridge is running.

• Only a single instance of Porta Bridge is running.

  Caution

  Check the Windows system tray and Task Manager on the Bridge machine. Multiple instances of Porta Bridge cause races. If duplicates are found, stop all instances and restart Bridge.

• Porta Bridge is up to date.

• Porta Bridge is connected to the correct Porta and Designer.

• Porta Bridge’s configuration matches the deployment:

  • API URL: http://<VM-IP>:8000
  • Socket Server URL: http://<VM-IP>:6001 or http://porta-socket.server:6001 (with matching Windows hosts entry if using the hostname)
  • HTTP Listener IP Address: the Windows host IPv4 (where Bridge runs)

• The Windows host firewall on the Bridge machine has port 1500 open for inbound traffic. The Scheduler uses this port to drive transport and media requests.

Network and firewall

• The VM has a static IP. Inside the VM:

  ~/scripts/static_ip_info.sh

  This prints the contents of /etc/netplan/99-portacfg.yaml. If it’s empty, the VM is on DHCP and the IP can change. Depending on your network, this may already have caused the current incident. See Manually Setting Up a Static IP.

• The VM’s /etc/hosts file maps the replication group correctly. Inside the VM run view_hosts_file. For a single-machine setup the only critical entry is 127.0.0.1 localhost. For replication, each VM must have:

  <MAIN IP>     porta-db
  <BACKUP IP>   porta-db-2
  <ARBITER IP>  porta-db-3

  Caution

  Stale entries here are the most common cause of “node won’t join the group” complaints. Each line must match the current static IP of the corresponding machine.

• The Windows host firewall allows inbound traffic on the following ports:

  • MySQL ports: 3306, 3307, 3308
  • Group replication ports: 33061, 33062, 33063
  • Socket server: 6001
  • Porta UI: 8080
  • Porta API: 8000
  • Porta Manager: 88
  • Porta Bridge HTTP Listener: 1500 (on the Bridge machine, if separate)

  The VM bridges its network adaptor into the LAN, so these ports must also be reachable from the host’s perspective.

Disk and resources

• The VM has free disk space. Inside the VM:

  check_diskspace

  Anything under approximately ten percent free on / is a problem. The porta container will fail to write logs and the database will refuse new transactions.

• Docker has no large reclaimable cache. Inside the VM:

  docker_disk_usage

  If “Images Reclaimable” is more than a few gigabytes, free it with:

  docker image prune -af

  This removes unused images only — volumes (your data) are preserved.

• VirtualBox has allocated enough host resources to the VM. Confirm in VirtualBox Settings → System that the VM has at least:

  • 8 GB RAM
  • 4 vCPU
  • A CPU that supports AVX2

  Under-allocation is a frequent cause of:

  • rcu: detected stalls on CPUs/tasks messages.
  • Slow boot.
  • Intermittent container restarts.

When a check fails

For each failed check, see the matching section in the Porta VM Troubleshooting guide. Most paths from a failed check to a recovery procedure are documented there.