timebank-cc-public/references/SETUP_GUIDE.md

Timebank.cc - Complete Debian Linux Server Setup Guide

This guide provides step-by-step instructions for setting up the Timebank.cc application on a Debian-based Linux server, including all external services and dependencies.

---

PART 1: SYSTEM PREPARATION

System Updates & Essential Packages

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install essential build tools and utilities
sudo apt install -y curl wget git unzip software-properties-common \
    apt-transport-https ca-certificates gnupg lsb-release \
    build-essential supervisor ufw

User Account Setup

# Create application user (optional, for security)
sudo adduser timebank
sudo usermod -aG www-data timebank
sudo usermod -aG sudo timebank  # Only if needed for deployment

---

PART 2: PHP INSTALLATION & CONFIGURATION

PHP 8.3+ Installation with All Required Extensions

# Add PHP repository (if needed for latest versions)
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update

# Install PHP 8.3 and required extensions
sudo apt install -y \
    php8.3-fpm php8.3-cli php8.3-common \
    php8.3-mysql \
    php8.3-redis \
    php8.3-gd php8.3-imagick \
    php8.3-mbstring php8.3-xml php8.3-zip \
    php8.3-bcmath php8.3-intl \
    php8.3-curl \
    php8.3-imap

# Verify PHP installation
php -v
php -m | grep -E "(redis|mysql|gd|bcmath|intl)"

PHP-FPM Configuration

# Edit PHP-FPM configuration
sudo nano /etc/php/8.3/fpm/php.ini

Key settings to update:

# Memory and execution limits
memory_limit = 256M
max_execution_time = 300
max_input_time = 300
post_max_size = 64M
upload_max_filesize = 12M

# OPcache (Production optimization)
opcache.enable=1
opcache.memory_consumption=128
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=4000
opcache.revalidate_freq=2
opcache.validate_timestamps=1
# Note: For maximum performance in production, set opcache.validate_timestamps=0
# This requires manual cache clearing after code updates: php artisan opcache:clear

# Restart PHP-FPM
sudo systemctl restart php8.3-fpm
sudo systemctl enable php8.3-fpm

---

PART 3: DATABASE SETUP (MySQL 8.0+)

MySQL Server Installation

# Install MySQL 8.0+
sudo apt install -y mysql-server mysql-client

# Secure MySQL installation
sudo mysql_secure_installation

UTF8MB4 Configuration & Performance Tuning

# Edit MySQL configuration
sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

Add/update these settings:

[mysqld]
# Character set configuration
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci

# Performance settings
max_allowed_packet = 64M
innodb_buffer_pool_size = 1G
innodb_log_file_size = 256M

# Window functions support (verify MySQL 8.0+)
sql_mode = STRICT_TRANS_TABLES,NO_ZERO_DATE,NO_ZERO_IN_DATE,ERROR_FOR_DIVISION_BY_ZERO

Database User & Permissions Setup

# Login to MySQL as root
sudo mysql

# Create database
CREATE DATABASE timebank_cc CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# Create application user with transaction immutability enforcement
CREATE USER 'timebank_user'@'localhost' IDENTIFIED BY 'secure_password_here';

# Grant full privileges on all tables
GRANT SELECT, INSERT, UPDATE, DELETE ON timebank_cc.* TO 'timebank_user'@'localhost';

# Restrict transactions table to enforce immutability (no UPDATE or DELETE)
REVOKE UPDATE, DELETE ON timebank_cc.transactions FROM 'timebank_user'@'localhost';

FLUSH PRIVILEGES;
EXIT;

# Restart MySQL
sudo systemctl restart mysql
sudo systemctl enable mysql

# Verify window functions support (MySQL 8.0+ feature)
mysql -u timebank_user -p -e "SELECT VERSION(); SHOW VARIABLES LIKE 'sql_mode';"

---

PART 4: REDIS CACHE & SESSION STORAGE

Redis Server Installation

# Install Redis from official repository
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list

sudo apt update
sudo apt install -y redis-server

Redis Configuration for Cache/Sessions/Queues

# Edit Redis configuration
sudo nano /etc/redis/redis.conf

Key settings:

# Memory management
maxmemory 512mb
maxmemory-policy allkeys-lru

# Persistence (for sessions and queues)
save 900 1
save 300 10
save 60 10000

# Security
bind 127.0.0.1 ::1
protected-mode yes
requirepass your_redis_password_here

# Multiple databases for different purposes
databases 16

# Restart and enable Redis
sudo systemctl restart redis-server
sudo systemctl enable redis-server

# Test Redis connection
redis-cli ping

---

PART 5: ELASTICSEARCH SEARCH SERVICE

Elasticsearch Installation (7.x/8.x)

# Import Elasticsearch signing key
curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg

# Add Elasticsearch repository
echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/8.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-8.x.list

sudo apt update
sudo apt install -y elasticsearch

JVM Memory Configuration & Multi-language Setup

# Configure JVM memory (minimum 2GB for production)
sudo nano /etc/elasticsearch/jvm.options.d/heap.options

# Set heap size (50% of available RAM, min 2GB)
-Xms2g
-Xmx2g

# Configure Elasticsearch
sudo nano /etc/elasticsearch/elasticsearch.yml

# Basic configuration
cluster.name: timebank-search
node.name: timebank-node-1
network.host: localhost
http.port: 9200

# Security (for production)
xpack.security.enabled: false  # Set to true for production with proper auth

# Memory and performance
bootstrap.memory_lock: true

# Enable memory locking
sudo nano /etc/systemd/system/elasticsearch.service.d/override.conf

[Service]
LimitMEMLOCK=infinity

# Start and enable Elasticsearch
sudo systemctl daemon-reload
sudo systemctl enable elasticsearch
sudo systemctl start elasticsearch

# Verify Elasticsearch is running
curl -X GET "localhost:9200/"

---

PART 6A: WEB SERVER - NGINX OPTION

Nginx Installation & Configuration

# Install Nginx
sudo apt install -y nginx

# Remove default configuration
sudo rm /etc/nginx/sites-enabled/default

Create Timebank.cc Site Configuration

# Create new site configuration
sudo nano /etc/nginx/sites-available/timebank.cc

server {
    listen 80;
    listen [::]:80;
    server_name your-domain.com www.your-domain.com;
    root /var/www/timebank.cc/public;
    index index.php index.html;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # Handle Laravel routes
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # PHP processing
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # WebSocket proxy for Laravel Reverb (port 8080)
    location /reverb/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Static assets optimization
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Security: deny access to sensitive files
    location ~ /\. {
        deny all;
    }
}

SSL Configuration (Production)

# Install Certbot for Let's Encrypt
sudo apt install -y certbot python3-certbot-nginx

# Enable site and restart Nginx
sudo ln -s /etc/nginx/sites-available/timebank.cc /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
sudo systemctl enable nginx

# Generate SSL certificate (replace with your domain)
sudo certbot --nginx -d your-domain.com -d www.your-domain.com

---

PART 6B: WEB SERVER - APACHE2 OPTION

Apache2 Installation & Modules

# Install Apache2 and required modules
sudo apt install -y apache2 libapache2-mod-php8.3

# Enable required modules
sudo a2enmod rewrite ssl headers proxy proxy_http proxy_wstunnel
sudo systemctl restart apache2

Create Timebank.cc Virtual Host

# Create new virtual host
sudo nano /etc/apache2/sites-available/timebank.cc.conf

<VirtualHost *:80>
    ServerName your-domain.com
    ServerAlias www.your-domain.com
    DocumentRoot /var/www/timebank.cc/public

    <Directory /var/www/timebank.cc/public>
        AllowOverride All
        Require all granted
    </Directory>

    # Security headers
    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set X-Content-Type-Options "nosniff"
    Header always set X-XSS-Protection "1; mode=block"

    # WebSocket proxy for Laravel Reverb
    ProxyPass /reverb/ ws://127.0.0.1:8080/
    ProxyPassReverse /reverb/ ws://127.0.0.1:8080/

    ErrorLog ${APACHE_LOG_DIR}/timebank_error.log
    CustomLog ${APACHE_LOG_DIR}/timebank_access.log combined
