We've identified an issue that may affect the installation process for some users, specifically related to the PM2 package used by MultiPortal.
We've added a new section below titled “Installation Issues with PM2” that explains the issue and how to resolve it manually if needed.
If you run into any other problems, feel free to reach out on our MultiPortal Discord Server.
This comprehensive guide walks you through the complete installation process for setting up MultiPortal on a newly deployed operating system, ensuring you have everything needed for a smooth and successful setup
| Operating System | Supported |
|---|---|
| Debian 12 (Bookworm) | √ |
| Ubuntu 24.04 (Noble Numbat) | √ |
At the end of the guide, you'll have a fully working MultiPortal instance with the following components:
We have provided a script that will configure and install MultiPortal for you. To get started, simply copy the following command and run it on your server.
STEP1: Download the Script and set it as executable
sudo curl -o ./mpsetup.sh https://downloads.multiportal.io/mpsetup.sh
sudo chmod +x ./mpsetup.sh
STEP2: Depending on the installation you need, follow the instructions below
Choose this step if you want to use CaddyServer's built in SSL generation feature
sudo ./mpsetup.sh --fqdn "myfqdn.domain.local"
Choose this step if you want to use your own SSL certificate and SSL key
sudo ./mpsetup.sh --fqdn "myfqdn.domain.local" --sslcert "./fullchain.cer" --sslkey "./domain.local.key"
During the installation of MultiPortal, a package called PM2 (Process Manager 2) is installed. PM2 is responsible for managing the Node.js application that powers the Console Server.
As of March 31st, 2025, we’ve seen an increase in failures when installing this package via the automated installer script.
We've updated the installer to better handle this issue, but if the installation still fails, you'll see the following error and the Console Server will be unable to start:
⚠️ Warning:
If you see the following message during installation:
[Error] PM2 was not installed.
After MultiPortal completes the installation, please run the following command manually:
npm install pm2 -g
This will install the required PM2 process manager used by MultiPortal to run its Console Server.
This guide assumes you are logged in as the root or user with administrative privileges.
First, let's make sure the machine is up to date.
## Fetch latest updates
apt update
## Install all updates automatically
apt upgrade -y
Install essential tools and packages:
apt install -y \
debian-keyring \
debian-archive-keyring \
apt-transport-https \
curl \
software-properties-common \
git \
unzip \
libicu-dev \
cron
Disable Apache2 if it is running
systemctl stop apache2
systemctl disable apache2
Setup MariaDB Repository
sudo curl -LsSO https://r.mariadb.com/downloads/mariadb_repo_setup
sudo chmod +x ./mariadb_repo_setup
sudo ./mariadb_repo_setup --mariadb-server-version="mariadb-11.6.2" --skip-maxscale
Install MariaDB:
sudo apt install -y mariadb-server mariadb-client mariadb-backup galera-4
Start and enable MariaDB:
sudo systemctl start mariadb && sudo systemctl enable mariadb
To install PHP 8.2 on Debian, we'll use the Sury repository, which provides updated PHP packages for Debian.
## Add Sury repository for PHP 8.2
sudo apt install -y apt-transport-https lsb-release ca-certificates wget
wget -O /etc/apt/trusted.gpg.d/php.gpg https://packages.sury.org/php/apt.gpg
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list
apt update
To install PHP 8.2 on Ubuntu, we'll add the ppa:ondrej/php repository for Ubuntu.
sudo add-apt-repository ppa:ondrej/php -y
Once the repository has been added, install PHP 8.2 and required extensions:
apt install -y \
php8.2 \
php8.2-fpm \
php8.2-common \
php8.2-curl \
php8.2-gd \
php8.2-mbstring \
php8.2-mysql \
php8.2-opcache \
php8.2-xml \
php8.2-zip
Modify the PHP configuration file running commands below. This will update the upload settings
sudo sed -i 's/^upload_max_filesize = .*/upload_max_filesize = 10G/' /etc/php/8.2/fpm/php.ini
sudo sed -i 's/^post_max_size = .*/post_max_size = 10G/' /etc/php/8.2/fpm/php.ini
sudo sed -i 's/^max_execution_time = .*/max_execution_time = 360/' /etc/php/8.2/fpm/php.ini
Run the command below to verify applied configuration settings
grep -E 'upload_max_filesize|post_max_size|max_execution_time' /etc/php/8.2/fpm/php.ini
Output of the command should be:
upload_max_filesize = 10G
post_max_size = 10G
max_execution_time = 360
Restart PHP-FPM:
systemctl restart php8.2-fpm
cd /tmp
wget https://downloads.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz
tar -zxvf ioncube_loaders_lin_x86-64.tar.gz
Copy IonCube loader to PHP extension directory:
cp /tmp/ioncube/ioncube_loader_lin_8.2.so $(php -r "echo ini_get('extension_dir').PHP_EOL;")
Update PHP configuration files (/etc/php/8.2/fpm/php.ini and /etc/php/8.2/cli/php.ini) by running commands below:
echo "zend_extension=$(php -r "echo ini_get('extension_dir').PHP_EOL;")/ioncube_loader_lin_8.2.so" | sudo tee -a /etc/php/8.2/fpm/php.ini
echo "zend_extension=$(php -r "echo ini_get('extension_dir').PHP_EOL;")/ioncube_loader_lin_8.2.so" | sudo tee -a /etc/php/8.2/cli/php.ini
Verify applied configuration settings
grep -E 'zend_extension' /etc/php/8.2/fpm/php.ini
grep -E 'zend_extension' /etc/php/8.2/cli/php.ini
Expected Output:
zend_extension = /path/to/php/extension_dir/ioncube_loader_lin_8.2.so
Restart PHP-FPM:
systemctl restart php8.2-fpm
systemctl enable php8.2-fpm
Confirm the extension is installed:
php -v
If installed correctly, you should see output similar to:
PHP 8.2.25 (cli) (built: Oct 30 2024 11:26:32) (NTS)
Zend Engine v4.2.25, Copyright (c) Zend Technologies
with the ionCube PHP Loader v14.0.0, Copyright (c) 2002-2024, by ionCube Ltd.
with Zend OPcache v8.2.25, Copyright (c), by Zend Technologies
Remove ioncube from the tmp directory
rm -r ioncube
rm ioncube_loaders_lin_x86-64.tar.gz
Download and install CaddyServer:
wget -q "https://github.com/caddyserver/caddy/releases/download/v2.7.6/caddy_2.7.6_linux_amd64.deb"
apt install ./caddy_2.7.6_linux_amd64.deb
rm caddy_2.7.6_linux_amd64.deb
Add the Node.js repository and install Node.js:
curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
apt install -y nodejs npm
Download and install Composer:
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --quiet
mv composer.phar /usr/local/bin/composer
curl -o ./installMultiportal https://downloads.multiportal.io/installer/ManualInstallation
chmod +x ./installMultiportal
Set your multiportal FQDN
MYFQDN=mymultiportal.domain.local
Run the installer:
php ./installMultiportal $MYFQDN
Navigate to the websocket directory and install dependencies:
cd /var/www/$MYFQDN/websockets
npm install
npm install pm2 -g
Create a configuration file for your application, copy-paste the code below:
sudo cat > /etc/caddy/Caddyfile << EOF
$MYFQDN {
@css path *.css
header @css Content-Type text/css
root * /var/www/$MYFQDN/backend/web
encode gzip
file_server
php_fastcgi unix//var/run/php/php8.2-fpm.sock {
index index.php
}
## Add headers
header {
Access-Control-Allow-Origin *
Access-Control-Allow-Methods "GET, POST, OPTIONS"
x-frame-options SAMEORIGIN
Access-Control-Allow-Headers "Content-Type, Authorization"
}
## Error and access logs
log {
output file /var/log/caddy/$MYFQDN.log
level error
}
## PHP handling
route / {
try_files {path} {path}/ /index.php?{query}
php_fastcgi unix//var/run/php/php8.2-fpm.sock {
env PHP_FCGI_MAX_REQUESTS 1000
}
}
## Static files
route / {
file_server
}
## Reverse proxy to Node.js server
reverse_proxy /wss* localhost:8081 {
header_up Host {host}
header_up X-Real-IP {remote}
}
}
EOF
If you wish to add your own TLS certificate instead of using the CaddyServer default LetsEncrypt process.
Upload your certificate and private key to folder below
cd /var/lib/caddy
then run the command below to set the ownership of the file
chown caddy:caddy /var/lib/caddy/*your certificate*
chown caddy:caddy /var/lib/caddy/*your key*
modify the configuration file with your preferred editor.
nano /etc/caddy/Caddyfile
then add the following after $MYFQDN {
tls /var/lib/caddy/*your certificate* /var/lib/caddy/*your key*
Example:
YOUR_HOSTNAME {
tls /var/lib/caddy/certificate /var/lib/caddy/privatekey
...
Start and enable Caddy:
systemctl start caddy
systemctl enable caddy
Create a service file:
sudo cat > /etc/systemd/system/multiportal.service << EOF
[Unit]
Description=MultiPortal Service
After=network.target
[Service]
User=root
Group=root
WorkingDirectory=/var/www/$MYFQDN
ExecStart=/usr/bin/php /var/www/$MYFQDN/yii queue/listen --verbose
Restart=on-failure
[Install]
WantedBy=multi-user.target
EOF
Reload systemd and start the service:
systemctl daemon-reload
systemctl enable multiportal.service
systemctl start multiportal.service
Restart Caddy Service
systemctl restart caddy
Visit your instance at:
https://YOUR_MULTIPORTAL_FQDN