SocialForge Documentation

Complete social media management platform built on Laravel 12

SocialForge is a self-hosted social media management platform that lets you schedule posts, monitor analytics, manage your inbox, and run AI-powered content campaigns — all from a single, beautiful dashboard. Built with Laravel 12, Livewire 3, and Tailwind CSS, it runs on any standard PHP hosting environment.

Supported Platforms

What's Included

Your purchase includes everything needed to run SocialForge on your own server.

Server Requirements

Minimum Requirements

Required PHP Extensions

Installation Guide

Follow these steps to install SocialForge on your server. No command line access is required for shared hosting.

1. 1
   Download & Upload Files

   Download the zip file from your CodeCanyon or Codester account. Upload it to your server via FTP (FileZilla) or cPanel File Manager.

   bash Copy

   # Recommended folder structure
   public_html/          ← for main domain install
   public_html/social/   ← for subdirectory install

2. 2
   Extract Files

   Right-click the zip file in cPanel File Manager and select Extract. Ensure the public/ folder contents are accessible from your web root. On most shared hosts, your web root is public_html/.

3. 3
   Set Folder Permissions

   Set write permissions on the storage and cache directories. This can be done via your FTP client or SSH.

   bash Copy

   chmod 755 storage/
   chmod 755 bootstrap/cache/
   chmod -R 775 storage/
   chmod -R 775 bootstrap/cache/

4. 4
   Run the Installer

   Open your browser and navigate to your domain followed by /install. The 6-step wizard will guide you through database setup, admin account creation, and license activation.

   yourdomain.com/install
5. 5
   Set Up the Cron Job

   After installation, set up a cron job so scheduled posts publish on time. In cPanel go to Cron Jobs and add:

   cron Copy

   * * * * * cd /path/to/socialforge && php artisan schedule:run >> /dev/null 2>&1

6. 6
   Configure Social APIs

   Add your social media API credentials to the .env file or via Settings → Social Accounts in the admin panel. See the Configuration section for each platform's setup guide.

Nginx Server Configuration

If you're using Nginx, use this configuration block:

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    root /var/www/socialforge/public;
    index index.php index.html;

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

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

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

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

License Activation

Finding Your License Key

After purchase your license key is included in the purchase confirmation email from CodeCanyon or Codester. It is also available in your account dashboard under Downloads. The key format is XXXX-XXXX-XXXX-XXXX.

Activating During Installation

Step 1 of the installation wizard asks for your license key. Enter the key and click Validate & Continue. The wizard connects to the license server, verifies the key, and stores it securely in your database.

Activating After Installation

If you skipped activation or need to re-enter your key, navigate to Settings → License in the admin panel. Enter your key and click Activate.

Transferring to a New Domain

To move SocialForge to a new domain, go to Settings → License → Transfer Domain. This deactivates the key on the old domain and activates it on the current one. You can transfer up to 3 times per year.

License Server Grace Period

If the license server is temporarily unreachable (e.g. during outages), SocialForge continues to function normally for up to 7 days. After that, a re-validation prompt will appear.

Environment Setup

All configuration is managed through the .env file in the project root. The installer creates this file automatically, but you may need to edit it for advanced configuration.

Database Configuration

SocialForge requires a MySQL 5.7+ or MariaDB 10.3+ database. The installer creates all tables automatically during Step 5.

Creating a Database (cPanel)

1. Log into cPanel and open MySQL Databases
2. Under Create New Database enter a name (e.g. socialforge) and click Create Database
3. Under MySQL Users create a new user with a strong password
4. Under Add User To Database grant the user ALL PRIVILEGES
5. Enter these credentials into the installer Step 3 or into your .env file

Running Migrations Manually

If the installer's migration step fails, you can run migrations via SSH:

php artisan migrate --force

Facebook & Instagram

Creating Your Facebook App

1. Go to developers.facebook.com and click My Apps → Create App
2. Select Business as the app type and click Next
3. Enter your app name and contact email address
4. From the left menu, find Products and click + next to Facebook Login
5. Under Facebook Login → Settings, add your OAuth Redirect URI:

https://yourdomain.com/auth/facebook/callback

6. Navigate to App Settings → Basic
7. Copy your App ID and App Secret

Required Permissions

• pages_manage_posts
• pages_read_engagement
• instagram_basic
• instagram_content_publish
• instagram_manage_insights

Environment Variables

META_APP_ID=your_app_id_here
META_APP_SECRET=your_app_secret_here
META_REDIRECT_URI=https://yourdomain.com/auth/facebook/callback

Twitter / X

Setup Steps

1. Go to developer.twitter.com/portal and create a new Project then an App inside it
2. Under App Settings → User authentication settings, click Set up
3. Enable OAuth 2.0 and set App type to Web App
4. Add your callback / redirect URI:

https://yourdomain.com/auth/twitter/callback

5. Copy your Client ID and Client Secret from the Keys and Tokens tab

Environment Variables

TWITTER_CLIENT_ID=your_client_id
TWITTER_CLIENT_SECRET=your_client_secret
TWITTER_CALLBACK_URL=https://yourdomain.com/auth/twitter/callback

LinkedIn

Setup Steps

1. Go to developer.linkedin.com and click Create App
2. Fill in your app name, associated LinkedIn Company Page, and upload a logo
3. Under the Auth tab, copy your Client ID and Client Secret
4. Add your OAuth 2.0 Redirect URL:

https://yourdomain.com/auth/linkedin/callback

5. Under the Products tab, request access to:
   • Sign In with LinkedIn using OpenID Connect
   • Share on LinkedIn
   • Marketing Developer Platform (for page analytics)

Environment Variables

LINKEDIN_CLIENT_ID=your_client_id
LINKEDIN_CLIENT_SECRET=your_client_secret
LINKEDIN_CALLBACK_URL=https://yourdomain.com/auth/linkedin/callback

TikTok

Setup Steps

1. Go to developers.tiktok.com and sign in with your TikTok account
2. Click Manage Apps → Connect an App
3. Fill in your app details, description, and category
4. Under Login Kit, add your redirect URI:

https://yourdomain.com/auth/tiktok/callback

5. Copy your Client Key and Client Secret from the app dashboard
6. Submit your app for review to enable content publishing

Environment Variables

TIKTOK_CLIENT_KEY=your_client_key
TIKTOK_CLIENT_SECRET=your_client_secret
TIKTOK_CALLBACK_URL=https://yourdomain.com/auth/tiktok/callback

YouTube / Google

Setup Steps

1. Go to console.cloud.google.com and create a new project
2. Navigate to APIs & Services → Library
3. Search for and enable YouTube Data API v3
4. Go to APIs & Services → Credentials
5. Click Create Credentials → OAuth Client ID
6. Select Web Application as the application type
7. Add your authorised redirect URI:

https://yourdomain.com/auth/google/callback

8. Copy your Client ID and Client Secret from the credentials page
9. Set up the OAuth Consent Screen with your app name and logo

Environment Variables

GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_CALLBACK_URL=https://yourdomain.com/auth/google/callback

Dashboard Overview

The dashboard is your central hub. It surfaces the most important information at a glance — upcoming posts, recent analytics, and platform health.

Dashboard Widgets

Compose & Schedule

The post composer lets you craft content for multiple platforms simultaneously, with per-platform overrides and live preview.

Key Features

• Multi-platform selection — choose one or multiple platforms per post
• Per-platform overrides — customize caption, media, or hashtags per platform
• Live preview — see how your post looks on each platform before publishing
• AI caption generator — generate captions with Google Gemini AI
• Hashtag manager — save and reuse hashtag groups
• Media upload — drag-and-drop images and videos with auto-thumbnail
• Schedule or post now — pick a date/time or publish immediately
• Best time suggestions — AI-recommended posting times based on engagement history