</VirtualHost>

# SSL Virtual Host (add after SSL certificate generation)
<IfModule mod_ssl.c>
<VirtualHost *:443>
    ServerName your-domain.com
    ServerAlias www.your-domain.com
    DocumentRoot /var/www/timebank.cc/public

    SSLEngine on
    SSLCertificateFile /path/to/certificate.crt
    SSLCertificateKeyFile /path/to/private.key

    <Directory /var/www/timebank.cc/public>
        AllowOverride All
        Require all granted
    </Directory>

    # Same configuration as HTTP virtual host
    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set X-Content-Type-Options "nosniff"
    Header always set X-XSS-Protection "1; mode=block"

    ProxyPass /reverb/ ws://127.0.0.1:8080/
    ProxyPassReverse /reverb/ ws://127.0.0.1:8080/
</VirtualHost>
</IfModule>

# Enable site and restart Apache
sudo a2ensite timebank.cc.conf
sudo a2dissite 000-default.conf
sudo systemctl restart apache2
sudo systemctl enable apache2

# Generate SSL certificate
sudo apt install -y certbot python3-certbot-apache
sudo certbot --apache -d your-domain.com -d www.your-domain.com

---

PART 7: FRONTEND BUILD ENVIRONMENT

Node.js 16+ LTS Installation

# Install Node.js from NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

# Verify installation
node --version
npm --version

# Update npm to latest version
sudo npm install -g npm@latest

Build Tools Setup

# Install global build tools (optional)
sudo npm install -g yarn

# Set npm registry (optional, for faster installs)
npm config set registry https://registry.npmjs.org/

---

PART 8: LARAVEL APPLICATION DEPLOYMENT

Composer Installation

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

# Verify Composer
composer --version

Project Clone & File Permissions

# Create web directory
sudo mkdir -p /var/www/timebank.cc
sudo chown -R www-data:www-data /var/www/timebank.cc

# Clone project (replace with your repository)
cd /var/www
sudo git clone https://github.com/your-repo/timebank.cc.git
sudo chown -R www-data:www-data timebank.cc

# Set proper permissions
sudo find /var/www/timebank.cc -type f -exec chmod 644 {} \;
sudo find /var/www/timebank.cc -type d -exec chmod 755 {} \;
sudo chmod -R 775 /var/www/timebank.cc/storage
sudo chmod -R 775 /var/www/timebank.cc/bootstrap/cache

Environment Configuration (.env)

# Copy environment file
cd /var/www/timebank.cc
sudo cp .env.example .env
sudo nano .env

Configure the following key settings:

APP_NAME="Timebank.cc"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://your-domain.com

# Theme Configuration
TIMEBANK_THEME=timebank_cc   # Options: timebank_cc, uuro, vegetable, yellow

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=timebank_cc
DB_USERNAME=timebank_user
DB_PASSWORD=secure_password_here

CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=your_redis_password_here
REDIS_PORT=6379
REDIS_CACHE_DB=1

ELASTICSEARCH_HOST=localhost:9200
SCOUT_DRIVER=matchish-elasticsearch

BROADCAST_DRIVER=reverb
PUSHER_APP_ID=timebank-app
PUSHER_APP_KEY=timebank-key
PUSHER_APP_SECRET=timebank-secret
PUSHER_HOST=your-domain.com
PUSHER_PORT=8080
PUSHER_SCHEME=https

MAIL_MAILER=smtp
MAIL_HOST=your-smtp-host
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@your-domain.com

Dependencies Installation

# Install PHP dependencies
cd /var/www/timebank.cc

# For production (recommended)
sudo -u www-data composer install --optimize-autoloader --no-dev

# For development (includes testing tools and Faker for test data generation)
# sudo -u www-data composer install --optimize-autoloader

# Generate application key
sudo -u www-data php artisan key:generate

