📦 Installation Guide

Complete step-by-step guide to installing Xiuno BBS 4.0.4 on your server.

System Requirements

Server Requirements

PHP: 7.4, 8.0, 8.1, 8.2, 8.3, or 8.4
MySQL: 5.6+ or MariaDB 10.0+
Web Server: Apache 2.4+ or Nginx 1.18+
Disk Space: Minimum 50MB
Memory: Minimum 256MB (512MB recommended)

Required PHP Extensions

mysqli or pdo_mysql
mbstring
gd or imagick (for image processing)
json
zip (optional, for plugin management)

💡 Tip: Xiuno BBS 4.0.4 is optimized for PHP 8.x and uses utf8mb4 encoding for full Unicode support.

Installation Methods

Method 1: Fresh Installation

Step 1: Upload Files

Upload all Xiuno BBS files to your web server's public directory:

# Via FTP/SFTP
Upload to: /public_html/ or /var/www/html/

# Via SSH
cd /home/yourusername/
wget https://xiuno.wiki/downloads/releases/xiuno-bbs-4.0.4.zip
unzip xiuno-bbs-4.0.4.zip
mv xiuno-bbs-4.0.4/* public_html/

Step 2: Set Permissions

Set proper file permissions for security:

chmod 755 /home/yourusername/public_html
chmod 644 /home/yourusername/public_html/*.php
chmod 755 /home/yourusername/public_html/upload
chmod 755 /home/yourusername/public_html/tmp
chmod 755 /home/yourusername/public_html/log
chmod 600 /home/yourusername/public_html/conf/conf.php

⚠️ Security: Never set 777 permissions. Use 755 for directories and 644 for files.

Step 3: Create Database

Create a MySQL database and user:

mysql -u root -p

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

Step 4: Configure Database

Edit conf/conf.php with your database credentials:

<?php
return array(
    // Database Configuration
    'db' => array(
        'type' => 'mysql',
        'host' => '127.0.0.1',
        'port' => 3306,
        'name' => 'xiuno',
        'user' => 'xiuno',
        'pass' => 'your_strong_password',
        'charset' => 'utf8mb4',
        'engine' => 'MyISAM',
        'prefix' => 'bbs_',
    ),
    
    // Site Information
    'sitename' => 'Xiuno Wiki',
    'sitebrief' => 'Documentation, Downloads & Community',
    'siteurl' => 'https://xiuno.wiki',
    
    // Other Settings
    'lang' => 'en-us',
    'timezone' => 'America/New_York',
);

Step 5: Run Installer

The platform will auto-initialize on first access. Simply visit:

https://yourdomain.com/

✅ Success: If configured correctly, Xiuno will automatically create all database tables and you'll see the forum homepage.

Post-Installation Setup

1. Access Admin Panel

URL: https://yourdomain.com/admin/
Default Username: admin
Default Password: (set during database creation)

2. Configure .htaccess (Apache)

For SEO-friendly URLs, ensure .htaccess is properly configured:

RewriteEngine On
RewriteBase /

# Prevent access to sensitive directories
RewriteRule ^conf/ - [F,L]
RewriteRule ^tmp/ - [F,L]
RewriteRule ^log/ - [F,L]

# Main rewrite
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]

3. Nginx Configuration

For Nginx servers, add this to your site config:

server {
    listen 80;
    server_name yourdomain.com;
    root /home/yourusername/public_html;
    index index.php index.html;

    # Deny access to sensitive directories
    location ~ ^/(conf|tmp|log|tool)/ {
        deny all;
    }

    # PHP processing
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

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

4. SSL/HTTPS Setup

Secure your site with Let's Encrypt (recommended):

# Install Certbot
sudo apt install certbot python3-certbot-apache

# Get SSL certificate
sudo certbot --apache -d yourdomain.com -d www.yourdomain.com

# Auto-renewal
sudo certbot renew --dry-run

Verification Checklist

✓ Homepage loads without errors
✓ Admin panel is accessible
✓ Can create test forum/thread
✓ File uploads work (test in admin)
✓ URL rewriting functions correctly
✓ SSL certificate installed (HTTPS)
✓ Permissions set correctly (not 777)

Common Installation Issues

Database Connection Failed

Check database credentials in conf/conf.php
Verify MySQL service is running: systemctl status mysql
Ensure user has proper privileges
Check if MySQL allows remote connections (if using remote DB)

White Page / 500 Error

Check PHP error logs: tail -f /var/log/apache2/error.log
Verify PHP version compatibility (7.4 - 8.4)
Check file permissions
Enable error display temporarily in index.php: error_reporting(E_ALL);

Upload Directory Not Writable

chmod 755 upload/
chown www-data:www-data upload/

Next Steps

After successful installation:

Need Help? Visit our community forum for support and questions.