5-Minute Quick Start Guide

Launch your first project with Pragma CMS in 5 minutes. This guide covers the journey from provisioning a site on the Platform to mastering content layouts.

Step 1: Create your Site (Platform)

Log in to your Global Platform Dashboard and click Create New Site.

Define your Site Name, your Site Handle (internal folder name) and your Primary Domain.
The platform will automatically provision the file structure and a dedicated database for this site.

Step 2: Configure Identity (Admin)

Enter your new Site Admin. Your first stop should be System > General Settings.

Upload your Logo and Favicon.
Configure SMTP settings to ensure your site can send emails (forms, notifications).

Step 3: Define your Look & Feel (Themes)

Go to Appearance > Themes. Pragma CMS uses a "Safe Copy" system:

When you customize the Default Theme, the CMS creates a dedicated copy in your site folder.
This protects your design changes from being overwritten during system updates. You can edit CSS and Twig templates directly from the Theme Editor.

Step 4: Routing & Architecture

Routing is the bridge between a URL and your logic. Before creating complex content, you must define its path.

Go to Structure > Routes.
Create a new route (e.g., services/{slug}).
Link it: Associate this route with a Content Type (e.g., "Services").
Map it: Assign a template file (e.g., pages/service-detail.php) that will handle the display logic.

Step 5: Choose your Content Strategy

Pragma CMS offers three ways to build your pages:

Standard Pages (WYSIWYG): Go to Structure > Pages and create a "Static" page. Best for text-heavy content like Privacy Policies.
Visual Builder (Block-based): Create a "Builder" page to use Editor.js. This allows you to stack modular blocks (Images, Call-to-actions, Code snippets) to create rich landing pages without touching code.
Content Modeling (Structured): For repetitive data like "Team Members" or "Services", go to Architecture > Content Types. Define a schema, and the CMS will build the SQL table for you.
- Pro Tip: You can add a Visual Builder field inside your custom Content Type for the best of both worlds (structured data + flexible layouts).

Step 6: SEO, Extensions & Launch

Before going live:

Explore the Extension Library to add advanced features like SEO Pro or Analytics.
Check your SEO Settings to verify your meta tags and OpenGraph images.
Once ready, disable Maintenance Mode in General Settings. Your site is now live!

Step 7: Deploying to Production (Migration Guide)

Migrating your Pragma CMS site from local development (e.g., your-site.local) to a live production VPS is straightforward thanks to our Clean Monolith architecture. Because the core engine and site files are strictly separated, migration involves transferring your tenant directory, migrating the database, and updating your configuration constants.

Live Environments (Code vs. Content)

Once your site is live, managing changes between local and production requires a simple, disciplined workflow to prevent data loss or database out-of-sync issues:

Database Content & Media (Production-Only):
Your live production site is the single source of truth for all content. Writing articles, uploading media, and creating navigation menus must occur directly on the production server. Never try to push local database dumps over a live database, as this will overwrite client-submitted data and break relational IDs.
Code, Themes & Extensions (Local-First):
Never write, edit, or test code directly on your production server. Develop your Twig templates, CSS/JS assets, and custom PHP controllers locally. Once tested and validated on your machine, deploy only the modified files to production (via SFTP, Rsync, or Git).
Database Schema Sync (Explicit Synchronization):
If you create a new Content Type or custom fields in your local environment, you do not need to manually run SQL migrations on your production database. Pragma CMS Content Models are file-based blueprints (saved under /content-types/).
When you deploy these files to production, simply log in to your live Admin Dashboard, navigate to Architecture > Content Types, and click the Synchronize Files button. The CMS will parse the new blueprints and update the production database schema instantly.
Keeping Local in Sync:
When you need to build a new feature locally, first download a production database dump (via the admin dashboard or CLI backup script) and import it into your local database. Download the /media/ folder as well. Your local setup is now a perfect replica of production, safe for offline development.

Migration Checklist

1. Export Your Local Database

Export your local database schema and data into a single .sql file using mysqldump or your preferred GUI client (DBeaver, TablePlus).

BASH

mysqldump -u [local_db_user] -p pragma_cms > [my_database].sql

2. Deploy Site Files to the Server

Transfer your dedicated site directory /sites/[your-site-handle] to the remote server under /var/www/pragma-cms/sites/[your-site-handle]. You can use SFTP, rsync, or Git.

Note: Ensure the local /storage/cache/ and /storage/tmp/ directories are cleared before transferring to avoid carrying over local cache states. Do not replace your production config_db.php file!

3. Transfer and Import the Database

Upload your local database dump to the production VPS and import it into your secure remote MariaDB instance.

Transfer the SQL file using PowerShell or SFTP:

BASH

scp C:\Users\[User]\Downloads\[my_database].sql [vpsUser]@[Server_IP]:/tmp/

SSH into your server and import the file (drop and recreate the database first to ensure a clean import):

BASH

mysql -u [prod_db_user] -p
# Inside MySQL:
DROP DATABASE [my_old_database]; # If it already existed
CREATE DATABASE [my_database] CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;

# Run the import:
mysql -u [prod_db_user] -p pragma_cms < /tmp/[my_database].sql

4. Update Production Database Config (config_db.php)

Open the database configuration file on your production server and update it with your live VPS database credentials.

File: /sites/[your-site-handle]/config_db.php

BASH

<?php
return [
    'host' => '127.0.0.1',
    'user' => 'pragma_master',
    'password' => 'your_secure_prod_password',
    'database' => 'my_database',
    'port' => 3306,
];

5. Update the Site URL in Settings (Critical)

If your database dump was exported from a local environment, the database still references your local URL (e.g., http://my-domain.local). You must update this to your production HTTPS URL to prevent security warnings or redirect loops.

Option A: Direct SQL Update (Fastest)
Run a direct query on your production database server to update the global setting key:

BASH

UPDATE settings SET setting_value = 'https://my-domain.com' WHERE setting_key = 'site_url';

Option B: Via the Admin Dashboard
If you can access the admin panel, navigate to Settings > General and update the Site URL field to https://my-domain.com.