# Create symbolic link for storage
sudo -u www-data php artisan storage:link

Database Migration & Seeding

# Run database migrations
sudo -u www-data php artisan migrate

# Seed database with initial data (required for application setup)
sudo -u www-data php artisan db:seed

# Verify database setup
sudo -u www-data php artisan tinker
# In tinker: User::count(); (should return number of users)
# Exit with: exit

Elasticsearch Indexing

# Import all models to Elasticsearch
sudo -u www-data php artisan scout:import "App\Models\User"
sudo -u www-data php artisan scout:import "App\Models\Organization"
sudo -u www-data php artisan scout:import "App\Models\Bank"
sudo -u www-data php artisan scout:import "App\Models\Post"

# Verify Elasticsearch indices
curl -X GET "localhost:9200/_cat/indices?v"

Frontend Asset Compilation

# Install Node.js dependencies
cd /var/www/timebank.cc
sudo -u www-data npm install

# Build production assets
sudo -u www-data npm run build

# Verify assets are compiled
ls -la public/build/

---

PART 9: PRODUCTION SERVICES & PROCESS MANAGEMENT

Supervisor Installation & Configuration

# Supervisor should already be installed from Part 1
sudo systemctl enable supervisor
sudo systemctl start supervisor

Queue Worker Configuration

# Create queue worker configuration
sudo nano /etc/supervisor/conf.d/timebank-queue.conf

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

WebSocket Server (Laravel Reverb) Setup

# Create Reverb WebSocket server configuration
sudo nano /etc/supervisor/conf.d/timebank-reverb.conf

[program:timebank-reverb]
process_name=%(program_name)s
command=php /var/www/timebank.cc/artisan reverb:start --host=0.0.0.0 --port=8080
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/timebank.cc/storage/logs/reverb.log

Process Monitoring & Auto-restart

# Update supervisor configuration
sudo supervisorctl reread
sudo supervisorctl update

# Start all processes
sudo supervisorctl start timebank-queue:*
sudo supervisorctl start timebank-reverb:*

# Check process status
sudo supervisorctl status

---

PART 10: SECURITY & OPTIMIZATION

File Permissions & Ownership

# Set proper ownership
sudo chown -R www-data:www-data /var/www/timebank.cc

# Set secure permissions
sudo find /var/www/timebank.cc -type f -exec chmod 644 {} \;
sudo find /var/www/timebank.cc -type d -exec chmod 755 {} \;

# Storage and cache directories need write permissions
sudo chmod -R 775 /var/www/timebank.cc/storage
sudo chmod -R 775 /var/www/timebank.cc/bootstrap/cache

# Protect sensitive files
sudo chmod 600 /var/www/timebank.cc/.env

Firewall Configuration

# Enable UFW firewall
sudo ufw --force reset
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Allow essential services
sudo ufw allow ssh
sudo ufw allow 'Nginx Full'  # or 'Apache Full' if using Apache
sudo ufw allow 8080/tcp      # WebSocket server

# Enable firewall
sudo ufw --force enable
sudo ufw status

SSL Certificate Setup (if not done in web server section)

# Let's Encrypt certificate (already covered in web server sections)
# Verify auto-renewal
sudo certbot renew --dry-run

Production Optimizations

# Laravel optimizations
cd /var/www/timebank.cc
sudo -u www-data php artisan config:cache
sudo -u www-data php artisan route:cache
sudo -u www-data php artisan view:cache

# Create optimization script for regular maintenance
sudo nano /usr/local/bin/timebank-optimize

#!/bin/bash
cd /var/www/timebank.cc
sudo -u www-data php artisan config:cache
sudo -u www-data php artisan route:cache
sudo -u www-data php artisan view:cache
sudo -u www-data php artisan queue:restart
echo "Timebank.cc optimization complete"

sudo chmod +x /usr/local/bin/timebank-optimize

---

PART 11: SERVICE MANAGEMENT & HEALTH CHECKS

Systemd Service Files (Alternative to Supervisor)