Bulk Scheduling

Upload and schedule multiple posts at once using a CSV file — ideal for campaigns and content batches.

CSV Format

platform,caption,scheduled_at,image_url
twitter,Check out our new feature! #launch,2026-04-01 09:00:00,https://example.com/img.jpg
facebook,We just launched something exciting…,2026-04-01 10:00:00,

Steps

1. Navigate to Compose → Bulk Schedule
2. Download the CSV template
3. Fill in your posts and save the file
4. Upload the CSV — SocialForge validates each row and shows a preview
5. Confirm to schedule all valid posts

Post Calendar

The visual calendar shows all scheduled and published posts in a monthly, weekly, or daily view.

Calendar Features

• Drag-and-drop rescheduling — drag a post to a new time slot
• Platform colour coding — each platform has a distinct colour
• Click to edit — click any post to open the composer with pre-filled content
• Month / Week / Day views — toggle between views with keyboard shortcut M, W, D
• Filter by platform — show/hide specific platforms
• Quick add — click an empty slot to open the composer for that time

Analytics

Track content performance across all connected platforms with detailed charts and exportable reports.

Available Metrics

Analytics are fetched automatically on a daily schedule via the queue. You can also trigger a manual sync from Analytics → Sync Now.

Inbox & Replies

The unified inbox aggregates comments, direct messages, and mentions from all connected platforms into a single stream.

Inbox Features

• Unified stream — all platforms in one inbox, sortable by date or platform
• Sentiment analysis — AI-powered positive / neutral / negative classification
• Reply templates — save and reuse common responses
• Read / Resolved states — mark messages as handled
• Filters — filter by platform, sentiment, or unread status
• Notifications — real-time browser notifications for new messages

Social Listening

Monitor keywords, brand mentions, and competitor activity across platforms without manual searching.

Setting Up Keywords

1. Navigate to Listening → Keywords
2. Click Add Keyword and enter your term (e.g. your brand name)
3. Select which platforms to monitor
4. Set a sentiment alert threshold if desired
5. Save — SocialForge begins monitoring immediately

Keyword Ideas

• Your brand name and common misspellings
• Your product names
• Industry hashtags
• Competitor names (for competitive intelligence)

A/B Testing

Test two variations of a post to discover which performs better. SocialForge uses AI to analyse results and recommend a winner.

Running an A/B Test

1. Open the Compose screen and click A/B Test
2. Write Variation A (your control post)
3. Click + Add Variation B and write an alternative caption or use different media
4. Set the test duration (24 hours recommended)
5. Schedule both posts — SocialForge publishes them simultaneously
6. After the test period, view results under Analytics → A/B Tests
7. The AI analysis explains which variation won and why

Team Members

Invite collaborators to manage social accounts with role-based access control.

Available Roles

Inviting a Team Member

1. Go to Settings → Team Members
2. Click Invite Member
3. Enter their email address and select a role
4. They receive an invitation email with a sign-up link

Account Management

Manage all connected social media accounts from Settings → Social Accounts.

Connecting an Account

1. Navigate to Settings → Social Accounts
2. Click Connect Account and choose a platform
3. You will be redirected to the platform's OAuth page
4. Grant the required permissions and you will be redirected back
5. The account now appears in your account list

Token Refresh

Social tokens expire periodically. SocialForge automatically refreshes tokens in the background. If a token cannot be refreshed, you will receive an email notification and an in-app warning. Simply reconnect the account to resolve it.

File Structure

SocialForge follows standard Laravel conventions. Key directories and their purposes:

socialforge/
├── app/
│   ├── Http/
│   │   ├── Controllers/     # HTTP request handlers (thin — logic in Services)
│   │   └── Middleware/      # Request middleware (auth, 2FA, license check)
│   ├── Livewire/            # Real-time Livewire components
│   ├── Models/              # Eloquent database models
│   ├── Services/            # Business logic services
│   │   ├── Social/          # Per-platform posting services
│   │   ├── AI/              # AI caption & image generation
│   │   └── Media/           # Upload, thumbnail, storage services
│   ├── Jobs/                # Queued jobs (posting, analytics sync, AI)
│   ├── Enums/               # PHP 8.1 enums (Platform, PostStatus, etc.)
│   └── Notifications/       # Email & database notifications
├── config/                  # Application configuration files
├── database/
│   ├── migrations/          # Database schema files (run in order)
│   └── seeders/             # Optional demo data seeders
├── install/                 # Web installer wizard (delete after install)
├── public/                  # Web root — point your domain here
│   ├── storage/             # Symlink to storage/app/public/
│   └── build/               # Compiled Vite CSS & JS assets
├── resources/
│   ├── views/               # Blade template files
│   │   ├── livewire/        # Livewire component views
│   │   ├── components/      # Reusable Blade components
│   │   └── emails/          # Email notification templates
│   ├── css/                 # Source CSS (Tailwind)
│   └── js/                  # Source JavaScript (Alpine.js)
├── routes/
│   ├── web.php              # Web routes (dashboard, auth, social)
│   └── api.php              # API routes (webhooks, license)
├── storage/
│   ├── app/public/          # User uploaded files (images, videos)
│   ├── framework/           # Framework cache (sessions, views, cache)
│   └── logs/                # Application log files
├── .env                     # Environment configuration (never commit!)
├── .env.example             # Environment template
└── artisan                  # Laravel CLI tool

Customization Guide

1. Changing the Color Scheme

Edit resources/css/app.css to change the primary color used throughout the UI:

/* resources/css/app.css */
:root {
    --color-primary: #1d4ed8;       /* Primary blue */
    --color-sidebar: #1b2a4a;       /* Sidebar background */
    --color-accent:  #f5a623;       /* Amber accent (buttons) */
}

After editing, recompile assets with:

npm run build

2. Adding a New Social Platform

1. Add the platform to the Platform enum in app/Enums/Platform.php
2. Create an OAuth controller in app/Http/Controllers/SocialAuth/ following the existing pattern
3. Create a posting service in app/Services/Social/
4. Add the OAuth callback route to routes/web.php
5. Add the platform logo/icon to resources/views/components/sf-icon.blade.php
6. Add API credentials to .env

3. Modifying Email Templates

All email templates are Blade files located in resources/views/emails/. They use the standard Laravel Markdown mail format and can be edited freely.

4. Adding Custom Dashboard Widgets

Create a new Livewire component and register it on the dashboard:

php artisan make:livewire Dashboard/MyCustomWidget

Then include it in resources/views/livewire/dashboard/dashboard-home.blade.php:

@livewire('dashboard.my-custom-widget')

Upgrade Guide

Follow these steps to safely upgrade to a new version of SocialForge.

1. 1
   Back Up Your Database

   Copy

   mysqldump -u root -p socialforge > backup_$(date +%Y%m%d).sql

2. 2
   Back Up Your .env File

   Copy your .env file to a safe location before overwriting any files.

3. 3
   Upload New Files

   Download the new version zip and upload to your server. Overwrite all files except:

   • .env — keep your existing environment file
   • storage/ — keep your uploaded media files
4. 4
   Run Migrations

   Copy

   php artisan migrate --force

5. 5
   Clear All Caches

   Copy

   php artisan config:clear
   php artisan cache:clear
   php artisan view:clear
   php artisan optimize

Frequently Asked Questions

Changelog

Getting Support

We're here to help. Before opening a ticket, please check the FAQ and confirm you're running the latest version.

Response Times

What Support Covers

• ✓ Installation assistance
• ✓ Configuration and setup help
• ✓ Bug reports and confirmed fixes
• ✓ General usage questions

What Support Does Not Cover

• ✗ Custom development or code modifications
• ✗ Third-party API issues (Facebook, Twitter, etc.)
• ✗ Server configuration and hosting environment setup
• ✗ Data migration from other platforms