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

```bash
# 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

```bash
# 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

```bash
# 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

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

Key settings to update:
```ini
# 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
```

```bash
# 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

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

# Secure MySQL installation
sudo mysql_secure_installation
```

### UTF8MB4 Configuration & Performance Tuning

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

Add/update these settings:
```ini
[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

```bash
# 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;
```

```bash
# 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

```bash
# 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

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

Key settings:
```ini
# 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
```

```bash
# 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)

```bash
# 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

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

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

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

```yaml
# 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
```

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

```ini
[Service]
LimitMEMLOCK=infinity
```

```bash
# 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

```bash
# Install Nginx
sudo apt install -y nginx

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

### Create Timebank.cc Site Configuration

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

```nginx
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)

```bash
# 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

```bash
# 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

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

```apache
<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>
```

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)

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

Configure the following key settings:
```env
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

### Queue Worker Configuration

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

```ini
[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

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

```ini
[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

```bash
# 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

```bash
# 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

```bash
# 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)

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

### Production Optimizations

```bash
# 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
```

```bash
#!/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"
```

```bash
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:

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

```ini
[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
```

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

```ini
[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
```

```bash
# 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:

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

```bash
#!/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 ==="
```

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

# Run health check
timebank-health-check
```

### Monitoring & Log Management

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Check Elasticsearch status
sudo systemctl status elasticsearch

# Check Elasticsearch logs
sudo journalctl -u elasticsearch -f

# Restart Elasticsearch
sudo systemctl restart elasticsearch
```

#### Issue: Permission errors
```bash
# 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

```bash
# 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

```bash
# 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

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

# Clear Laravel caches
php artisan optimize:clear
```

#### Step 3: Database Operations

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:**
```bash
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:**
```bash
php -d memory_limit=2G /usr/local/bin/composer install
```

**NPM Build Failures:**
```bash
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
npm run build
```

**Elasticsearch Index Issues:**
```bash
# Check Elasticsearch health
curl localhost:9200/_cluster/health?pretty

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

**Queue Worker Not Processing:**
```bash
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.