# GST Billing & POS SaaS Platform - Installation Guide

## Overview
This document provides step-by-step instructions for deploying the GST Billing & POS SaaS Platform on a live production server.

## System Requirements

### Server Requirements
- **Operating System**: Ubuntu 20.04 LTS or later / CentOS 8 or later / Windows Server 2019+
- **Web Server**: Nginx 1.18+ or Apache 2.4+
- **PHP**: PHP 8.2+ with required extensions
- **Database**: MySQL 8.0+ or MariaDB 10.5+ (SQLite for development only)
- **Memory**: Minimum 2GB RAM (4GB+ recommended)
- **Storage**: Minimum 10GB SSD storage
- **Composer**: PHP Dependency Manager 2.0+

### Required PHP Extensions
- bcmath
- ctype
- curl
- fileinfo
- json
- mbstring
- openssl
- pdo
- pdo_mysql
- tokenizer
- xml
- zip
- gd (for image processing)
- zip

## Installation Steps

### 1. Server Preparation

#### Update System Packages
```bash
# Ubuntu/Debian
sudo apt update && sudo apt upgrade -y

# CentOS/RHEL
sudo yum update -y
```

#### Install Required Dependencies
```bash
# Ubuntu/Debian
sudo apt install -y nginx mariadb-server php8.2-fpm php8.2-mysql \
    php8.2-xml php8.2-mbstring php8.2-bcmath php8.2-curl \
    php8.2-zip php8.2-gd php8.2-tokenizer unzip git curl

# CentOS/RHEL
sudo yum install -y nginx mariadb-server php php-fpm php-mysqlnd \
    php-xml php-mbstring php-bcmath php-curl php-zip php-gd \
    php-tokenizer unzip git curl
```

#### Enable and Start Services
```bash
sudo systemctl enable nginx mariadb php8.2-fpm
sudo systemctl start nginx mariadb php8.2-fpm
```

### 2. Database Setup

#### Create Database and User
```sql
MariaDB [(none)]> CREATE DATABASE gst_billing_pos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
MariaDB [(none)]> CREATE USER 'gstbilling'@'localhost' IDENTIFIED BY 'your_strong_password_here';
MariaDB [(none)]> GRANT ALL PRIVILEGES ON gst_billing_pos.* TO 'gstbilling'@'localhost';
MariaDB [(none)]> FLUSH PRIVILEGES;
MariaDB [(none)]> EXIT;
```

### 3. Application Deployment

#### Clone/Upload Application
```bash
# Option 1: Clone from repository
cd /var/www/
sudo git clone https://your-repository-url.git gst_billing_pos
sudo chown -R www-data:www-data gst_billing_pos
sudo chmod -R 755 gst_billing_pos

# Option 2: Upload via FTP/SFTP
# Upload the application files to /var/www/gst_billing_pos
```

#### Install PHP Dependencies
```bash
cd /var/www/gst_billing_pos/backend
sudo -u www-data composer install --no-dev --optimize-autoloader
```

#### Set Proper Permissions
```bash
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache
```

### 4. Environment Configuration

#### Copy Environment File
```bash
cp .env.example .env
```

#### Generate Application Key
```bash
sudo -u www-data php artisan key:generate
```

#### Configure .env File
Edit the `.env` file to match your production environment:
```env
APP_NAME="GST Billing & POS"
APP_ENV=production
APP_KEY=base64:your_generated_key_here
APP_DEBUG=false
APP_URL=https://yourdomain.com

LOG_CHANNEL=stack
LOG_LEVEL=warning

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=gst_billing_pos
DB_USERNAME=gstbilling
DB_PASSWORD=your_strong_password_here

BROADCAST_DRIVER=log
CACHE_DRIVER=file
QUEUE_CONNECTION=database
SESSION_DRIVER=database
SESSION_LIFETIME=120

MEMCACHED_HOST=127.0.0.1

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your_email@gmail.com
MAIL_PASSWORD=your_app_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="${APP_NAME}"
MAIL_FROM_NAME="${APP_NAME}"

# JWT Configuration
JWT_SECRET=your_jwt_secret_key_here
JWT_TTL=60
JWT_REFRESH_TTL=20160

# GST Configuration
GST_DEBUG=false
```

### 5. Database Migration and Seeding

#### Run Database Migrations
```bash
sudo -u www-data php artisan migrate --force
```

#### Seed Initial Data (Optional)
```bash
sudo -u www-data php artisan db:seed --force
```

#### Create Super Admin User
```bash
sudo -u www-data php artisan tinker
>>> App\Models\User::factory()->create([
    'name' => 'Super Admin',
    'email' => 'admin@yourdomain.com',
    'password' => bcrypt('SecurePassword123!'),
    'email_verified_at' => now(),
]);
>>> exit
```

### 6. Web Server Configuration

#### Nginx Configuration
Create `/etc/nginx/sites-available/gst_billing_pos`:
```nginx
server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    root /var/www/gst_billing_pos/backend/public;

    index index.php index.html;

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

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

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

    client_max_body_size 50M;

    access_log /var/log/nginx/gst_billing_pos.access.log;
    error_log /var/log/nginx/gst_billing_pos.error.log;
}
```

Enable the site and test configuration:
```bash
sudo ln -s /etc/nginx/sites-available/gst_billing_pos /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

#### SSL Certificate (Let's Encrypt)
```bash
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com
```

### 7. Queue Worker Setup (Optional but Recommended)

For better performance with notifications and background jobs:
```bash
# Create systemd service for queue worker
sudo nano /etc/systemd/system/gst-billing-queue.service
```

Add the following content:
```ini
[Unit]
Description=Laravel Queue Worker for GST Billing POS
After=network.target

