Porta VM Diagnostics Cheatsheet

This page lists where everything is and how to look at it on a Porta VM deployment. Treat it as a reference, not a procedure — pick the entry that matches the symptom being diagnosed.

• For a structured walk-through of common symptoms, see the Porta VM Troubleshooting guide.
• For a five-minute first-pass check, see the Porta VM Support Checklist.

Quick-fire data collection

Inside the VM, either over SSH or directly at the VirtualBox console:

# Bundles diagnostics under ~/logs/collected_data/YYYYMMDD/HH-SS/.
# Requires VM image 0.9.14.2 or newer.
collect_data

# Runs the full Porta diagnostics: versions, group members, health checks.
porta_diag

# Quick environment snapshot: hostname, IPv4, MAC, and /etc/hosts.
~/scripts/vm_info.sh

To copy the resulting bundle to the Windows host, set up the VirtualBox shared folder once — see Porta On Prem VM Windows Shared Folder — then:

~/scripts/export_to_windows.sh ~/logs/collected_data/...

In-VM helpers

Diagnostics

Helper	What it does	Available since
collect_data	Runs various diagnostics to gather system and app data. Results are stored under ~/logs/collected_data/YYYYMMDD/HH-SS/.	0.9.14.2+
porta_diag	Runs the full Porta servers diagnostics.	0.9.14.2+
view_hosts_file	Prints the contents of /etc/hosts.	0.9.14.2+
check_diskspace	Simple disk space check.	0.9.14.2+
check_diskspace_sorted	Disk space check sorted by size.	0.9.14.2+
docker_disk_usage	Docker disk usage by images, containers, and volumes.	0.9.14.2+
docker_volume_size <volume_name>	Inspects the size of a named Docker volume.	0.9.14.2+
~/scripts/vm_info.sh	Prints the VM’s hostname, IPv4 address, MAC address, and /etc/hosts contents.	All
~/scripts/porta-manager/check-conn-cache.sh	Shows the cached connections, the loaded in-memory connections, and the database connection cache for every Porta Manager container.	All

Versioning

Helper	What it does	Available since
porta_check_version	Prints Porta version information, including Laravel, PHP, MySQL, Redis, and OS.	0.9.14.2+
mngr_check_version	Prints Porta Manager version information.	0.9.14.2+
~/scripts/porta-manager/check-manager-version.sh	Underlying script for mngr_check_version.	All

Logs

Each Porta log helper has a paired _follow variant that tails the file (equivalent to tail -f) instead of dumping its current contents.

Helper	What it shows	Available since
porta_laravel_logs / porta_laravel_logs_follow	/var/www/storage/logs/laravel-YYYY-MM-DD.log from the porta container.	0.9.14.2+
porta_php_errors / porta_php_errors_follow	/var/log/php/errors.log from the porta container.	0.9.14.2+
porta_horizon_logs / porta_horizon_logs_follow	/var/www/logs/horizon.log — queue workers and sequence playout.	0.9.14.2+
porta_task_logs / porta_task_logs_follow	/var/www/logs/default_tasks.log — scheduled tasks, database backups, socket checks.	0.9.14.2+
porta_main_db_logs / porta_main_db_logs_follow	MySQL error log on this machine, when it is the main machine.	0.9.14.2+
porta_backup_db_logs / porta_backup_db_logs_follow	MySQL error log on this machine, when it is the backup machine.	0.9.14.2+
porta_arbiter_db_logs / porta_arbiter_db_logs_follow	MySQL error log on this machine, when it is the arbiter machine.	0.9.14.2+
mngr_app_logs	Porta Manager app container logs.	0.9.14.2+
mngr_horizon_logs	Porta Manager installer wizard processing logs.	0.9.14.2+
mngr_task_logs	Porta Manager background task runner logs.	0.9.14.2+
~/scripts/porta-manager/view-logs.sh [container] [lines]	Underlying script for the mngr_*_logs commands. [container] is app, horizon, or task. [lines] is a line count, or f to follow.	All

Note

On older VM images that don’t have the bash shortcuts, use view-logs.sh directly. For example, ~/scripts/porta-manager/view-logs.sh app 300 tails the last 300 lines of the manager app container’s log, and ~/scripts/porta-manager/view-logs.sh horizon f follows the horizon container’s log.

Replication