If you prefer systemd over supervisor, create these service files:

# Queue worker service
sudo nano /etc/systemd/system/timebank-queue.service

[Unit]
Description=Timebank.cc Queue Worker
After=redis-server.service mysql.service

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/timebank.cc/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

# WebSocket service
sudo nano /etc/systemd/system/timebank-reverb.service

[Unit]
Description=Timebank.cc WebSocket Server
After=redis-server.service

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/timebank.cc/artisan reverb:start --host=0.0.0.0 --port=8080
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

# Enable and start services
sudo systemctl daemon-reload
sudo systemctl enable timebank-queue.service
sudo systemctl enable timebank-reverb.service
sudo systemctl start timebank-queue.service
sudo systemctl start timebank-reverb.service

Health Check Commands

Create a health check script:

sudo nano /usr/local/bin/timebank-health-check

#!/bin/bash

echo "=== Timebank.cc Health Check ==="
echo "Date: $(date)"
echo

# Check web server
echo "1. Web Server:"
if systemctl is-active --quiet nginx; then
    echo "   ✓ Nginx is running"
elif systemctl is-active --quiet apache2; then
    echo "   ✓ Apache2 is running"
else
    echo "   ✗ Web server is not running"
fi

# Check PHP-FPM
echo "2. PHP-FPM:"
if systemctl is-active --quiet php8.3-fpm; then
    echo "   ✓ PHP-FPM is running"
else
    echo "   ✗ PHP-FPM is not running"
fi

# Check MySQL
echo "3. MySQL:"
if systemctl is-active --quiet mysql; then
    echo "   ✓ MySQL is running"
else
    echo "   ✗ MySQL is not running"
fi

# Check Redis
echo "4. Redis:"
if systemctl is-active --quiet redis-server; then
    echo "   ✓ Redis is running"
else
    echo "   ✗ Redis is not running"
fi

# Check Elasticsearch
echo "5. Elasticsearch:"
if curl -s localhost:9200 > /dev/null; then
    echo "   ✓ Elasticsearch is running"
else
    echo "   ✗ Elasticsearch is not responding"
fi

# Check Queue Workers
echo "6. Queue Workers:"
if sudo supervisorctl status timebank-queue: | grep -q RUNNING; then
    echo "   ✓ Queue workers are running"
else
    echo "   ✗ Queue workers are not running"
fi

# Check WebSocket Server
echo "7. WebSocket Server:"
if sudo supervisorctl status timebank-reverb: | grep -q RUNNING; then
    echo "   ✓ WebSocket server is running"
else
    echo "   ✗ WebSocket server is not running"
fi

# Check Laravel application
echo "8. Laravel Application:"
cd /var/www/timebank.cc
if sudo -u www-data php artisan inspire > /dev/null 2>&1; then
    echo "   ✓ Laravel application is accessible"
else
    echo "   ✗ Laravel application has issues"
fi

echo
echo "=== End Health Check ==="

sudo chmod +x /usr/local/bin/timebank-health-check

# Run health check
timebank-health-check

Monitoring & Log Management

# View application logs
sudo tail -f /var/www/timebank.cc/storage/logs/laravel.log

# View queue worker logs
sudo tail -f /var/www/timebank.cc/storage/logs/worker.log

# View WebSocket server logs
sudo tail -f /var/www/timebank.cc/storage/logs/reverb.log

# View web server logs (Nginx)
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log

# View web server logs (Apache)
sudo tail -f /var/log/apache2/timebank_access.log
sudo tail -f /var/log/apache2/timebank_error.log

Common Troubleshooting

Issue: Queue workers not processing jobs

# Restart queue workers
sudo supervisorctl restart timebank-queue:*

# Check queue status
cd /var/www/timebank.cc
sudo -u www-data php artisan queue:work --once --verbose

Issue: WebSocket connection failures

# Check if port 8080 is open
sudo netstat -tulpn | grep :8080

# Restart WebSocket server
sudo supervisorctl restart timebank-reverb:*

