Documentation - SilkPanel

Appearance

Ubuntu ​

This guide will walk you through the process of setting up the SilkPanel SaaS application on Ubuntu Server.

Prerequisites ​

Before you begin, make sure you have:

  • Ubuntu 24.04 LTS or higher
  • Root or sudo access
  • A domain name pointed to your server (optional for local development)

Step 1: Update System ​

First, update your system packages:

bash
sudo apt update
sudo apt upgrade -y

Step 2: Install PHP 8.4 ​

Add the PHP repository and install PHP with required extensions:

bash
sudo apt install software-properties-common -y
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update

Install PHP 8.4 and necessary extensions:

bash
sudo apt install php8.4 php8.4-fpm php8.4-cli php8.4-common php8.4-mysql \
php8.4-zip php8.4-gd php8.4-mbstring php8.4-curl php8.4-xml \
php8.4-bcmath php8.4-intl php8.4-readline -y

Verify PHP installation:

bash
php -v

Step 3: Install Microsoft ODBC Driver 18 and PHP SQL Server Extensions ​

SilkPanel requires SQL Server connectivity for the Silkroad MSSQL databases. On Ubuntu 24.04 with PHP 8.4, install the Microsoft ODBC Driver 18 together with the sqlsrv and pdo_sqlsrv PHP extensions.

3.1 Check for conflicting Microsoft APT repository entries ​

If the Microsoft repository was added before, make sure there is no duplicate entry using a different keyring:

bash
sudo -i
grep -R -n "packages.microsoft.com\|microsoft.gpg\|microsoft-prod.gpg" /etc/apt/sources.list /etc/apt/sources.list.d /etc/apt/keyrings 2>/dev/null

A common conflict looks like this:

  • /etc/apt/sources.list.d/microsoft-prod.list
  • /etc/apt/sources.list.d/mssql-release.list

If both files exist and point to the same Ubuntu 24.04 repository, remove the duplicate file:

bash
rm -f /etc/apt/sources.list.d/mssql-release.list

Verify that only the correct Microsoft repository entry remains:

bash
grep -R -n "packages.microsoft.com\|microsoft.gpg\|microsoft-prod.gpg" /etc/apt/sources.list /etc/apt/sources.list.d /etc/apt/keyrings 2>/dev/null

The valid remaining entry should look like this:

text
/etc/apt/sources.list.d/microsoft-prod.list:1:deb [arch=amd64,arm64,armhf signed-by=/usr/share/keyrings/microsoft-prod.gpg] https://packages.microsoft.com/ubuntu/24.04/prod noble main

3.2 Install or reinstall the official Microsoft repository package ​

bash
curl -sSL -O https://packages.microsoft.com/config/ubuntu/24.04/packages-microsoft-prod.deb
dpkg -i packages-microsoft-prod.deb
rm -f packages-microsoft-prod.deb
apt-get update

3.3 Install ODBC Driver 18 and PHP 8.4 build dependencies ​

bash
ACCEPT_EULA=Y apt-get install -y msodbcsql18 unixodbc-dev php-pear php8.4-dev

Verify that the ODBC driver is installed:

bash
odbcinst -q -d

Expected relevant output:

text
ODBC Driver 18 for SQL Server

3.4 Install sqlsrv and pdo_sqlsrv via PECL ​

Configure PECL to use the PHP 8.4 FPM configuration:

bash
pecl config-set php_ini /etc/php/8.4/fpm/php.ini

Install the PHP SQL Server extensions:

bash
pecl install sqlsrv
pecl install pdo_sqlsrv

3.5 Enable the extensions for PHP 8.4 FPM ​

Create the module ini files:

bash
printf "; priority=20\nextension=sqlsrv.so\n" > /etc/php/8.4/mods-available/sqlsrv.ini
printf "; priority=30\nextension=pdo_sqlsrv.so\n" > /etc/php/8.4/mods-available/pdo_sqlsrv.ini

Enable the modules:

bash
phpenmod -v 8.4 sqlsrv pdo_sqlsrv

3.6 Restart PHP-FPM ​

bash
systemctl restart php8.4-fpm

3.7 Verify the PHP SQL Server extensions ​

bash
php -m | grep -E 'sqlsrv|pdo_sqlsrv'

