Getting Started with XooPress

A Complete Beginner's Guide to Installation and Setup

Welcome to XooPress, the modular CMS that combines the best of XOOPS and WordPress! This guide will walk you through everything you need to know to get started with your new CMS.

🎉 Easy Installation! XooPress features a beautiful 4-step web installer that guides you through setup. No manual configuration files needed!

📋 Prerequisites

Before you begin, make sure you have:

PHP 8.2 or higher
MySQL 5.8 or MariaDB 10.11+
Composer (for dependency management)
Apache/Nginx web server with mod_rewrite
Required PHP extensions: PDO, PDO MySQL, gettext, mbstring, JSON, Session

🚀 The 4-Step Web Installer

XooPress includes a user-friendly web installer with a progress indicator showing your setup journey. Let's walk through each step:

✓

Step 1: System Requirements Check

The installer first checks if your server meets all requirements:

✅ Requirements Verified:

PHP Version 8.2+ check
PDO Extension & MySQL Driver
gettext, mbstring, JSON, Session extensions
Directory write permissions (config, cache, logs)

The installer displays a clear pass/fail status for each requirement. If everything passes, you'll see a green success message and can proceed to Step 2.

💡 Pro Tip: The installer automatically detects common issues. If something fails, it tells you exactly what's missing and why!

Step 2: Database Configuration

Enter your MySQL connection details:

📝 Database Settings:

🔹 Host - Usually "localhost" (try 127.0.0.1 for socket issues)
🔹 Port - MySQL port (default: 3306)
🔹 Database Name - Will be created automatically if it doesn't exist
🔹 Username & Password - MySQL credentials
🔹 Table Prefix - Default is xp_ (recommended to keep)

The installer includes intelligent troubleshooting:

Automatically tries TCP connections AND Unix socket paths
Provides helpful MySQL 8 compatibility hints
Suggests creating a dedicated database user if root access fails
Tests the connection before proceeding

⚠️ MySQL 8 Note: MySQL 8's root user may use auth_socket authentication. If you get "Access denied", the installer suggests creating a dedicated user with mysql_native_password.

Step 3: Admin Account Creation

Create your administrator account:

👤 Admin Details:

🔹 Username - Minimum 3 characters (choose something secure)
🔹 Email Address - For password recovery and notifications
🔹 Password - Minimum 8 characters (strongly recommended)
🔹 Confirm Password - Verification

Step 4: Automatic Installation

The installer now handles everything automatically:

⚙️

Installation in Progress...
Creating tables • Setting up admin • Writing configuration

During this step, the installer:

✅ Creates all database tables (users, settings, sessions, posts, categories, post_meta)
✅ Registers the System and Content modules in xp_modules
✅ Creates the admin user with BCrypt password hashing
✅ Sets up default site settings
✅ Creates the "Uncategorized" default category
✅ Generates config/app.local.php with your settings
✅ Creates config/installed.lock to prevent re-installation

🎉 Installation Complete!

After successful installation, you'll see a summary screen with:

✓ Your Installation Summary:

Site URL:: /
Admin Username:: The username you created
Admin Email:: Your admin email address
Database Name:: The database you configured
Table Prefix:: Your chosen prefix (default: xp_)

🔒 Important Security Step: After logging in, delete the public/install.php file from your server to prevent unauthorized re-installation!

🔧 What Gets Installed?

XooPress creates the following database tables during installation:

Table	Purpose
`xp_users`	User accounts and authentication
`xp_settings`	Global site settings
`xp_sessions`	User session management
`xp_posts`	Content posts and pages
`xp_categories`	Category taxonomy
`xp_post_meta`	Post metadata
`xp_modules`	Module registry

🎯 Post-Installation Checklist

1️⃣

Delete install.php

Remove /public/install.php for security

2️⃣

Login to Admin

Go to /login with your admin credentials

3️⃣

Choose a Theme

Visit /admin/themes and activate XooPress Lite or Dark

4️⃣

Create Content

Start writing posts and pages in your preferred editor

🆘 Troubleshooting Common Issues

Issue	Solution
"Missing extension: PDO MySQL"	Install php-mysqlnd or php-pdo-mysql package
"Config directory is not writable"	Run: `chmod 755 config/ storage/cache storage/logs`
"Access denied for user 'root'@'localhost'"	Create a dedicated MySQL user as suggested by installer
"Connection refused"	Ensure MySQL is running: `sudo systemctl start mysql`
White screen after installation	Check PHP error log and ensure all Composer dependencies installed

📚 Next Steps

Congratulations! XooPress is now installed. Here's what to explore next:

📖 Markdown vs HTML vs PHP - Which Editor Should You Use?
🛠️ Building Your First XooPress Module
🎨 Creating Stunning Themes for XooPress
🔧 Visit /admin to configure your site settings
📦 Check out additional modules in the marketplace

💬 Need Help? Join our community forums or check the official documentation for more detailed guidance!

Happy building with XooPress! 🚀 The 4-step installer makes setup a breeze, so you can focus on creating amazing content.