Splintr Installation & Administration Guide


Quick Start


  1. Upload the Splintr files to your web hosting
  2. Extract the files to your desired location
  3. Visit yourdomain.com/install.php
  4. Follow the installer wizard
  5. Delete install.php when complete


System Requirements


Server Requirements:

  • PHP 7.4 or higher
  • MySQL 5.7+ or MariaDB 10.2+
  • Web server (Apache with mod_rewrite, or Nginx)
  • 256MB RAM minimum, 512MB recommended
  • 100MB+ disk space
  • HTTPS (SSL certificate) — required for federation

PHP Extensions Required:

  • PDO and PDO_MySQL
  • JSON, cURL, GD, OpenSSL
  • Zip (php-zip) — required for plugin installation

Optional but Recommended:

  • ImageMagick (better image processing)
  • mbstring (international text support)


Installation Steps


Step 1: Upload Files


  1. Download the Splintr installation package
  2. Upload to your web server:
  • VPS/Dedicated: Upload to /var/www/yourdomain.com/ or your configured web root
  • Shared hosting: Upload to public_html/ or www/
  • Subdirectory: Upload to public_html/splintr/

Step 2: Extract Files


Verify these files are present:

  • install.php
  • config.php (will be created during installation)
  • Folders: core/, css/, js/, api/, templates/, includes/, plugins/

Step 3: Create Database


  1. Create a new MySQL database (e.g., yourname_splintr)
  2. Create a database user with password
  3. Grant the user all privileges on the database
  4. Note down: database name, username, password, host (usually localhost)

Step 4: Run Installation Wizard


  1. Visit: https://yourdomain.com/install.php
  2. System Check: Verify all requirements are met
  3. Configuration:

Database Settings:

  • Host: localhost (or provided by hosting provider)
  • Database Name: Your created database name
  • Username: Database user
  • Password: Database password

URL Structure:

  • Path per user (recommended): yourdomain.com/username
  • Single user: One user owns entire domain

Administrator Account:

  • Username: Your admin login (avoid reserved words like admin, api)
  • Email: Your email address
  • Password: 8+ characters, must include at least one letter and one number
  • Display Name: How your name appears

Server Type:

  • Personal: Single user node
  • Community: Moderated public/private cluster

  1. Install: Click "Install Splintr"
  2. Complete: Follow final instructions and delete install.php

Step 5: Security Setup


  1. Delete installer: Remove install.php for security
  2. Set file permissions:
  • Folders: 755 (uploads/, cache/, logs/, plugins/)
  • Files: 644 (most files)
  • Config: 600 (config.php)
  1. Production mode: Ensure SPLINTR_DEV_MODE is set to false in config.php
  2. Backup config: Save a copy of config.php securely

Step 6: Config.php Settings


After installation, verify these settings in config.php:


// Set to false in production — controls SSL verification, error display
define('SPLINTR_DEV_MODE', false);


Post-Installation Setup


First Login

  1. Visit your domain
  2. Login with admin credentials created during installation
  3. Complete your profile information

User Management


Create Additional Users:

  1. Go to Admin → User Management
  2. Click "Add New User"
  3. Set account type (Person/Group/Business)
  4. Send invitation or create directly

Essential Settings


Privacy & Security:

  • Review registration settings
  • Configure content filtering
  • Set default privacy levels
  • Enable/disable federation with other servers

Appearance:

  • Customize theme colors via CSS variables
  • Upload logo/favicon
  • Enable user theme customization


URL Structure Guide


Path-Based (domain.com/user) — Recommended

Best for: Most installations, shared or dedicated hosting


Users get: yourdomain.com/username
No special DNS required
Single SSL certificate covers everything


Single User (domain.com)

Best for: Personal blogs, individual use


Primary user owns entire domain
Other users can be added as: domain.com/username



Administration Tasks


User Management

  • Add Users: Admin → Users → Add New User
  • Manage Permissions: Edit user → Permissions tab

DNS Federation Identity (Optional)


Publishing a _splintr TXT record in your domain's DNS allows other Splintr servers to verify your server's identity independently, protecting against domain impersonation. This is optional — federation works without it via the existing trust-on-first-use (TOFU) model.


