Installation

This guide will walk you through installing SocialApparatus on your server. The process takes about 10-15 minutes for a complete setup.

Requirements

Before installing, ensure your server meets these requirements:

Requirement	Minimum Version	Recommended
PHP	8.2	8.3+
MySQL / MariaDB	8.0 / 10.6	Latest stable
Node.js	18.x	20.x LTS
Composer	2.x	Latest

Required PHP Extensions

BCMath
Ctype
cURL
DOM
Fileinfo
GD or Imagick
JSON
Mbstring
OpenSSL
PDO (MySQL)
Tokenizer
XML
Zip

Using Laravel Herd or Valet? All required extensions are already installed. You can skip the extension check.

Installation Steps

Clone the Repository

Clone SocialApparatus from GitHub to your server:

git clone https://github.com/mrshanebarron/socialapparatus.git
cd socialapparatus

Install PHP Dependencies

Use Composer to install all PHP packages:

composer install --optimize-autoloader --no-dev

Remove --no-dev if you're setting up a development environment.

Install Frontend Dependencies

Install Node.js packages and build assets:

npm install
npm run build

Configure Environment

Copy the example environment file and generate an application key:

cp .env.example .env
php artisan key:generate

Configure Database

Create a MySQL database and update your .env file:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=socialapparatus
DB_USERNAME=your_username
DB_PASSWORD=your_password

Run Migrations

Create all database tables:

php artisan migrate

Seed Initial Data (Optional)

Populate the database with sample data for testing:

php artisan db:seed

This creates a default admin user:
Email: admin@example.com
Password: password

Link Storage

Create a symbolic link for file uploads:

php artisan storage:link

Set Permissions

Ensure proper file permissions:

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

Replace www-data with your web server's user if different.

Quick Install Script

For convenience, you can run this all-in-one installation script:

#!/bin/bash
# SocialApparatus Quick Install

git clone https://github.com/mrshanebarron/socialapparatus.git
cd socialapparatus

composer install --optimize-autoloader --no-dev
npm install && npm run build

cp .env.example .env
php artisan key:generate

# Configure your .env file with database credentials here
# Then run:
php artisan migrate --seed
php artisan storage:link

chmod -R 775 storage bootstrap/cache

echo "Installation complete!"

Web Server Configuration

Nginx (Recommended)

server {
    listen 80;
    server_name your-community.com;
    root /var/www/socialapparatus/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

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

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_hide_header X-Powered-By;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Apache

Ensure mod_rewrite is enabled. The included .htaccess file handles URL rewriting:

<VirtualHost *:80>
    ServerName your-community.com
    DocumentRoot /var/www/socialapparatus/public

    <Directory /var/www/socialapparatus/public>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/socialapparatus_error.log
    CustomLog ${APACHE_LOG_DIR}/socialapparatus_access.log combined
</VirtualHost>

SSL Certificate

We strongly recommend using HTTPS. Use Let's Encrypt for free SSL certificates:

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

# Obtain certificate
sudo certbot --nginx -d your-community.com

Verify Installation

After completing the installation:

Visit your domain in a browser
You should see the SocialApparatus homepage
Log in with the admin credentials (if you ran the seeder)
Access the admin panel at /admin

Production Checklist:

Set APP_ENV=production
Set APP_DEBUG=false
Configure proper mail settings
Set up queue workers (see Deployment Guide)
Configure caching for performance

Troubleshooting

Common Issues

Problem	Solution
500 Internal Server Error	Check `storage/logs/laravel.log` for details. Usually a permissions issue.
Blank page	Run `php artisan config:clear` and check file permissions.
Database connection error	Verify credentials in `.env`. Test with `php artisan db:show`.
Assets not loading	Run `npm run build` and verify `storage:link` was created.
Queue jobs not processing	Start a queue worker: `php artisan queue:work`

Next Steps

Now that SocialApparatus is installed: