Porta On Prem README

Architecture

Porta On Prem requires the following minimum system configuration:

• minimum of 3 machines if running database replication

Component	Specification
Operating System	Windows 10 or 11, 64-bit, Win10 must have minimum update 21H2
Virtualized Operating System	WSL 2 with Ubuntu 22.04 as default distro
CPU	Intel i7 4th Generation (required: CPU with AVX2 support)
Memory	8GB RAM
Storage	30+GB

Docker

porta Container

• Role: Porta UI & API
• Published Ports:
  • 8080 for UI
  • 8000 for API

Note

Also communicates on Porta Bridge’s port 1500

porta-db Container

• Role: Porta MySQL Database
• Published Ports:
  • MySQL Client Ports:
    • 3306 for porta-db
    • 3307 for porta-db-2
    • 3308 for porta-db-3
  • MySQL Replication Ports:
    • 33061 for porta-db
    • 33062 for porta-db-2
    • 33063 for porta-db-3

porta-socket Container

• Role: Porta WebSocket Relay Server
• Published Ports: 6001

porta-redis Container

• Role: Porta Redis Server
• Published Ports: 6379

Database

Porta On Prem runs three MySQL databases utilizing the MySQL standard Group Replication features.

Database Replication

MySQL Group Replication provides distributed replication with automated coordination between servers in the group. Group replication ensures that the database service is continuously available.

The replication group operates in single-primary mode with automatic primary election, in which only one server accepts writes at a time. In the case of primary failure, the Porta backend will automatically attempt to reconnect to the newly elected primary.

Replication States

Possible values of member_state from performance_schema.replication_group_members

Member State	Description
ONLINE	The server is an active member of a group and in a fully functioning state
RECOVERING	The server has joined a group and is in the process of becoming an active member
OFFLINE	The Group Replication plugin is loaded but the member does not belong to any group. This status may briefly occur while a member is joining or rejoining a group
UNREACHABLE	The local failure detector suspects that the member cannot be contacted, because the group’s messages are timing out. This can happen if a member is disconnected involuntarily.
ERROR	The member is in an error state and is not functioning correctly as a group member. While a member is joining or rejoining a replication group, its status can be displayed as ERROR before the group completes the compatibility checks and accepts it as a member.

Note

The following documentation provides further details about Porta On Prem database replication:

• Replication Group Member Recovery
• Replication Group Troubleshooting

Helpers

Many recovery or monitoring tasks have user-friendly shortcut scripts available, and they will be referenced throughout these documents.

Tip

Helper scripts are contained within helper folders located in porta-onprem-bundle/porta-helpers

Database Helpers

Checks

Location: porta-database

Script Name	Description
view-group-repl-status.bat	View the database replication group’s member statuses (as reported by this machine)
view-ALL-group-repl-status.bat	View the database replication group’s member statuses (as reported by EACH machine)
view-database-log.bat	View this machine’s database logs
follow-database-log.bat	View this machine’s database logs in real time
view-repl-vars.bat	View this machine’s database replication variables’ values
view-binlog-events.bat	View this machine’s database binary log events
view-transactions.bat	View this machine’s database transactions
view-database-users.bat	View the registered Porta users in the database

Replication Actions

Location: porta-database/actions

Script Name	Description
bootstrap.bat	Bootstrap this database’s replication
restart-repl.bat	Restart this database’s replication
START-repl.bat	Start this database’s replication
STOP-repl.bat	Stop this database’s replication

Backup & Recovery Actions

Location: porta-database/actions

Script Name	Description
create-backup.bat	Create a backup of the database
restore-from-backup.bat	Restore a database from a backup
caution/copy-DB-backup-from-container-to-host.ps1	Copy a database backup from the database container to the host machine
caution/copy-DB-backup-into-container-and-restore.ps1	Copy a database backup from the host machine into a database container and optionally use it to restore the database

Other Database Actions

Location: porta-database/actions/caution

Caution

These scripts will perform destructive actions on the database. Use with caution only as directed.

Script Name	Description
reset.bat ⚠️	Reset this database ⚠️ THIS WILL WIPE DATA ON THE MACHINE
migrate-or-seed.bat	Migrate and/or seed the database
set-bootstrap-OFF.bat	Disable bootstrapping when the database is started (this is the default setting)

Destructive Database Actions

Location: porta-database/actions/caution

Warning

These scripts will lead to irreparable data loss if misused. Do not use unless directly instructed by a Disguise engineer.

Script Name	Description
⛔ set-bootstrap-ON.bat ⛔	Enable bootstrapping when the database is started THIS WILL LEAD TO DATA LOSS if used in a 3 machine setup
⛔ transfer/MAIN-TO-BACKUP-transfer-database.bat ⛔	Transfer the database from the main machine to the backup machine. This will overwrite ALL data in the backup machine’s database. Intended only for use with a 2 machine setup.
⛔ transfer/BACKUP-TO-MAIN-transfer-database.bat ⛔	Transfer the database from the backup machine to the main machine. This will overwrite ALL data in the main machine’s database. Intended only for use with a 2 machine setup.

General Check Helpers

Location: porta-checks

Script Name	Description
view-workers.bat	View Porta’s server workers
view-failed-jobs.bat	View Porta’s failed jobs
check-default-connection.bat	Check the default database connection cached by Porta
check-env-connections.bat	Check the database connections configured in Porta’s environment configuration
check-primary-connection.bat	Check the primary database connection being used by Porta
check-version.bat	Check the Porta version

Log Viewer Helpers

Location: porta-log-viewers

Script Name	Description
view-laravel-log.bat	View Porta API’s logs
view-horizon-log.bat	View Porta’s queue logs
view-tasks-log.bat	View Porta’s background tasks logs
view-php-errors-log.bat	View Porta API’s low level error logs
view-server-log.bat	View Porta’s general server logs
view-socket-log.bat	View Porta’s socket server logs
view-redis-log.bat	View Porta’s Redis server logs

Config Viewer Helpers

Location: porta-config-viewers

Script Name	Description
view-api-env.bat	View the Porta’s API environment configuration file contents
view-app-env.bat	View the Porta’s UI environment configuration file contents
view-cached-connection.bat	View the cached default database connection being used by Porta
view-cache-config.bat	View all cached configurations being used by Porta
view-supervisor-conf.bat	View the Porta’s supervisord configuration
view-php-conf.bat	View the Porta’s PHP configuration
view-nginx-conf.bat	View the Porta’s nginx configuration

System Helpers

Location: porta-run

Script Name	Description
cache-api-config.bat	Cache Porta API’s configuration files
clear-api-cache.bat	Clear Porta API’s cache
rotate-porta-logs.bat	Manually rotate Porta’s system logs
copy-file-from-container.bat	Copy a file from a running container to the host machine
copy-file-from-stopped container.bat	Copy a file from a stopped container to the host machine

System Administration Helpers

Location: porta-run/sysadmin

Caution

These scripts will perform disruptive actions in Porta. Use with caution only as directed.

Script Name	Description
fix-crlf.bat	Convert Windows line endings (CRLF) to Linux line endings (LF) in the given directory
generate-secret.bat	Generate a new secret key for Porta’s environment configuration file. This will also cache the API configuration.
❌ migrate-volumes.bat	Obsolete — Migrate the mounted drives to docker volumes in an old version of Porta On Prem
restart-workers.bat	Restart Porta server workers
restart-container.bat	Restart a Docker container
stop-container.bat	Stop a Docker container
stop-porta-socket-server.bat	Stop the porta-socket container

Installing Porta On Prem

• Initial Machine Setup
• New Installation or Existing Update
• Installation/Update Troubleshooting

Logs

Installer Logs

Porta installer logs are located in the WSL directory: /home/$USER/porta/logs/installer

Note

$USER within WSL will be interpreted to the current WSL user’s username. For example, from the WSL CLI, you can navigate to the logs directory by running the command cd /home/$USER/porta/logs/installer or cd ~/porta/logs/installer

