Docs 1
Home GitHub
menu_book Navigation menu
Documentation Getting Started Requirements

Requirements

Before starting the installation, ensure your server meets the following requirements:

1. Web Server

A web server such as Apache, Nginx, or Caddy with PHP support.

2. PHP

PHP 8.0 or higher is required. The following extensions must be enabled:

  • mysqli: Required only for the initial installation to configure and verify the database.
  • PDO_MySQL: Required for all database operations after installation.
  • cURL: To communicate with external servers (update system).
  • Zip: To handle updates and extension installations.
  • gd: For image processing (thumbnails, resizing).
  • mbstring: For multibyte string management, essential for UTF-8.
  • intl: For advanced internationalization (localized date and number formats).
  • Imagick (Recommended): To generate thumbnails and preview PDFs, SVGs, etc. Highly recommended for commercial use.
  • Ghostscript (Optional but highly recommended with Imagick for PDF/AI/EPS): To convert PostScript and PDF files into images. Without it, previews for these files will not work.

On Debian/Ubuntu:

We recommend using the official repository by Ondřej Surý to get the most stable and recent version.

BASH 
# Update package lists
sudo apt update

# Install the native stack (PHP 8.4 or higher is default on Ubuntu 24.04)
sudo apt install -y php-fpm php-mysql php-curl php-gd php-intl php-mbstring php-xml php-zip php-imagick ghostscript

Applying Changes:

After installing new extensions or modifying the configuration (php.ini), you must restart the PHP service.

If you are using Nginx or Caddy (Recommended - adapt the PHP version):

BASH 
sudo systemctl restart php8.4-fpm

If you are using Apache (Standard module):

BASH 
sudo systemctl restart apache2

Performance: Enable OPcache (Recommended in Production)

PHP is an interpreted language. By default, it reads and compiles your scripts on every visit. The OPcache extension keeps the compiled code in memory, which reduces server load by two or three times.

1. Configuration

Open the PHP FPM configuration file (adapt the version, e.g., 8.4):

BASH 
nano /etc/php/8.4/fpm/php.ini

Search for the [opcache] section and apply the following configuration for maximum performance:

BASH 
[opcache]
; Activation
opcache.enable=1

; Allocated Memory
opcache.memory_consumption=256 ; Increased to 256MB (comfortable for an 8GB VPS)
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=20000  ; Increased to handle Core + client sites

; BALANCED CONFIGURATION (PERFORMANCE + CONVENIENCE)
opcache.validate_timestamps=1        ; Tells PHP to check if the file date has changed.
opcache.revalidate_freq=0            ; Tells PHP to check on every request (instant).
opcache.save_comments=1 ; Preserve comments (required for some internal CMS logic)

Once the file is saved, apply the changes:

BASH 
# For Nginx / Caddy
service php8.4-fpm restart

# For Apache
service apache2 restart

2. Update Workflow (Deployment)

If opcache.validate_timestamps=0 is enabled, PHP will not automatically detect if you modify a PHP file via SFTP or Git.

After every code update, you must run this command to clear the cache and take changes into account:

BASH 
# Clears the OPcache without dropping active connections
service php8.4-fpm reload

Server Restart:

Once the configuration is modified, or every time you update your site's code (if revalidate_freq=0), you must restart the PHP process.

BASH 
# For Caddy or Nginx (using PHP-FPM)
# Replace 8.4 with your PHP version
sudo systemctl restart php8.4-fpm

# For Apache (if used as a standard module)
sudo systemctl restart apache2
warning
Important
With opcache.revalidate_freq=0, your code modifications (PHP files) will not appear online until the PHP-FPM service is restarted. This is the highest-performance setting for production.

3. Database Server

  • MySQL (≥ 5.7) or MariaDB (≥ 10.3).
  • You will need:
    • Database host and port (ex : localhost:3306)
    • MySQL username and password
  • User Privileges: The user must be able to:
    1. Connect to the MySQL server
    2. Create a database if it doesn't exist (CREATE DATABASE)
    3. If the database exists, create and access tables
  • Database Name: If the user cannot create a database, create an empty one manually before installation.

4. Write Permissions

For the platform to function (site creation, auto-updates, asset publishing), the web server user (e.g., www-data) must have write permissions on specific directories.

Required Directories:

  • sites/: Essential. The platform must be able to create directories for new clients and write their configuration files (config.json, config_db.php).
  • cms-versions/: Essential for the update system. This is where new core versions are downloaded and extracted.
  • public/assets/: Required to publish (copy) CSS/JS files from the core to the accessible public folder.
  • storage/: For temporary files (ZIP downloads, logs, cache).

Linux :

BASH 
# Go to the project root
cd /var/www/pragma-cms

# Give ownership to the web user (often www-data)
sudo chown -R www-data:www-data sites cms-versions public/assets storage

# Give read/write/execute permissions (755 is recommended)
sudo chmod -R 755 sites cms-versions public/assets storage
info
Security Note
It is recommended to leave files at the root (like public/index.php or domain_mapping.php) as read-only for the web server once the installation is complete, to prevent any accidental or malicious modification.

Windows (XAMPP/WAMP/IIS) :

  • Navigate to your project folder.
  • Navigate to your project folder.
  • For the sites, cms-versions, public/assets, and storage folders:
  • Right-click > Properties > Security.
  • Edit > Add > Select the IUSR user (IIS) or your local user (XAMPP/WAMP).
  • Check "Full control" or "Modify".

5. Web Browser

A modern browser with JavaScript enabled is required for the installer's interactive interface.