Installation on Nginx

This guide will walk you through installing OmniSuite CMS on a server running Nginx web server.

Prerequisites
Step 1: Server Preparation
Step 2: Install PHP and Extensions
Step 3: Install Composer and Node.js
Step 4: Create Database
Step 5: Upload Files
Step 6: Configure Nginx
Step 7: Set Permissions
Step 8: Run the Installer
Step 9: Post-Installation
Troubleshooting

Prerequisites

Before starting, ensure you have:

✅ Root or sudo access to server
✅ Nginx installed and running
✅ PHP 8.2+ installed
✅ MySQL/PostgreSQL database server
✅ Domain or IP address configured
✅ Reviewed System Requirements

Step 1: Server Preparation

Update System Packages

Ubuntu/Debian:

bash

sudo apt update
sudo apt upgrade -y

CentOS/RHEL:

bash

sudo yum update -y

Install Required Tools

Ubuntu/Debian:

bash

sudo apt install -y curl wget git unzip

CentOS/RHEL:

bash

sudo yum install -y curl wget git unzip

Step 2: Install PHP and Extensions

Install PHP 8.2+

Ubuntu 22.04+:

bash

sudo apt install -y php8.2 php8.2-fpm php8.2-cli

Ubuntu 20.04:

bash

sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install -y php8.2 php8.2-fpm php8.2-cli

CentOS/RHEL:

bash

sudo yum install -y epel-release
sudo yum install -y https://rpms.remirepo.net/enterprise/remi-release-8.rpm
sudo yum module reset php
sudo yum module enable php:remi-8.2
sudo yum install -y php php-fpm php-cli

Install Required PHP Extensions

Ubuntu/Debian:

bash

sudo apt install -y \
    php8.2-mysql \
    php8.2-pgsql \
    php8.2-sqlite3 \
    php8.2-mbstring \
    php8.2-xml \
    php8.2-curl \
    php8.2-intl \
    php8.2-zip \
    php8.2-gd \
    php8.2-bcmath

CentOS/RHEL:

bash

sudo yum install -y \
    php-mysqlnd \
    php-pgsql \
    php-sqlite3 \
    php-mbstring \
    php-xml \
    php-curl \
    php-intl \
    php-zip \
    php-gd \
    php-bcmath

Verify PHP Installation

bash

php -v
# Should show PHP 8.2.0 or higher

php -m
# Should show all required extensions

Configure PHP-FPM

Edit PHP-FPM configuration:

bash

sudo nano /etc/php/8.2/fpm/php.ini

Update these settings:

ini

memory_limit = 256M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 300
date.timezone = America/New_York  # Set your timezone

Restart PHP-FPM:

bash

sudo systemctl restart php8.2-fpm
sudo systemctl enable php8.2-fpm

Step 3: Install Composer and Node.js

Install Composer

bash

cd /tmp
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
sudo chmod +x /usr/local/bin/composer
composer --version

Install Node.js and NPM

Using NodeSource (Recommended):

bash

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

Or using NVM:

bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18

Verify Installation:

bash

node --version  # Should show v18.x or higher
npm --version

Step 4: Create Database

MySQL/MariaDB

Login to MySQL:

bash

sudo mysql -u root -p

Create Database and User:

sql

CREATE DATABASE omnisuite_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'omnisuite_user'@'localhost' IDENTIFIED BY 'strong_password_here';
GRANT ALL PRIVILEGES ON omnisuite_db.* TO 'omnisuite_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Note: Replace strong_password_here with a secure password.

PostgreSQL

Login to PostgreSQL:

bash

sudo -u postgres psql

Create Database and User:

sql

CREATE DATABASE omnisuite_db;
CREATE USER omnisuite_user WITH PASSWORD 'strong_password_here';
GRANT ALL PRIVILEGES ON DATABASE omnisuite_db TO omnisuite_user;
\q

Step 5: Upload Files

Option A: Using Git (Recommended)

bash

cd /var/www
sudo git clone [your-repository-url] omnisuite
cd omnisuite

Option B: Using SCP/SFTP

