Skip to content

DEPLOYMENT-GUIDE.md

Latest commit

 

History

History
288 lines (229 loc) · 7.57 KB

DEPLOYMENT-GUIDE.md

File metadata and controls

288 lines (229 loc) · 7.57 KB
Raw

GitHub Actions Deployment to DirectAdmin Shared Hosting

🎯 Overview

This repository includes complete GitHub Actions workflows to automatically deploy your multi-tenant SaaS platform to DirectAdmin shared hosting. The deployment system supports both production and staging environments with automated testing.

🚀 Deployment Workflows

1. Production Deployment (deploy-directadmin.yml)

  • Triggers: Push to main or production branch, or manual trigger
  • Features:
    • Automated PHP and Node.js setup
    • Composer and NPM dependency installation
    • Frontend asset building with Vite
    • FTP deployment to shared hosting
    • Post-deployment Laravel optimization via SSH
    • Comprehensive logging and error handling

2. Staging Deployment (deploy-staging.yml)

  • Triggers: Push to develop or staging branch, or pull requests
  • Features:
    • Full test suite execution with MySQL database
    • Code quality checks and testing
    • Automated staging deployment after tests pass
    • Separate staging environment configuration

📋 Setup Instructions

Step 1: Configure GitHub Secrets

In your GitHub repository, go to Settings → Secrets and variables → Actions and add:

Production Secrets:

FTP_HOST=your-directadmin-server.com
FTP_USERNAME=your-directadmin-username  
FTP_PASSWORD=your-directadmin-password
FTP_PORT=21
FTP_PROTOCOL=ftp
FTP_SERVER_DIR=/domains/yourdomain.com/public_html
SSH_HOST=your-directadmin-server.com
SSH_USERNAME=your-directadmin-username
SSH_PASSWORD=your-directadmin-password
SSH_PORT=22
DOMAIN_NAME=yourdomain.com

Staging Secrets (optional):

STAGING_FTP_HOST=your-staging-server.com
STAGING_FTP_USERNAME=your-staging-username
STAGING_FTP_PASSWORD=your-staging-password
STAGING_FTP_PORT=21
STAGING_FTP_PROTOCOL=ftp
STAGING_FTP_SERVER_DIR=/domains/staging.yourdomain.com/public_html
STAGING_SSH_HOST=your-staging-server.com
STAGING_SSH_USERNAME=your-staging-username
STAGING_SSH_PASSWORD=your-staging-password
STAGING_SSH_PORT=22

Step 2: Configure Environment Files

Update .env.production:

APP_NAME="AI SaaS Platform"
APP_ENV=production
APP_KEY=base64:your-generated-key
APP_DEBUG=false
APP_URL=https://yourdomain.com

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

# Add your API keys, Stripe keys, etc.

Step 3: DirectAdmin Setup

  1. Create Database:

    • Log into DirectAdmin
    • Go to "MySQL Management"
    • Create database and user
    • Note credentials for .env file

  2. Configure Domain:

    • Ensure your domain points to your DirectAdmin server
    • SSL certificate should be installed and active

  3. PHP Configuration:

    • Ensure PHP 8.1+ is available
    • Enable required PHP extensions

Step 4: Deploy

Automatic Deployment:

# Deploy to production
git push origin main

# Deploy to staging  
git push origin develop

Manual Deployment:

  1. Go to your GitHub repository
  2. Click "Actions" tab
  3. Select "Deploy to DirectAdmin Shared Hosting"
  4. Click "Run workflow"
  5. Choose environment and click "Run workflow"

🔧 Deployment Process

What Happens During Deployment:

  1. Preparation Phase:

    • Checkout code from repository
    • Setup PHP 8.2 with required extensions
    • Cache and install Composer dependencies
    • Setup Node.js and install NPM packages

  2. Build Phase:

    • Build frontend assets with Vite
    • Optimize code for production
    • Create deployment package
    • Remove development files

  3. Deployment Phase:

    • Upload files via FTP/SFTP to DirectAdmin
    • Set proper file permissions
    • Create necessary .htaccess files

  4. Post-Deployment Phase (via SSH):

    • Set Laravel-specific permissions
    • Create storage symlink
    • Clear and rebuild Laravel caches
    • Run database migrations
    • Optimize application for production