# Check WebSocket logs
sudo tail -f /var/www/timebank.cc/storage/logs/reverb.log

Issue: Elasticsearch not responding

# Check Elasticsearch status
sudo systemctl status elasticsearch

# Check Elasticsearch logs
sudo journalctl -u elasticsearch -f

# Restart Elasticsearch
sudo systemctl restart elasticsearch

Issue: Permission errors

# Fix Laravel permissions
sudo chown -R www-data:www-data /var/www/timebank.cc
sudo chmod -R 775 /var/www/timebank.cc/storage
sudo chmod -R 775 /var/www/timebank.cc/bootstrap/cache

---

PART 8: APPLICATION DEPLOYMENT

After completing the server setup, you need to deploy your Laravel application. Choose between automated deployment using the provided script or manual deployment.

Option A: Automated Deployment Using Deploy Script

The repository includes a comprehensive deployment script that handles the entire deployment process automatically.

Deploy Script Features

• Environment auto-detection (local vs. server)
• Git pull with conflict resolution
• Dependency installation (Composer + NPM)
• Database migrations with automatic backup
• Cache clearing and optimization
• Elasticsearch re-indexing
• Asset compilation (development or production mode)
• Permissions management
• Deployment status reporting

Using the Deploy Script

# Navigate to your application directory
cd /var/www/timebank.cc

# Make the deploy script executable
chmod +x deploy.sh

# Run deployment with default settings
./deploy.sh

# Deployment options:
./deploy.sh -m          # Skip migrations
./deploy.sh -n          # Skip NPM build
./deploy.sh -d          # Force development build (even on production)
./deploy.sh -e server   # Force server environment
./deploy.sh -e local    # Force local environment

# Combined options example:
./deploy.sh -n -e server  # Server deployment, skip NPM

Deploy Script Environment Detection

The script automatically detects the environment:

• Server Environment: Detected when hostname contains "dev", "prod", or "timebank"
• Local Environment: Default for other hostnames

What the Deploy Script Does

1. Pre-deployment Checks

   • Checks for uncommitted changes
   • Prompts for confirmation if changes exist

2. Code Updates

   • Pulls latest code from main branch
   • Handles merge conflicts with user interaction
   • Options to stash, discard, or cancel on conflicts

3. Dependencies

   • Runs composer install with production optimizations
   • Installs NPM dependencies
   • Builds assets (dev or production mode)

4. Database & Search

   • Creates database backup before migrations
   • Runs Laravel migrations
   • Links storage directories
   • Re-indexes Elasticsearch using re-index-search.sh

5. Optimization

   • Clears Laravel caches
   • Sets proper file permissions
   • Optimizes autoloader

6. Post-deployment

   • Reports deployment status
   • Shows environment information
   • Displays helpful URLs and versions

Option B: Manual Deployment Process

If you prefer manual control or need to customize the deployment process:

Step 1: Code Deployment

# Navigate to application directory
cd /var/www/timebank.cc

# Pull latest code
git pull origin main

# Handle any merge conflicts if they occur
# git stash  # if you need to stash local changes
# git pull origin main

Step 2: Backend Dependencies

# Install/update PHP dependencies
composer install --no-interaction --prefer-dist --optimize-autoloader

# Clear Laravel caches
php artisan optimize:clear

Step 3: Database Operations

# Create database backup (recommended)
DB_NAME=$(php artisan tinker --execute="echo config('database.connections.mysql.database');" | grep -v ">>>")
DB_USER=$(php artisan tinker --execute="echo config('database.connections.mysql.username');" | grep -v ">>>")
DB_PASS=$(php artisan tinker --execute="echo config('database.connections.mysql.password');" | grep -v ">>>")

# Create backup
mkdir -p storage/backups
mysqldump -u "$DB_USER" -p"$DB_PASS" "$DB_NAME" > "storage/backups/db-backup-$(date +'%Y-%m-%d-%H%M%S').sql"

# Run migrations
php artisan migrate

# Link storage (if not already linked)
php artisan storage:link

Step 4: Search Index Management

