# Deployment Guide - Invoice Generator Application

This guide will help you deploy the Invoice Generator application to a production server.

## Prerequisites

- **PHP**: 8.2 or higher with extensions: BCMath, Ctype, cURL, DOM, Fileinfo, JSON, Mbstring, OpenSSL, PCRE, PDO, Tokenizer, XML
- **Composer**: Latest version
- **Node.js & NPM**: For asset compilation (if rebuilding assets)
- **Database**: MySQL 5.7+, PostgreSQL 10+, MariaDB 10.3+, or SQLite 3.8.8+
- **Web Server**: Apache 2.4+ or Nginx 1.18+
- **SSL Certificate**: Recommended for production

## Deployment Steps

### 1. Upload Files

Upload all files from the zip archive to your server's web root directory (e.g., `public_html`, `www`, or a subdirectory).

**Important**: Make sure the `public` folder is your web root. If deploying to shared hosting, point your domain to the `public` folder.

### 2. Install Dependencies

```bash
# Install PHP dependencies
composer install --optimize-autoloader --no-dev

# If you need to rebuild assets (Node.js required)
npm install
npm run build
```

### 3. Environment Configuration

```bash
# Copy the example environment file
cp .env.example .env

# Generate application key
php artisan key:generate
```

### 4. Configure .env File

Edit the `.env` file with your production settings:

```env
APP_NAME="Invoice Generator"
APP_ENV=production
APP_KEY=base64:... (generated by key:generate)
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_database_user
DB_PASSWORD=your_database_password

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
MAIL_FROM_ADDRESS="noreply@yourdomain.com"
MAIL_FROM_NAME="${APP_NAME}"
```

### 5. Set Permissions

```bash
# Set proper permissions
chmod -R 755 storage
chmod -R 755 bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
```

**For shared hosting**, you may need to set permissions via FTP/cPanel:
- `storage` folder: 755 (or 775)
- `bootstrap/cache` folder: 755 (or 775)

### 6. Create Storage Link

```bash
php artisan storage:link
```

This creates a symbolic link from `public/storage` to `storage/app/public` for public file access (like uploaded logos).

### 7. Run Migrations

```bash
php artisan migrate --force
```

**Note**: Use `--force` flag only in production. This will create all necessary database tables.

### 8. Optimize for Production

```bash
# Cache configuration
php artisan config:cache

# Cache routes
php artisan route:cache

# Cache views
php artisan view:cache

# Optimize autoloader
composer install --optimize-autoloader --no-dev
```

### 9. Configure Web Server

#### Apache (.htaccess included)

The application comes with `.htaccess` files in the `public` folder. Ensure `mod_rewrite` is enabled on your Apache server.

#### Nginx Configuration

Add this to your Nginx server block:

```nginx
server {
    listen 80;
    server_name yourdomain.com;
    root /path/to/your/project/public;

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

    index index.php;

    charset utf-8;

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

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    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;
    }
}
```

### 10. SSL/HTTPS Setup

Enable SSL/HTTPS for security:
- Use Let's Encrypt (free)
- Update `APP_URL` in `.env` to use `https://`
- Ensure `APP_ENV=production` and `APP_DEBUG=false`

## Post-Deployment Checklist

- [ ] Application key generated
- [ ] Database configured and migrated
- [ ] Storage link created
- [ ] File permissions set correctly
- [ ] `.env` file configured with production values
- [ ] `APP_DEBUG=false` in production
- [ ] SSL certificate installed
- [ ] Assets compiled and optimized
- [ ] Caches cleared and rebuilt
- [ ] Test user registration and login
- [ ] Test invoice creation and PDF generation

## Maintenance Commands

```bash
# Clear all caches
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# Rebuild caches
php artisan config:cache
php artisan route:cache
php artisan view:cache

# Put application in maintenance mode
php artisan down

# Bring application back online
php artisan up

# Run migrations
php artisan migrate

# Check application status
php artisan about
```

## Troubleshooting

### 500 Internal Server Error
1. Check file permissions (`storage` and `bootstrap/cache`)
2. Verify `.env` file exists and is configured correctly
3. Check Laravel logs: `storage/logs/laravel.log`
4. Ensure `APP_KEY` is set in `.env`

### Permission Denied Errors
```bash
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
```

### Storage Link Not Working
```bash
php artisan storage:link
```
If on shared hosting, you may need to create the link manually via FTP.

### Assets Not Loading
- Ensure `public/build` folder exists
- Run `npm run build` to rebuild assets
- Check `APP_URL` in `.env` matches your domain

### Database Connection Errors
- Verify database credentials in `.env`
- Ensure database exists
- Check database user has proper permissions
- Test connection with: `php artisan tinker` then `DB::connection()->getPdo();`

## Security Recommendations

1. **Always set `APP_DEBUG=false` in production**
2. **Use strong database passwords**
3. **Enable HTTPS/SSL**
4. **Keep Laravel and dependencies updated**
5. **Regular backups of database and files**
6. **Use environment variables for sensitive data**
7. **Restrict file permissions**
8. **Enable firewall rules**
9. **Regular security updates**

## Backup Strategy

### Database Backup
```bash
# MySQL
mysqldump -u username -p database_name > backup.sql

# PostgreSQL
pg_dump -U username database_name > backup.sql
```

### File Backup
- Backup entire `storage` folder
- Backup `.env` file (keep secure!)
- Backup uploaded files in `storage/app/public`

## Performance Optimization

1. **Enable OPcache** in PHP
2. **Use Redis/Memcached** for caching
3. **CDN** for static assets
4. **Database indexing** (already in migrations)
5. **Queue jobs** for heavy tasks (configure in `.env`)

## Support

For issues or questions:
- Check the `APPLICATION_DOCUMENTATION.md` for features
- Review Laravel documentation: https://laravel.com/docs
- Check error logs: `storage/logs/laravel.log`

---

**Version**: 1.0  
**Last Updated**: December 2024