Also verify the FPM module links:

bash
ls /etc/php/8.4/fpm/conf.d/*sqlsrv.ini

INFO

SilkPanel uses Microsoft SQL Server connectivity for the Silkroad databases. On Ubuntu 24.04 with PHP 8.4, the recommended setup is msodbcsql18 together with the PHP extensions sqlsrv and pdo_sqlsrv.

WARNING

If apt-get update fails with a Signed-By conflict, you most likely have duplicate Microsoft repository definitions pointing to the same URL with different keyrings. Remove the duplicate entry before continuing.

Step 4: Install Composer ​

Download and install Composer globally:

bash
cd ~
curl -sS https://getcomposer.org/installer -o /tmp/composer-setup.php
sudo php /tmp/composer-setup.php --install-dir=/usr/local/bin --filename=composer

Verify Composer installation:

bash
composer --version

Step 5: Install Node.js ​

Install Node.js (v18 or higher) using NodeSource repository:

bash
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs -y

Verify Node.js and npm installation:

bash
node -v
npm -v

Step 6: Install and Configure Nginx ​

Install Nginx web server:

bash
sudo apt install nginx -y

Start and enable Nginx:

bash
sudo systemctl start nginx
sudo systemctl enable nginx

Step 7: Install MySQL ​

Install MySQL server:

bash
sudo apt install mysql-server -y

Secure MySQL installation:

bash
sudo mysql_secure_installation

Create a database and user for SilkPanel:

bash
sudo mysql -u root -p

Then run the following SQL commands:

sql
CREATE DATABASE silkpanel;
CREATE USER 'silkpanel'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON silkpanel.* TO 'silkpanel'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 8: Install Git ​

Install Git if not already installed:

bash
sudo apt install git -y

Step 9: Download the Project ​

Navigate to the web root directory and clone the repository:

bash
cd /var/www
sudo git clone https://github.com/Devsome/silkpanel-cms silkpanel-saas
cd silkpanel-saas

Set proper ownership:

bash
sudo chown -R www-data:www-data /var/www/silkpanel-saas
sudo chmod -R 755 /var/www/silkpanel-saas

Step 10: Install Dependencies ​

Install PHP Dependencies ​

bash
sudo -u www-data composer install --no-dev --optimize-autoloader

Install Node.js Dependencies ​

bash
npm install

Build Frontend Assets ​

bash
npm run build

Step 11: Configure Environment ​

Copy the example environment file:

bash
sudo cp .env.example .env

Set proper permissions:

bash
sudo chown www-data:www-data /var/www/silkpanel-saas/.env
sudo chmod 600 /var/www/silkpanel-saas/.env

TIP

You do not need to manually edit the .env file. The Installation Wizard in Step 15 will guide you through all configuration settings including database credentials, application URL, and mail settings.

Step 12: Configure Nginx ​

Create an Nginx configuration file for SilkPanel:

bash
sudo nano /etc/nginx/sites-available/silkpanel

Add the following configuration:

nginx
server {
    listen 80;
    listen [::]:80;
    server_name yourdomain.com www.yourdomain.com;
    root /var/www/silkpanel-saas/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Enable the site and remove the default configuration:

bash
sudo ln -s /etc/nginx/sites-available/silkpanel /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default

Test Nginx configuration:

bash
sudo nginx -t

Reload Nginx:

bash
sudo systemctl reload nginx

Step 13: Set Proper Permissions ​

Set the correct permissions for Laravel:

bash
sudo chown -R www-data:www-data /var/www/silkpanel-saas
sudo chmod -R 755 /var/www/silkpanel-saas
sudo chmod -R 775 /var/www/silkpanel-saas/storage
sudo chmod -R 775 /var/www/silkpanel-saas/bootstrap/cache

Install Certbot:

bash
sudo apt install certbot python3-certbot-nginx -y

Obtain and install SSL certificate:

bash
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

Follow the prompts. Certbot will automatically configure Nginx for HTTPS.

Test automatic renewal:

bash
sudo certbot renew --dry-run

Step 15: Run the Installation Wizard ​

Open your browser and navigate to:

text
https://yourdomain.com/install

The installation wizard will:

  1. Check system requirements — verifies PHP version, required extensions (including the SQL Server driver), and directory permissions
  2. Validate your SilkPanel API license key
  3. Configure the MySQL database — tests the connection and runs migrations automatically
  4. Configure the MSSQL database — tests the connection to your Silkroad Online databases (Account, Shard, Log, Custom, and optionally Portal)
  5. Set up application settings — app name, URL, environment, and optional mail configuration
  6. Generate the application key and seed initial data

WARNING

Make sure all PHP extensions from Step 2 and Step 3 are installed before starting the wizard. The wizard will block you if required SQL Server extensions are missing.

Step 16: Configure Queue Worker (Optional) ​

If your application uses queues, set up a queue worker with Supervisor:

Install Supervisor:

bash
sudo apt install supervisor -y

Create a Supervisor configuration:

bash
sudo nano /etc/supervisor/conf.d/silkpanel-worker.conf

Add the following configuration:

ini
[program:silkpanel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/silkpanel-saas/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/silkpanel-saas/storage/logs/worker.log
stopwaitsecs=3600

Update Supervisor:

bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start silkpanel-worker:*

Step 17: Configure Cron for Scheduled Tasks ​

Laravel requires a cron entry for scheduled tasks:

bash
sudo crontab -e -u www-data

Add the following line:

bash
* * * * * cd /var/www/silkpanel-saas && php artisan schedule:run >> /dev/null 2>&1

Optimization for Production ​

Run these commands to optimize your application:

bash
cd /var/www/silkpanel-saas
sudo php artisan optimize

Security Hardening ​

Configure Firewall ​

bash
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

Disable Directory Listing ​

This is already handled by the Nginx configuration above.

Keep System Updated ​

Regularly update your system:

bash
sudo apt update && sudo apt upgrade -y

Troubleshooting ​

Microsoft APT repository Signed-By conflict ​

If apt-get update fails with a message similar to this:

text
E: Conflicting values set for option Signed-By regarding source https://packages.microsoft.com/ubuntu/24.04/prod/ noble: /usr/share/keyrings/microsoft-prod.gpg != /usr/share/keyrings/microsoft.gpg

check for duplicate Microsoft repository definitions:

bash
sudo -i
grep -R -n "packages.microsoft.com\|microsoft.gpg\|microsoft-prod.gpg" /etc/apt/sources.list /etc/apt/sources.list.d /etc/apt/keyrings 2>/dev/null

If both of these files are present and point to the same repository, remove the duplicate file:

  • /etc/apt/sources.list.d/microsoft-prod.list
  • /etc/apt/sources.list.d/mssql-release.list
bash
rm -f /etc/apt/sources.list.d/mssql-release.list
apt-get update

Permission Issues ​

If you encounter permission issues:

bash
sudo chown -R www-data:www-data /var/www/silkpanel-saas
sudo chmod -R 755 /var/www/silkpanel-saas
sudo chmod -R 775 /var/www/silkpanel-saas/storage
sudo chmod -R 775 /var/www/silkpanel-saas/bootstrap/cache

Clear Application Cache ​

bash
cd /var/www/silkpanel-saas
sudo php artisan optimize:clear
php artisan config:clear
php artisan cache:clear

Check Logs ​

Application logs:

bash
sudo tail -f /var/www/silkpanel-saas/storage/logs/laravel.log

Nginx error logs:

bash
sudo tail -f /var/nginx/error.log

PHP-FPM logs:

bash
sudo tail -f /var/log/php8.4-fpm.log

Verify SQL Server connectivity in Laravel ​

If the SQL Server connection does not work, verify that the driver is loaded:

bash
php -m | grep -E 'sqlsrv|pdo_sqlsrv'
php --ri sqlsrv
php --ri pdo_sqlsrv

You can also test the Laravel connection:

bash
php artisan tinker

Then run:

php
DB::connection()->getPdo();
DB::select('SELECT 1 as test');

Next Steps ​

Once installation is complete, you can:

  • Access the admin panel at https://yourdomain.com/admin
  • Configure your application settings
  • Set up your first server
  • Explore the configuration guide

TIP

For production environments, always use HTTPS and keep your system and dependencies up to date.

WARNING

Never expose your .env file publicly. It contains sensitive credentials and configuration.

Released under the PolyForm Shield License 1.0.0.

Copyright © 2026 - Alexander Frank