# Re-index Elasticsearch (this is resource intensive)
bash re-index-search.sh

# Alternative: Re-index specific models
# php artisan scout:flush "App\Models\User"
# php artisan scout:import "App\Models\User"
# php artisan scout:flush "App\Models\Post"  
# php artisan scout:import "App\Models\Post"
# php artisan scout:flush "App\Models\Organization"
# php artisan scout:import "App\Models\Organization"
# php artisan scout:flush "App\Models\Bank"
# php artisan scout:import "App\Models\Bank"

Step 5: Frontend Assets

# Install/update NPM dependencies
npm install

# Build assets for production
npm run build

# Alternative: Development build (starts dev server)
# npm run dev

Step 6: Permissions & Services

# Set proper permissions
sudo chown -R www-data:www-data storage bootstrap/cache public/storage public/build
sudo chmod -R 775 storage bootstrap/cache public/build

# Restart services to pick up changes
sudo supervisorctl restart timebank-queue:*
sudo supervisorctl restart timebank-reverb:*

# Restart web server (choose one)
sudo systemctl restart nginx
# sudo systemctl restart apache2

# Restart PHP-FPM
sudo systemctl restart php8.3-fpm

Deployment Verification

After either deployment method, verify the deployment:

# Check Laravel application status
php artisan inspire  # Should work without errors

# Check database connectivity
php artisan tinker
# In tinker: \App\Models\User::count()

# Verify search functionality
curl -X GET "localhost:9200/_cat/indices?v"  # Should show search indices

# Check queue functionality
php artisan queue:work --once --verbose

# Test web server response
curl -I http://localhost  # Should return 200 OK

Post-Deployment Tasks

1. Update Environment Variables: Check .env file for any new configuration options
2. SSL Certificate: Ensure SSL certificates are up to date for production
3. Monitor Logs: Check application logs for any errors after deployment
4. Performance: Monitor system resources after deployment
5. Backup: Ensure regular backup schedules are in place

Troubleshooting Deployment Issues

Common Deployment Problems

Permission Errors:

sudo chown -R www-data:www-data /var/www/timebank.cc
sudo chmod -R 775 /var/www/timebank.cc/storage
sudo chmod -R 775 /var/www/timebank.cc/bootstrap/cache

Composer Memory Issues:

php -d memory_limit=2G /usr/local/bin/composer install

NPM Build Failures:

rm -rf node_modules package-lock.json
npm cache clean --force
npm install
npm run build

Elasticsearch Index Issues:

# Check Elasticsearch health
curl localhost:9200/_cluster/health?pretty

# Clear and rebuild indices
bash re-index-search.sh

Queue Worker Not Processing:

sudo supervisorctl restart timebank-queue:*
php artisan queue:restart

---

FINAL VERIFICATION CHECKLIST

After completing the setup, verify everything is working:

• Web server responds to HTTP/HTTPS requests
• PHP processes Laravel requests correctly
• Database connections work (test login)
• Redis caching is functional
• Elasticsearch search returns results
• Queue workers process background jobs
• WebSocket server handles real-time connections
• SSL certificates are valid and auto-renewing
• All services start automatically on boot
• Health check script runs without errors
• File permissions are secure
• Firewall rules are properly configured

REFERENCE DOCUMENTS

This setup guide references the following documentation:

Core Documentation

• EXTERNAL_SERVICES_REQUIREMENTS.md - Complete service specifications
• CLAUDE.md - Development commands and architecture details
• SECURITY_OVERVIEW.md - Security best practices
• .env.example - Environment configuration template

Essential Setup Guides

• references/BOUNCE_SETUP.md - Required: Email bounce handling system setup for production environments
• references/BRANDING_CUSTOMIZATION.md - Complete guide for creating branded instances with custom themes, platform configurations, and content pages

Additional References

The references/ folder contains extensive documentation for various aspects of the application. Consult these guides for detailed information on customization, development patterns, and advanced features

---

Setup Complete! Your Timebank.cc application should now be fully functional on Debian Linux with all external services properly configured.