Installation Guide

This guide covers installing Traffic Exchange Script on both shared hosting (cPanel) and a VPS. Follow the section that matches your hosting environment.

---

Part A — Shared Hosting (cPanel)

Step 1: Create a MySQL Database

1. Log in to your cPanel account.
2. Navigate to MySQL Databases (or MySQL Database Wizard).
3. Create a new database — e.g. youraccount_te.
4. Create a new database user — e.g. youraccount_teuser — with a strong password.
5. Add the user to the database and grant All Privileges.
6. Note the database name, username, and password — you will need them in Step 4.

Note: On cPanel, your database and username will be prefixed with your cPanel account name (e.g. johnsmith_te). Make sure to use the full prefixed names.

Step 2: Upload the Script Files

Option A — File Manager: 1. In cPanel, open File Manager. 2. Navigate to your domain’s web root (typically public_html or a subdirectory if you’re installing on a subdomain). 3. Click Upload and upload the script .zip file. 4. Right-click the uploaded archive and select Extract.

Option B — FTP: 1. Connect to your server using an FTP client (FileZilla is recommended). 2. Upload the extracted script files to your domain’s web root.

Step 3: Set the Document Root to /public

The script’s web-accessible entry point is the /public directory. You need to point your domain’s document root there.

In cPanel: 1. Go to Domains (or Addon Domains / Subdomains). 2. Find your domain and click Manage. 3. Change the document root to public_html/public (or wherever you uploaded, plus /public).

If your host does not allow changing the document root, you can alternatively: – Move the contents of /public up one level, and update index.php to adjust the paths — contact support for assistance with this approach.

Step 4: Configure the .env File

1. In File Manager, navigate to your script’s root directory (the folder containing artisan).
2. Find .env.example and copy it to .env (do not rename — keep the original too).
3. Open .env and fill in at minimum these values:

APP_NAME="My Traffic Exchange"
APP_URL=https://yourdomain.com
APP_KEY=                        # Leave blank — generated in Step 5

DB_HOST=127.0.0.1
DB_DATABASE=youraccount_te
DB_USERNAME=youraccount_teuser
DB_PASSWORD=yourpassword

TE_APP_NAME="My Traffic Exchange"
TE_LICENSE_KEY=your-license-key-here
TE_SUPPORT_EMAIL=support@yourdomain.com
TE_HOSTING_MODE=shared

Important: Set TE_HOSTING_MODE=shared for cPanel hosting. This disables Redis, Reverb, and Meilisearch and uses file-based fallbacks.

Step 5: Run the Installer

The script uses a Laravel-based installer. You need to run several artisan commands via cPanel’s Terminal (if available) or via SSH.

If your host provides a Terminal in cPanel:

1. Open the Terminal.
2. Navigate to your script root: cd ~/public_html (adjust path as needed).
3. Run the following commands in order:

php artisan key:generate
php artisan migrate --seed
php artisan storage:link

• key:generate — generates and saves APP_KEY in your .env
• migrate --seed — creates all database tables and seeds default data
• storage:link — creates the public symlink for file uploads

If SSH access is available:

ssh youraccount@yourserver.com
cd ~/public_html
php artisan key:generate
php artisan migrate --seed
php artisan storage:link

Migrations failing? Double-check your DB_* credentials in .env. Ensure the database user has full privileges on the database.

Step 6: Set Up the Cron Job

The script requires a cron job to run scheduled tasks (newsletter dispatch, subscription renewals, badge evaluation, etc.).

1. In cPanel, go to Cron Jobs.
2. Set the frequency to Every Minute.
3. Enter this command (adjust the path to match your installation):

* * * * * cd /home/youraccount/public_html && php artisan schedule:run >> /dev/null 2>&1

This single cron entry handles all scheduled tasks. See Scheduled Tasks Reference for the full list of what runs and when.

Step 7: First Login

1. Visit https://yourdomain.com/admin in your browser.
2. You will be prompted to create an admin account on first run.
3. Set a strong password and note your credentials.

Your site is now installed. Continue to Admin Setup to configure it.

---

Part B — VPS Installation

This guide assumes a clean Ubuntu 22.04 or Debian 12 server with root access.

Step 1: Install Server Dependencies

# Update packages
apt update && apt upgrade -y

# Install PHP 8.3 and extensions
apt install -y software-properties-common
add-apt-repository ppa:ondrej/php   # Ubuntu only
apt install -y php8.3-fpm php8.3-mysql php8.3-bcmath php8.3-exif 
    php8.3-gd php8.3-intl php8.3-mbstring php8.3-zip php8.3-redis 
    php8.3-curl php8.3-xml