[Service]
User=www-data
Group=www-data
Restart=always
ExecStart=/usr/bin/php /var/www/gst_billing_pos/backend/artisan queue:work --sleep=3 --tries=3
StopTimeout=10
StartLimitInterval=3600
StartLimitBurst=5

[Install]
WantedBy=multi-user.target
```

Enable and start the service:
```bash
sudo systemctl daemon-reload
sudo systemctl enable gst-billing-queue
sudo systemctl start gst-billing-queue
```

### 8. Scheduled Tasks (Cron Jobs)

Add Laravel scheduler to crontab:
```bash
sudo crontab -u www-data -e
```

Add the following line:
```
* * * * * cd /var/www/gst_billing_pos/backend && php artisan schedule:run >> /dev/null 2>&1
```

### 9. Firewall Configuration

#### Ubuntu/Debian with UFW
```bash
sudo ufw allow 'Nginx Full'
sudo ufw enable
```

#### CentOS/RHEL with Firewalld
```bash
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload
```

### 10. Security Considerations

#### File Permissions
```bash
# Ensure proper ownership
sudo chown -R www-data:www-data storage bootstrap/cache

# Set secure permissions
find /var/www/gst_billing_pos -type f -exec chmod 644 {} \;
find /var/www/gst_billing_pos -type d -exec chmod 755 {} \;
```

#### Environment Security
- Ensure `.env` file is not accessible via web
- Set `APP_DEBUG=false` in production
- Use strong passwords for database and application keys
- Regularly update dependencies: `composer update`

#### PHP Security Settings
Edit your PHP configuration (`/etc/php/8.2/fpm/php.ini`):
```ini
expose_php = Off
display_errors = Off
log_errors = True
error_log = /var/log/php_errors.log
session.cookie_httponly = 1
session.cookie_secure = 1
```

### 11. Backup Strategy

#### Database Backup (Daily)
```bash
# Create backup script
sudo nano /usr/local/bin/db-backup.sh
```

Content:
```bash
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/var/backups/gst_billing_pos"
MYSQL_USER="gstbilling"
MYSQL_PASSWORD="your_strong_password_here"
DATABASE="gst_billing_pos"

mkdir -p $BACKUP_DIR
mysqldump -u $MYSQL_USER -p$MYSQL_PASSWORD $DATABASE | gzip > $BACKUP_DIR/db_$DATE.sql.gz

# Keep only last 7 days
find $BACKUP_DIR -name "db_*.sql.gz" -mtime +7 -delete
```

Make executable and schedule:
```bash
sudo chmod +x /usr/local/bin/db-backup.sh
sudo crontab -u root -e
# Add: 0 2 * * * /usr/local/bin/db-backup.sh
```

#### File Backup (Weekly)
```bash
# Add to crontab for weekly file backup
0 3 * * 0 tar -czf /var/backups/gst_billing_pos/files_$(date +\%Y\%m\%d).tar.gz /var/www/gst_billing_pos
```

### 12. Monitoring and Maintenance

#### Log Monitoring
```bash
# Check application logs
sudo tail -f /var/www/gst_billing_pos/backend/storage/logs/laravel.log

# Check web server logs
sudo tail -f /var/log/nginx/gst_billing_pos.access.log
sudo tail -f /var/log/nginx/gst_billing_pos.error.log
```

#### Health Check Endpoint
Application provides a health check at: `https://yourdomain.com/api/health`

#### Performance Optimization
- Enable OPcache in PHP
- Configure Redis for caching and queues
- Use CDN for static assets
- Enable gzip compression in Nginx

### 13. Troubleshooting

#### Common Issues

1. **Database Connection Errors**
   - Check `.env` database credentials
   - Ensure MySQL service is running: `sudo systemctl status mariadb`
   - Verify user permissions: `SHOW GRANTS FOR 'gstbilling'@'localhost';`

2. **Permission Errors**
   - Check storage and bootstrap/cache permissions
   - Ensure web server user (www-data) owns these directories

3. **500 Internal Server Error**
   - Check Laravel logs: `storage/logs/laravel.log`
   - Check PHP-FPM logs: `/var/log/php8.2-fpm.log`
   - Check Nginx error logs

4. **Queue Worker Issues**
   - Check service status: `sudo systemctl status gst-billing-queue`
   - Check logs: `journalctl -u gst-billing-queue -f`

5. **SSL/TLS Issues**
   - Check certificate validity: `sudo certbot certificates`
   - Renew certificates: `sudo certbot renew --dry-run`

### 14. Update Procedure

To update the application to a newer version:
```bash
# Put application in maintenance mode
sudo -u www-data php artisan down

# Pull latest code
cd /var/www/gst_billing_pos
sudo git pull origin main

# Install/update dependencies
sudo -u www-data composer install --no-dev --optimize-autoloader

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

# Clear caches
sudo -u/www-data php artisan cache:clear
sudo -u/www-data php artisan config:clear
sudo -u/www-data php artisan route:clear
sudo -u/www-data php artisan view:clear

# Take application out of maintenance mode
sudo -u www-data php artisan up

# Restart queue workers
sudo systemctl restart gst-billing-queue
```

## Support

For technical support, please contact:
- Email: support@gstbillingpos.com
- Documentation: https://docs.gstbillingpos.com
- Community Forum: https://community.gstbillingpos.com

---

**Last Updated**: July 25, 2026
**Version**: 1.0.0