Helper	What it does	Available since
porta_group_status	Shows the group replication status as reported by this machine.	0.9.14.2+
porta_all_group_status	Runs the same status query against every machine in the group using the entries in /etc/hosts. Each VM’s /etc/hosts must be correct for this to work.	0.9.14.2+
porta_start_repl	Runs START GROUP_REPLICATION on this machine.	0.9.14.2+
porta_stop_repl	Runs STOP GROUP_REPLICATION on this machine.	0.9.14.2+
porta_bootstrap	Bootstraps the replication group from this machine. Check first with porta_all_group_status — only run this if no other member is already primary.	0.9.14.2+
porta_set_bootstrap_ON	Persists the bootstrap flag as ON. This machine will always set itself as primary on startup. Useful only for single-VM setups — never use it on a multi-VM replication group, as it can cause split-brain.	0.9.14.2+
porta_set_bootstrap_OFF	Persists the bootstrap flag as OFF. This is the default state for a Porta VM.	0.9.14.2+
~/scripts/porta/view-ALL-group-repl-status.sh	Underlying script for porta_all_group_status.	All

Database backups

Helper	What it does	Available since
porta_backup_db	Creates a backup of the Porta database. The resulting ZIP archive is saved inside the porta container at /var/www/storage/app/Porta-Backups.	0.9.14.2+
porta_restore_db	Restores the Porta database from a backup. Prompts with a list of locally available dumps.	0.9.14.2+
porta_db_dump [db_container_name] [db_name]	Runs a raw mysqldump. Defaults to porta-db and the porta database.	0.9.14.2+
porta_db_restore [db_container_name] [db_name]	Restores a database from a mysqldump. Defaults to porta-db and the porta database. Prompts with a list of locally available dumps.	0.9.14.2+
porta_reset_db	Destructive — wipes all data on this machine and recreates the database from migrations. Used as the last-resort step in disaster recovery.	0.9.14.2+

Note

Automatic backups run every three hours on a non-primary machine — usually the arbiter — and are saved inside the porta container at /var/www/storage/app/Porta-Backups. Filenames look like arbiter-machine-mysql-3-backup-YYYY-MM-DD-HH-mm-ss.zip.

For full backup and recovery procedures, see Porta VM Disaster Backup and Restore.

Scheduler playout

These helpers query the same Scheduler tables but on different machines in the replication group. Use the variant that matches the machine you are currently on — for example, run porta_playouts from the main machine, porta_backup_playouts from the backup machine.

Helper	What it shows	Available since
porta_playouts	Last 50 Scheduler playouts, including the currently active and next entries. Main machine only.	0.9.14.2+
porta_playout_history	Last 50 Scheduler playout history items. Main machine only.	0.9.14.2+
porta_backup_playouts	Last 50 Scheduler playouts. Backup machine only.	0.9.14.2+
porta_backup_playout_history	Last 50 Scheduler playout history items. Backup machine only.	0.9.14.2+
porta_arbiter_playouts	Last 50 Scheduler playouts. Arbiter machine only.	0.9.14.2+
porta_arbiter_playout_history	Last 50 Scheduler playout history items. Arbiter machine only.	0.9.14.2+

VM lifecycle

Helper	What it does	Available since
~/scripts/reset_identity.sh	Picks a new hostname and unique machine ID, updates /etc/hosts, and reboots. Run this after importing the VM image to a second or third host so the copies don’t share an identity. See Manually Resetting the Identity of a Porta On Prem VM.	All
~/scripts/setup_static_ip.sh	Sets a static IP via netplan. The Porta VM PowerShell setup script does this automatically — only run manually if setup failed mid-flight. See Manually Setting Up a Static IP.	All
~/scripts/disable_static_ip.sh	Disables the static IP configuration by renaming /etc/netplan/99-portacfg.yaml. The VM will fall back to DHCP on next boot.	All
~/scripts/reset_dhcp.sh	Forces a new DHCP lease and clears cached leases. Only meaningful when the VM is not using a static IP.	All
~/scripts/static_ip_info.sh	Prints the current netplan static IP configuration.	All
~/scripts/setup_shared_folders.sh	Prepares the VM side of a VirtualBox shared folder for file export to Windows. See Porta On Prem VM Windows Shared Folder.	All

Warning

~/scripts/setup_static_ip.sh and ~/scripts/disable_static_ip.sh restart networking on the VM. Run them from the VirtualBox console, not over SSH. If executed over SSH, the connection drops when networking restarts and the script fails mid-flight.

Porta Manager lifecycle