📊 Monitoring Deployment

GitHub Actions Dashboard:

  • View real-time deployment progress
  • Check logs for any issues
  • Monitor deployment success/failure

DirectAdmin Logs:

  • Check error logs for runtime issues
  • Monitor resource usage
  • Verify SSL certificate status

🛠️ Troubleshooting

Common Issues and Solutions:

1. FTP Connection Failed

Error: Could not connect to FTP server

Solutions:

  • Verify FTP credentials in GitHub secrets
  • Check if FTP is enabled in DirectAdmin
  • Try SFTP instead of FTP (more secure)
  • Verify server firewall settings

2. Permission Denied

Error: Permission denied when setting file permissions

Solutions:

  • Check SSH credentials
  • Verify user has proper permissions
  • Contact hosting provider for permission issues

3. Laravel 500 Error

Error: Internal Server Error after deployment

Solutions:

  • Check storage and bootstrap/cache permissions (775)
  • Verify .env file exists and is readable
  • Check DirectAdmin error logs
  • Ensure PHP version is 8.1+

4. Database Connection Error

Error: Could not connect to database

Solutions:

  • Verify database credentials in .env
  • Ensure database exists in DirectAdmin
  • Check database user permissions
  • Test database connection manually

5. Missing Storage Link

Error: Storage files not accessible

Solutions:

  • SSH into server and run: php artisan storage:link
  • Check if symlink exists in public/storage
  • Verify storage directory permissions

📈 Advanced Configuration

Custom Deployment Scripts:

Pre-deployment Hook:

Create .github/workflows/pre-deploy.yml for custom pre-deployment tasks.

Post-deployment Hook:

Modify the SSH commands in the workflow to add custom post-deployment tasks.

Environment-Specific Configurations:

Multiple Staging Environments:

  • Create separate workflows for different staging environments
  • Use branch-specific configurations
  • Set up different GitHub secrets for each environment

Database Migrations:

  • Automatic migrations are included in the deployment
  • For sensitive migrations, consider manual approval steps
  • Use migration rollbacks for critical issues

Performance Optimization:

Caching Strategy:

  • Laravel configs, routes, and views are automatically cached
  • Consider Redis if available on your hosting
  • Implement application-level caching for API responses

CDN Integration:

  • Configure asset URLs to use CDN
  • Update ASSET_URL in .env for production
  • Consider using services like Cloudflare

🔒 Security Considerations

Secrets Management:

  • Never commit sensitive data to repository
  • Use GitHub secrets for all credentials
  • Rotate passwords regularly
  • Use SFTP instead of FTP when possible

File Permissions:

  • Directories: 755
  • Files: 644
  • Storage and bootstrap/cache: 775
  • Never use 777 permissions

SSL/HTTPS:

  • Ensure SSL certificate is active
  • Force HTTPS in production
  • Update CORS and Sanctum domains for HTTPS

📞 Support

Deployment Issues:

  1. Check GitHub Actions logs first
  2. Review DirectAdmin error logs
  3. Verify all configuration settings
  4. Test manually via SSH if needed

Application Issues:

  1. Check Laravel logs in storage/logs/
  2. Verify environment configuration
  3. Test database connectivity
  4. Monitor resource usage

🎉 Success!

Once deployed successfully, your AI SaaS platform will be accessible at your configured domain with:

  • ✅ Automatic SSL/HTTPS
  • ✅ Multi-tenant architecture
  • ✅ AI agent functionality
  • ✅ Stripe billing integration
  • ✅ Professional admin panel
  • ✅ Complete API endpoints
  • ✅ Responsive frontend

Your platform is now ready for customers! 🚀