Chapter 4 - Installation and Deployment

Environment preparation (source code + infra)

1. Linux server with PHP 8.2+ extensions; Apache/Nginx configuration (repo only has .htaccess for Apache).
2. Obtain repository.
3. Install composer + npm.
4. Install/start MySQL + Redis (if needed).
5. Set up queue worker supervisor and cron.
6. Configure SSL (not automated by repo).

Build/install sequence (production)

1. composer install --no-dev --optimize-autoloader.
2. cp your private baseline to .env (repository provides none — manage as secret).
3. php artisan key:generate.
4. php artisan migrate --force (supports SaaS/env switches).
5. php artisan db:seed only if you want available starter/fresh demo data (warning: demo only insertion under flagged condition, users potentially inserted; dedicated fresh app defaults best left seeded).
6. npm ci / npm run build (verifying vite 6 / node compatibility).
7. php artisan storage:link.
8. php artisan cache:clear, config:cache, route:cache (caution: route caching might cause controller resolution issue? Inertia generally okay).
9. Ensure storage/framework/cache/data, sessions, views, testing; set file ownership for web user.
10. php artisan schedule:run + queue worker.

Queue and scheduler setup

• Scheduler:

* * * * * cd /path/to/app && php artisan schedule:run >> /dev/null 2>&1

• Queue:

php artisan queue:work --tries=3 --timeout=600

• Commands exposed: emails:sync-all, emails:listen, emails:ai-auto-process, emails:process-batch, others.
• Existing Docker uses queue:work --daemon --tries=3 --timeout=600 --sleep=3.

Web server configuration

• public/ directory set as docroot.
• Apache rewrite via .htaccess exists.
• Nginx likely uses standard Laravel config:
• root path public; index.php. No custom example in repo (gap).
• App’s health endpoint /up.
• Currently no public/build in repository, required after npm run build.

Storage

• Default local; dynamic storage uses settings (S3 if registered).
• Media exposes via MediaController, token mark for private/public path.
• Plan storage limit check (bytes conversion via Plan).

Additional configuration

• IMAP must request inbound email reader usage + credentials stored in user/workspace.
• Gemini key; OpenAI fallback (demo).
• ChatGPT App is gated via settings.
• Payment settings.
• SMTP email.
• CAPTCHA/cookie consent enterprise-level website configuration for public site.
• Logging key (Larabug optional).

Deployment verification

• Login with SEEDER_CREDENTIALS users to test mounts.
• Configure workspace and user.
• Configure integration drivers before testing evaluator.
• Send test emails and watch storage/logs.
• Validate cron and daemons after restart.
• Ensure file upload via plan allows count.

Maintenance/remediation tasks

• Switch environment to non-demo / SaaS.
• Manual creation of .env (required; easy to forget when packaging).
• Upgrade Laravel patches if available.
• And scheduler must have valid working credentials.