Federated from workspace · PRD-001 · Dental Clinic Revenue Operating System/docs/deployment/PRODUCTION_RUNBOOK.md Do not edit canonical truth here — update the source repo, then re-run npm run docs:sync.

---

AI Clinic OS — Production Runbook

Operational guide for deploying and running the first managed production pilot. This is not marketing documentation.

1. Server requirements

Component	Minimum	Recommended
OS	Ubuntu 22.04 LTS	Ubuntu 24.04 LTS
CPU	2 vCPU	4 vCPU
RAM	4 GB	8 GB
Disk	40 GB SSD	80 GB SSD

PHP 8.2+ extensions

bcmath ctype curl dom fileinfo json mbstring openssl pdo pdo_pgsql tokenizer xml zip

Optional but recommended: redis, intl, gd or imagick.

2. Stack

• Web: Nginx (or Caddy) terminating HTTPS
• App: PHP-FPM 8.2+
• Database: PostgreSQL 15+
• Queue: Redis (recommended) or database driver
• Cache: Redis (recommended) or database
• Scheduler: system cron → php artisan schedule:run
• Workers: Supervisor managing queue:work

3. Initial deploy

git clone <repository-url> /var/www/ai-clinic-os
cd /var/www/ai-clinic-os

composer install --no-dev --optimize-autoloader
cp .env.example .env
php artisan key:generate

npm ci
npm run build

4. Environment variables (production)

Variable	Required	Notes
APP_ENV	yes	production
APP_DEBUG	yes	false
APP_URL	yes	https://your-domain.com
DB_CONNECTION	yes	pgsql
DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD	yes	PostgreSQL
QUEUE_CONNECTION	yes	redis or database — never sync
CACHE_STORE	yes	redis or database
SESSION_DRIVER	yes	database or redis
MAIL_MAILER	yes	smtp, ses, or postmark
MAIL_FROM_ADDRESS	yes	Verified sender
MAIL_FROM_NAME	yes	Clinic product name
TENANCY_ENABLED	yes	true for SaaS pilot
TENANCY_BASE_DOMAIN	yes	e.g. dentrevenue.com
SAAS_BILLING_PROVIDER	yes	stripe in production
SAAS_CUSTOMER_EXPERIENCE_REQUIRE_EMAIL_VERIFICATION	yes	true
REDIS_HOST	if using redis
AWS_* / STRIPE_*	as needed	Billing and object storage

Run php artisan config:cache and php artisan route:cache after env changes.

5. Database

php artisan migrate --force
php artisan db:seed --class=PilotProductionSeeder   # first pilot clinic only

For upgrades:

php artisan migrate --force
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache

6. Storage and permissions

chown -R www-data:www-data storage bootstrap/cache
chmod -R ug+rwx storage bootstrap/cache
php artisan storage:link

Ensure storage/app, storage/logs, and bootstrap/cache are writable by PHP-FPM.

7. Queue workers (Supervisor)

/etc/supervisor/conf.d/ai-clinic-os-worker.conf:

[program:ai-clinic-os-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/ai-clinic-os/artisan queue:work redis --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/ai-clinic-os/storage/logs/worker.log
stopwaitsecs=3600

supervisorctl reread && supervisorctl update && supervisorctl start ai-clinic-os-worker:*

8. Scheduler (cron)

* * * * * www-data cd /var/www/ai-clinic-os && php artisan schedule:run >> /dev/null 2>&1

Critical scheduled commands:

• reminders:process — every 15 minutes
• autopilot:run — hourly (when enabled)
• clinic-ai:run — every 10 minutes (when enabled)
• saas:billing — daily
• workflow:process-schedules — every minute

9. HTTPS and health checks

• Terminate TLS at Nginx/Caddy; forward X-Forwarded-Proto
• Health endpoint: GET /up (Laravel 11 built-in)
• After deploy: curl -f https://your-domain.com/up

10. Pilot validation

Before onboarding the first paying clinic:

php artisan pilot:validate-deployment
php artisan pilot:validate-deployment --strict   # production: fail on warnings
php artisan test --filter=ProductionSmokeTest
php artisan test --filter=PilotDeploymentReadinessTest
php artisan test --filter=PilotWorkflowTest

All checks must show PASS (warnings reviewed in strict mode).

11. First clinic onboarding

1. Owner visits /signup (Threshold experience)
2. Completes workspace preparation → receives verification email (Settle phase)
3. Clicks verification link → organization onboarding wizard
4. Completes clinic profile, branding, plan selection
5. Assign receptionist and doctor accounts via Team page
6. Configure SMTP-sent reminders and working hours
7. Run one test lead → booking → appointment through CRM

Optional: seed demo data with PilotProductionSeeder for training environments only.

12. Backups

php artisan backup:run

Configure config/backup.php for off-site storage (S3). Verify restore quarterly.

13. Rollback

1. Put app in maintenance: php artisan down
2. Restore previous release tag / deployment artifact
3. Roll back database if migration was destructive (restore from backup)
4. composer install --no-dev, npm run build, php artisan migrate:status
5. Restart workers and PHP-FPM
6. php artisan up
7. Re-run pilot:validate-deployment

14. Disaster recovery

Scenario	Response
Database loss	Restore latest PostgreSQL backup; replay queue dead letter if any
Redis loss	Restart Redis; cache rebuilds automatically; queue may need replay
Worker stopped	Supervisor autostart; check storage/logs/worker.log
Mail failure	Verify SMTP credentials; check failed jobs table
Scheduler stopped	Restore cron; run reminders:process manually once

15. Common production failures

Symptom	Likely cause	Fix
Verification emails not sent	QUEUE_CONNECTION=sync or worker down	Enable queue + supervisor
Reminders never fire	Cron missing	Add schedule:run cron
403 after login	Tenant not resolved	Check TENANCY_BASE_DOMAIN, DNS
Mixed content / bad links	APP_URL not HTTPS	Set APP_URL=https://...
Upload failures	Storage not writable	Fix permissions on storage/
Stripe webhooks fail	Wrong endpoint secret	Update STRIPE_WEBHOOK_SECRET

16. Verification checklist

• [ ] php artisan pilot:validate-deployment --strict passes
• [ ] GET /up returns 200
• [ ] Signup → verify email → onboarding completes
• [ ] Admin login works for owner, receptionist, doctor
• [ ] Queue worker processing (check jobs table emptying)
• [ ] Cron running (schedule:list matches bootstrap schedule)
• [ ] Test reminder email delivered
• [ ] PostgreSQL backups scheduled
• [ ] HTTPS certificate valid
• [ ] Pilot workflow test passes on staging

---

Authority: Consumer deployment operations · complements docs/DEPLOYMENT-CHECKLIST.md and docs/PILOT-WORKFLOW.md.