Helper	What it does	Available since
update_manager (alias install_manager)	Downloads the latest available Porta Manager build and runs the installer. Automatically runs backup-env.sh first so APP_KEY is preserved across the update.	All
mngr_init_user	Initialises the first Porta Manager admin user. Only needed after a full Porta Manager database wipe.	0.9.14.2+
mngr_backup_env	Copies the .env file from the porta-manager-app container to ${MNGR_CONFIG_DIR}/.env to preserve APP_KEY between updates. Runs automatically when calling update_manager.	0.9.14.2+
mngr_restore_env	Restores the preserved .env file from ${MNGR_CONFIG_DIR}/.env back into the porta-manager-app container.	0.9.14.2+
mngr_recreate	Recreates the Porta Manager containers from their existing images, preserving data volumes. Useful if the VM’s IP changed without running Fix IP Settings in the Porta Manager dashboard.	0.9.14.2+
mngr_wipe_recreate	Destructive — wipes Porta Manager data and storage volumes, then recreates the containers from existing images. Porta application data is not affected.	0.9.14.2+
~/scripts/porta-manager/install-manager.sh	Underlying script for update_manager.	All
~/scripts/porta-manager/init-manager-user.sh	Underlying script for mngr_init_user.	All
~/scripts/porta-manager/backup-env.sh	Underlying script for mngr_backup_env. Runs automatically as part of install-manager.sh.	All

Where files live inside each container

porta container — UI and API

Path	Notes
/var/www	Laravel application root.
/var/www/.env	Application environment file containing host, database credentials, app key, and integrations.
/var/www/bootstrap/cache/config.php	Cached Laravel configuration. Must be regenerated after any .env change with php artisan config:cache.
/var/www/storage/logs/laravel-YYYY-MM-DD.log	Laravel error log.
/var/www/storage/app/Porta-Backups/*.zip	Automatic and manual database backups.
/var/www/logs/horizon.log	Horizon worker log — sequence playout.
/var/www/logs/default_tasks.log	Scheduled task log — database checks, socket checks, backups.
/var/www/logs/default_queue.log	Default queue worker log. Entries should end DONE, not FAIL.
/var/log/php/errors.log	PHP error log inside the container.
/etc/nginx/sites-available/default	Nginx vhost. The default client_max_body_size is 1024M.
/etc/supervisord.conf	Supervisor configuration. Manages nginx, php-fpm, porta-horizon-worker_*, and porta-task-worker_*.
/usr/local/etc/php/conf.d/app.ini	PHP configuration. Default post_max_size is 1024M and default upload_max_filesize is 1000M.

Warning

Do not edit /var/www/.env without guidance from a Disguise engineer. Incorrect values can prevent Porta from starting or leave the database in an inconsistent state.

porta-db* container — MySQL

Path	Notes
/etc/my.cnf	MySQL configuration.
/var/lib/mysql	Data directory. Mounted as a Docker volume; for advanced sysadmin use only.

porta-socket container

Path	Notes
/usr/src/app	Node.js source.
/usr/src/app/.env	Socket server environment — Redis URL and port.

A healthy startup log includes the lines:

info: Starting namespace: /unreal
info: Starting namespace: /disguise
info: Starting namespace: /playout_status

The Socket.IO admin UI is available at http://<VM-IP>:8000/socketio-adminui. Contact support@disguise.one for the credentials.

porta-redis container

To watch messages from the Porta API (including Porta Scheduler) to the socket server, open a Redis CLI session:

docker exec -it porta-redis redis-cli
> MONITOR
# or, only API → socket messages:
> PSUBSCRIBE *-API-msg

Health-check commands

Run these against the porta container:

docker exec -it porta bash -c "php artisan check:version"

For database replication health

docker exec -it porta bash -c "php artisan health:single-check 'PrimaryDatabaseConnectionCheck' --do-not-store-results --no-notification --fail-command-on-failing-check"

docker exec -it porta bash -c "php artisan health:single-check 'MysqlClusterCheck' --do-not-store-results --no-notification --fail-command-on-failing-check"

docker exec -it porta bash -c "php artisan health:single-check 'MysqlNodeStatusCheck' --do-not-store-results --no-notification --fail-command-on-failing-check"

To inspect Porta’s active database connection, run:

docker exec -it porta bash -c "cat .env | grep DB_HOST"
docker exec -it porta bash -c "cat bootstrap/cache/config.php | grep -B 2 \"'default' => 'mysq\""

DB_HOST should reference the same DB_HOST_# slot as the current primary’s IP. If they differ, the Porta backend is talking to a read-only replica — re-running the primary connection health check will trigger a reconnect.

Browser-side monitoring URLs

URL	Purpose
http://<VM-IP>:8000/health	Database group, replication, and primary connection health. Green is healthy.
http://<VM-IP>:8000/horizon	Queue worker dashboard. Watch for failed jobs piling up.
http://<VM-IP>:8000/socketio-adminui	Socket.IO admin UI. Requires credentials from Disguise support.

The Porta UI browser console (F12 → Console) is the only place UI-side errors land. There is no front-end log file.

Configuration cache invalidation

To refresh the configuration cache in the porta container, run:

docker exec -it porta bash -c "php artisan config:cache"

Then docker restart porta if anything that PHP-FPM reads at boot has changed.

For Porta Manager, the equivalent action is mngr_recreate, which drops and recreates the Manager containers from existing images and preserves data volumes.