# Install MySQL 8.0
apt install -y mysql-server
mysql_secure_installation

# Install Nginx
apt install -y nginx

# Install Composer
curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

# Install Node.js (for asset compilation, if needed)
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs

# Install Redis
apt install -y redis-server
systemctl enable redis-server
systemctl start redis-server

Step 2: Create a Database

mysql -u root -p

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

Step 3: Upload the Script

Upload your script files to the server. A common location is /var/www/yourdomain.com:

mkdir -p /var/www/yourdomain.com
# Upload via SFTP/SCP, then extract
cd /var/www/yourdomain.com
unzip traffic-exchange-script.zip

Set correct ownership:

chown -R www-data:www-data /var/www/yourdomain.com
chmod -R 755 /var/www/yourdomain.com
chmod -R 775 /var/www/yourdomain.com/storage
chmod -R 775 /var/www/yourdomain.com/bootstrap/cache

Step 4: Configure .env

cd /var/www/yourdomain.com
cp .env.example .env
nano .env

Set these values at minimum:

APP_NAME="My Traffic Exchange"
APP_URL=https://yourdomain.com
APP_ENV=production
APP_DEBUG=false

DB_HOST=127.0.0.1
DB_DATABASE=traffic_exchange
DB_USERNAME=te_user
DB_PASSWORD=strongpassword

SESSION_DRIVER=redis
CACHE_STORE=redis
QUEUE_CONNECTION=redis

REDIS_HOST=127.0.0.1
REDIS_PORT=6379

TE_APP_NAME="My Traffic Exchange"
TE_LICENSE_KEY=your-license-key-here
TE_SUPPORT_EMAIL=support@yourdomain.com
TE_HOSTING_MODE=vps

Step 5: Install PHP Dependencies and Run Migrations

cd /var/www/yourdomain.com
composer install --no-dev --optimize-autoloader
php artisan key:generate
php artisan migrate --seed
php artisan storage:link
php artisan config:cache
php artisan route:cache
php artisan view:cache

Step 6: Generate VAPID Keys (Web Push)

If you want web push notifications:

php artisan te:generate-vapid-keys

This writes VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY to your .env.

Step 7: Update GeoIP Database

The anti-cheat system uses MaxMind GeoLite2 for location lookups:

php artisan te:update-geoip

Step 8: Configure Nginx

Create a site configuration:

nano /etc/nginx/sites-available/yourdomain.com

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    root /var/www/yourdomain.com/public;

    index index.php;

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

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

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

ln -s /etc/nginx/sites-available/yourdomain.com /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

After adding SSL (see Going Live Checklist), Nginx will handle HTTPS automatically.

Step 9: Set Up Queue Workers with Supervisor

The script uses Laravel queues for background processing (emails, commissions, etc.).

apt install -y supervisor
nano /etc/supervisor/conf.d/te-worker.conf

[program:te-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/yourdomain.com/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/yourdomain.com/storage/logs/worker.log
stopwaitsecs=3600

supervisorctl reread
supervisorctl update
supervisorctl start te-worker:*

Step 10: Set Up the Laravel Scheduler (System Cron)

crontab -e -u www-data

Add this line:

* * * * * cd /var/www/yourdomain.com && php artisan schedule:run >> /dev/null 2>&1

Step 11 (Optional): Laravel Reverb WebSocket Server

For real-time surf timers and notifications (VPS only):

1. Configure Reverb in .env:

BROADCAST_CONNECTION=reverb
REVERB_APP_ID=your-app-id
REVERB_APP_KEY=your-app-key
REVERB_APP_SECRET=your-app-secret
REVERB_HOST=yourdomain.com
REVERB_PORT=8080
REVERB_SCHEME=https

1. Add a Supervisor entry for Reverb:

[program:te-reverb]
command=php /var/www/yourdomain.com/artisan reverb:start --host=0.0.0.0 --port=8080
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/yourdomain.com/storage/logs/reverb.log

1. Add a Nginx proxy block for WebSocket traffic on port 8080.

Step 12: First Login

Visit https://yourdomain.com/admin and create your admin account.

Continue to Admin Setup.

---

Troubleshooting

Problem	Solution
Blank white page	Check storage/logs/laravel.log. Usually a missing APP_KEY or wrong file permissions.
APP_KEY error	Run php artisan key:generate
Migrations failed	Verify DB_* credentials in .env. Ensure the DB user has ALL PRIVILEGES.
License validation failed	Check TE_LICENSE_KEY in .env. Ensure your server can make outbound HTTPS requests.
500 error after install	Run php artisan config:clear and check file permissions on storage/ and bootstrap/cache/.

See Installation FAQ for more common issues.

Screenshots