To set up:


  1. Go to Admin → Settings and find the "Federation DNS Identity" section
  2. Copy the DNS Record Hostname (e.g. _splintr.yourdomain.com)
  3. Copy the TXT Record Value (starts with v=splintr1; alg=rsa-sha256; p=...)
  4. In your DNS provider's control panel, create a new TXT record:
  • Host/Name: _splintr (or _splintr.yourdomain.com depending on your provider's format)
  • Type: TXT
  • Value: the value from step 3
  • TTL: 3600 (1 hour) or higher
  1. Wait for DNS propagation (can take minutes to hours)
  2. Return to Admin → Settings to verify the record is detected

What it does: When another Splintr server receives a federation request claiming to be from your domain, it looks up your _splintr TXT record and verifies the request's signature matches the key published in DNS. If the keys don't match, the request is rejected. If no DNS record is found, the server falls back to the standard TOFU handshake model.


Plugin Management


Splintr supports installable plugins (games, tools, widgets) that run in sandboxed iframes.


Installing a Plugin:

  1. Go to Admin → Plugins
  2. Upload a plugin ZIP file (must contain a manifest.json at the root)
  3. Optionally override the plugin's suggested category
  4. Click Upload & Install — the server validates the manifest and verifies file checksums
  5. Click Enable to make it available to users

Managing Plugins:

  • Enable/Disable: Toggle a plugin on or off without uninstalling it
  • Verify: Re-check file checksums against the manifest (detects tampering)
  • Category: Override the plugin's category for navigation
  • Uninstall: Removes the plugin, its files, and all associated data (scores, saves, events)

Plugins appear under the Plugins nav item for logged-in users. Each server admin controls which plugins are installed and enabled on their server independently.


Maintenance

  • Logs: Check logs/ directory for application errors
  • Backups: Regular database backups recommended
  • Updates: Replace application files via rsync or manual upload; never overwrite config.php, uploads/, user-data/, keys/, plugins/, or .well-known/


Using Cloudflare


DNS only (grey cloud) — recommended. Cloudflare answers DNS for your domain (and can handle the DNS challenge for Let's Encrypt), but browsers and other Splintr servers connect straight to your server. Cloudflare never sees your traffic.


Proxied (orange cloud). Cloudflare decrypts every request to your site before passing it on, so it can read everything that goes through it: logins and passwords, posts (including friends-only), private messages as they're sent and read, and federation traffic. Encryption inside Splintr doesn't change that — messages are encrypted at rest on the server, not in the browser. If you proxy anyway:


  • Set SSL/TLS mode to Full (strict) so the Cloudflare → server leg stays encrypted and verified.
  • Cache only static files: /css/*, /js/*, /assets/*, /themes/*. Bypass the cache for /api/*, /admin/*, /.well-known/* and /user-data/* — media links are signed and expire, and a cached copy would outlive the link.
  • Restore visitor IPs (Apache mod_remoteip with Cloudflare's published IP ranges); otherwise security logs and login rate limiting see Cloudflare's addresses instead of your visitors'.

Troubleshooting


Common Issues


"Permission denied" errors:

chmod 755 uploads/ cache/ logs/
chmod 644 *.php *.css *.js
chmod 600 config.php

Database connection failed:

  • Verify database credentials in config.php
  • Check if database exists
  • Ensure user has proper privileges

Static files not loading:

  • Check .htaccess file exists and is readable
  • Verify mod_rewrite is enabled
  • Check file permissions on css/, js/ folders

Federation not working:

  • Verify HTTPS is configured and certificate is valid
  • Check that SPLINTR_DEV_MODE is false (SSL verification must be enabled)
  • Verify .well-known/splintr server discovery file exists and is accessible
  • Check logs/ for federation-specific error messages

Debug Mode


Add to config.php for troubleshooting only (remove in production):

define('SPLINTR_DEV_MODE', true);

This enables display_errors and disables SSL verification for federation requests. Never leave this enabled in production.



Security Best Practices


Server Security

  • Keep PHP and MySQL updated
  • Use strong database passwords
  • Enable HTTPS with a valid SSL certificate
  • Regular security updates
  • Set SPLINTR_DEV_MODE to false in production

Application Security

  • Delete install.php after setup
  • Use strong passwords (8+ characters, letters + numbers)
  • Rate limiting is enforced on all login endpoints
  • Error responses never expose internal details in production mode
  • Federation requests are cryptographically signed and verified
  • Media served via HMAC-signed expiring URLs

Backup Strategy

  • Database: Regular automated backups
  • Files: Backup uploads/ and user-data/ directories
  • Config: Keep secure copy of config.php and keys/ directory


Next Steps


  1. Set up your profile: Add a display name, avatar, and bio
  2. Invite users: Create accounts or send invitations
  3. Customize appearance: Edit theme variables in the admin panel
  4. Connect with other servers: Add friends on other Splintr installations
  5. Keep updated: Replace application files regularly for security fixes

Welcome to Splintr! Your private social network is ready to use.