You can access these logs in Windows explorer by navigating to one of the following paths (depending on your installation):

• \\wsl$\Ubuntu\home\<USERNAME>\porta\logs\installer
• \\wsl$\Ubuntu-22.04\home\<USERNAME>\porta\logs\installer
• \\wsl$\Ubuntu-20.04\home\<USERNAME>\porta\logs\installer

Note

<USERNAME> should be replaced with your WSL username

Porta UI Logs

The front-end logs can be viewed in the Web Browser console. To access the logs, open the browser’s developer tools (F12) and select the Console tab.

Porta Server and Service Logs

Porta related logs are located within their respective containers. You can view some of these logs by running one of the helpers within the porta-onprem-bundle\porta-helpers\porta-log-viewers folder.

Porta API log

Application Logs

These logs will be the most useful for general debugging and troubleshooting of the Porta API.

• Helper: view-laravel-log.bat

  • Note: The log filenames will begin with laravel- and be scoped by date, i.e. laravel-YYYY-MM-DD.log

Scheduled/Background Tasks Logs

These consist of scheduled or long-running background tasks like socket server checks, database backups & checks, etc.

• Helper: view-tasks-log.bat

Queued Tasks Log

These logs are for queued background tasks such as media ingestion and conversion.

• Helper: view-horizon-log.bat

PHP Error Logs

These logs are for lower level PHP errors and exceptions. These will occur if something goes wrong on the server level, such as a memory error.

• Helper: view-php-errors-log.bat

General API Server Logs

Logs regarding server processes and services.

• Helper: view-server-log.bat

Porta Database logs

These logs are for the Porta database server. They will contain information about replication, and other MySQL logs.

• Helper: porta-onprem-bundle\porta-helpers\porta-database\view-database-log.bat

Porta Socket Server Logs

These logs will contain lots of information about websocket connections and requests passing through the server. Nearly all events and status changes are logged here.

• Helper: view-socket-log.bat

Redis Server Logs

These logs will almost never be needed unless there is a redis error seen in the socket server or API logs.

• Helper: view-redis-log.bat

Diagnostics and Monitoring

Full Diagnostic

Run a Porta diagnostic to compile various logs and configuration information into a single archive.

1. In porta-onprem-bundle’s porta-helpers folder, run the full diagnostic helper by double-clicking on porta-full-diag.bat
2. The diagnostic will run and create a directory and .tar.gz file in the same folder as the helper script.

Viewing Database Health

A database health dashboard is available at http://<MACHINE-IP>:8000/health. This dashboard displays the results of ongoing database replication health checks.

Viewing Server Workers

Such as those that process the play group sequence (porta-horizon-worker) or run database checks in the background (porta-task-worker)

• Helper: porta-onprem-bundle\porta-helpers\porta-checks\view-workers.bat
• Example result:

  nginx                                    RUNNING   pid 7, uptime 0:16:57
  php-fpm                                  RUNNING   pid 8, uptime 0:16:57
  porta-task-worker:porta-task-worker_00   RUNNING   pid 746, uptime 0:02:57
  porta-task-worker:porta-task-worker_01   RUNNING   pid 747, uptime 0:02:57
  porta-horizon-worker:porta-horizon-worker_00             RUNNING   pid 732, uptime 0:02:59
  porta-horizon-worker:porta-horizon-worker_01             RUNNING   pid 733, uptime 0:02:59

Viewing Queued Tasks

Some heavy-duty tasks, such as media conversion, are queued and run in the background. A minimal UI is available at http://<MACHINE-IP>:8000/horizon to monitor these tasks.

View failed tasks

Viewed failed tasks directly with the helper porta-onprem-bundle\porta-helpers\porta-checks\view-failed-jobs.bat

Socket.IO Admin UI

View the Socket.IO Admin UI at http://<PORTA-MACHINE-IP>:8000/socketio-adminui to monitor the status of the Porta Socket Server. Please contact support@disguise.one for the login credentials.

Backups and Restorations

Please refer to the Porta On Prem Backup and Restore Guide for details on how to backup and restore your Porta OnPrem databases.