Upload files via SCP/SFTP to /var/www/omnisuite
Or use wget to download ZIP and extract

Option C: Manual Upload

Download application package
Extract to /var/www/omnisuite
Ensure all files uploaded

Set Ownership

bash

sudo chown -R www-data:www-data /var/www/omnisuite

Step 6: Configure Nginx

Create Nginx Configuration

Create configuration file:

bash

sudo nano /etc/nginx/sites-available/omnisuite

Add the following configuration:

nginx

server {
    listen 80;
    listen [::]:80;
    server_name yourdomain.com www.yourdomain.com;
    root /var/www/omnisuite/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.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }

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

Important: Replace yourdomain.com with your actual domain.

Enable Site

bash

sudo ln -s /etc/nginx/sites-available/omnisuite /etc/nginx/sites-enabled/
sudo nginx -t  # Test configuration
sudo systemctl reload nginx

Test Nginx Configuration

bash

sudo nginx -t

Should show: syntax is ok and test is successful

Step 7: Set Permissions

Set Directory Permissions

bash

cd /var/www/omnisuite
sudo chown -R www-data:www-data .
sudo find . -type d -exec chmod 755 {} \;
sudo find . -type f -exec chmod 644 {} \;

Set Writable Directories

bash

sudo chmod -R 775 storage bootstrap/cache
sudo chown -R www-data:www-data storage bootstrap/cache

Set Executable Files

bash

sudo chmod +x artisan

Step 8: Run the Installer

Access the Installer

Open browser
Navigate to: http://yourdomain.com/install
Or: http://your-server-ip/install

Follow Installer Steps

See Web Installer Guide for detailed steps.

Quick Summary:

Requirements check
Environment configuration
Database configuration
Admin account setup
Installation progress
Completion

Step 9: Post-Installation

Install Dependencies (if needed)

If installer doesn't handle this:

bash

cd /var/www/omnisuite
composer install --no-dev --optimize-autoloader
npm install
npm run build

Set Up SSL (Let's Encrypt)

Install Certbot:

bash

sudo apt install -y certbot python3-certbot-nginx

Obtain Certificate:

bash

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

Auto-Renewal:

bash

sudo certbot renew --dry-run

Configure Cron Jobs

Edit crontab:

bash

sudo crontab -e -u www-data

Add:

* * * * * cd /var/www/omnisuite && php artisan schedule:run >> /dev/null 2>&1

Set Up Queue Worker

Using Supervisor (Recommended):

Install Supervisor:

bash

sudo apt install -y supervisor

Create config:

bash

sudo nano /etc/supervisor/conf.d/omnisuite-worker.conf

Add configuration:

ini

[program:omnisuite-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/omnisuite/artisan queue:work --sleep=3 --tries=3
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/omnisuite/storage/logs/worker.log

Start Supervisor:

bash

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start omnisuite-worker:*

Troubleshooting

502 Bad Gateway

Problem: PHP-FPM not running or misconfigured

Solutions:

Check PHP-FPM status:
bash
```
sudo systemctl status php8.2-fpm
```
1
Restart PHP-FPM:
bash
```
sudo systemctl restart php8.2-fpm
```
1
Verify socket path in Nginx config matches PHP-FPM config
Check PHP-FPM socket:
bash
```
ls -la /var/run/php/php8.2-fpm.sock
```
1

404 Not Found

Problem: Nginx can't find files

Solutions:

Verify root path in Nginx config
Check file permissions
Verify index.php exists in public/ directory
Check Nginx error logs:
bash
```
sudo tail -f /var/log/nginx/error.log
```
1

Permission Denied

Problem: Web server can't access files

Solutions:

Check ownership:
bash
```
ls -la /var/www/omnisuite
```
1

Fix ownership:

bash

sudo chown -R www-data:www-data /var/www/omnisuite

Fix permissions:

bash

sudo chmod -R 755 /var/www/omnisuite
sudo chmod -R 775 storage bootstrap/cache

PHP Errors Not Displaying

Enable error display (development only):

Edit .env:
```
APP_DEBUG=true
```
1
Check PHP-FPM error log:
bash
```
sudo tail -f /var/log/php8.2-fpm.log
```
1

Static Files Not Loading

Problem: CSS/JS files return 404

Solutions:

Verify public/ directory is web root
Check Nginx config root directive
Clear browser cache
Verify file permissions

Performance Optimization

Enable Gzip Compression

Add to Nginx config:

nginx

gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/xml+rss application/json;

Enable Browser Caching

Add to Nginx config:

nginx

location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

PHP-FPM Optimization

Edit PHP-FPM pool:

bash

sudo nano /etc/php/8.2/fpm/pool.d/www.conf

Optimize settings:

ini

pm = dynamic
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20

Restart PHP-FPM:

bash

sudo systemctl restart php8.2-fpm

Security Recommendations

Firewall Configuration

UFW (Ubuntu):

bash

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

Nginx Security Headers

Add to server block:

nginx

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;

Hide PHP Version

In php.ini:

ini

expose_php = Off

Next Steps

After successful installation:

Last Updated: [Date will be updated during final review]

Installation on Nginx ​

Table of Contents ​

Prerequisites ​

Step 1: Server Preparation ​

Update System Packages ​

Install Required Tools ​

Step 2: Install PHP and Extensions ​

Install PHP 8.2+ ​

Install Required PHP Extensions ​

Verify PHP Installation ​

Configure PHP-FPM ​

Step 3: Install Composer and Node.js ​

Install Composer ​

Install Node.js and NPM ​

Step 4: Create Database ​

MySQL/MariaDB ​

PostgreSQL ​

Step 5: Upload Files ​

Option A: Using Git (Recommended) ​

Option B: Using SCP/SFTP ​

Option C: Manual Upload ​

Set Ownership ​

Step 6: Configure Nginx ​

Create Nginx Configuration ​

Enable Site ​

Test Nginx Configuration ​

Step 7: Set Permissions ​

Set Directory Permissions ​

Set Writable Directories ​

Set Executable Files ​

Step 8: Run the Installer ​

Access the Installer ​

Follow Installer Steps ​

Step 9: Post-Installation ​

Install Dependencies (if needed) ​

Set Up SSL (Let's Encrypt) ​

Configure Cron Jobs ​

Set Up Queue Worker ​

Troubleshooting ​

502 Bad Gateway ​

404 Not Found ​

Permission Denied ​

PHP Errors Not Displaying ​

Static Files Not Loading ​

Performance Optimization ​

Enable Gzip Compression ​

Enable Browser Caching ​

PHP-FPM Optimization ​

Security Recommendations ​

Firewall Configuration ​

Nginx Security Headers ​

Hide PHP Version ​

Next Steps ​

Installation on Nginx

Table of Contents

Prerequisites

Step 1: Server Preparation

Update System Packages

Install Required Tools

Step 2: Install PHP and Extensions

Install PHP 8.2+

Install Required PHP Extensions

Verify PHP Installation

Configure PHP-FPM

Step 3: Install Composer and Node.js

Install Composer

Install Node.js and NPM

Step 4: Create Database

MySQL/MariaDB

PostgreSQL

Step 5: Upload Files

Option A: Using Git (Recommended)

Option B: Using SCP/SFTP

Option C: Manual Upload

Set Ownership

Step 6: Configure Nginx

Create Nginx Configuration

Enable Site

Test Nginx Configuration

Step 7: Set Permissions

Set Directory Permissions

Set Writable Directories

Set Executable Files

Step 8: Run the Installer

Access the Installer

Follow Installer Steps

Step 9: Post-Installation

Install Dependencies (if needed)

Set Up SSL (Let's Encrypt)

Configure Cron Jobs

Set Up Queue Worker

Troubleshooting

502 Bad Gateway

404 Not Found

Permission Denied

PHP Errors Not Displaying

Static Files Not Loading

Performance Optimization

Enable Gzip Compression

Enable Browser Caching

PHP-FPM Optimization

Security Recommendations

Firewall Configuration

Nginx Security Headers

Hide PHP Version

Next Steps