# Deployment and Scaling

This document describes planned environment, delivery, operations, and scaling direction. It does not create GitHub Actions, deployment scripts, infrastructure configuration, or production paths.

## Status labels

- **Approved foundation** — already established by the repository documentation.
- **Recommended direction** — the preferred approach, subject to product-owner approval.
- **Deferred decision** — intentionally decided later.
- **Open question** — requires product-owner input.

## Local development

- **Recommended direction** — Local development should use environment-based configuration and safe placeholder values.
- **Recommended direction** — Redis should not be mandatory for initial local development, though the application should be Redis-ready for shared cache, sessions, and queues.
- **Recommended direction** — Local data must not include real production customer data.

## UAT

- **Recommended direction** — UAT has its own hostname, MySQL database, application encryption key, Stripe test mode configuration, Google OAuth configuration, email configuration, sessions and cache, test organizations, and test users.
- **Recommended direction** — The initial UAT URL should be `https://uat.cloutal.com/workspace/` as a transitional path-based deployment.
- **Recommended direction** — A future UAT-specific Workspace subdomain may be introduced when product and operations owners approve the DNS and certificate plan.
- **Recommended direction** — UAT must not contain real production customer data.
- **Recommended direction** — UAT should run the exact commit intended for production promotion.
- **Recommended direction** — UAT and production must use separate deployment directories so source, configuration, storage, logs, sessions, cache, credentials, and environment files are not shared accidentally.

## Production

- **Recommended direction** — Production has its own hostname, MySQL database, application encryption key, Stripe live mode configuration, Google OAuth configuration, email configuration, sessions and cache, and real customer data.
- **Recommended direction** — The initial production URL should be `https://cloutal.com/workspace/` as a transitional path-based deployment.
- **Recommended direction** — The planned future production URL should be `https://workspace.cloutal.com/`.
- **Recommended direction** — The future `workspace.cloutal.com` hostname should point to the existing production deployment rather than requiring a separate application copy.
- **Recommended direction** — When the dedicated production subdomain becomes active, `https://cloutal.com/workspace/` may redirect to `https://workspace.cloutal.com/`.
- **Recommended direction** — Production changes must be reviewed, auditable, environment-specific, and protected by backups, migrations, health checks, monitoring, and rollback planning.

## Environment separation

- **Approved foundation** — The same source-code commit must be capable of running in UAT or production through environment-specific configuration.
- **Approved foundation** — UAT and production must never share databases, encryption keys, Stripe modes, Stripe webhook secrets, OAuth credentials, sessions, customer records, or backup locations.
- **Recommended direction** — Secrets such as application keys, database credentials, email credentials, Stripe webhook secrets, OAuth credentials, and backup credentials belong in environment configuration or a secrets manager, not in source code.
- **Recommended direction** — Environment-specific URLs must come from configuration so the same application code can operate under the temporary `/workspace` path and later under the dedicated Workspace subdomain.
- **Recommended direction** — The application must not hardcode `/workspace` into routes, links, assets, authentication callbacks, cookies, or application logic.
- **Recommended direction** — Google OAuth redirect URLs, Stripe return URLs, canonical URLs, secure cookies, trusted-host settings, and any future central-login or handoff endpoints need environment-specific configuration for UAT, initial production, the future production subdomain, and verified customer-owned domains.

## Web root and deployment directories

- **Recommended direction** — The web server should expose only the application's future `public/` directory.
- **Recommended direction** — Application source code, configuration, logs, storage, credentials, and `.env` files must not be directly web-accessible.
- **Recommended direction** — UAT and production deployment directories should be separate even when hosted on the same infrastructure.
- **Recommended direction** — The future production subdomain should route to the existing production deployment directory rather than creating a second production application copy.
- **Recommended direction** — No DNS, web-server, deployment-workflow, or infrastructure files are created by this documentation task.

## GitHub workflow

1. **Recommended direction** — Start from the latest `main`.
2. **Recommended direction** — Create a feature or fix branch.
3. **Recommended direction** — Implement and test the change.
4. **Recommended direction** — Open a pull request targeting `main`.
5. **Recommended direction** — Review the pull request.
6. **Recommended direction** — Run automated tests and security checks.
7. **Recommended direction** — Merge approved changes.
8. **Recommended direction** — Automatically deploy the merged commit to UAT.
9. **Recommended direction** — Run UAT database migrations and health checks.
10. **Recommended direction** — Test the exact commit in UAT.
11. **Recommended direction** — Promote the exact UAT-tested commit to production.
12. **Recommended direction** — Create a production backup before migrations.
13. **Recommended direction** — Run production migrations and health checks.
14. **Recommended direction** — Roll back automatically when safe if health checks fail.

## Database migrations

- **Approved foundation** — Schema changes must be made through database migrations when application data models are introduced.
- **Recommended direction** — Migration plans should include backup-before-deployment, forward migration checks, rollback expectations where safe, and post-migration health checks.

## Backups and maintenance

- **Recommended direction** — Future automated processes should cover encrypted MySQL backups, off-server backup storage, backup retention, backup-success monitoring, periodic restore testing, disk-space monitoring, error monitoring, queue monitoring, failed-job handling, session cleanup, expired invitation cleanup, trial expiration, retention and deletion, custom-domain health checks, email delivery and bounce handling, dependency updates, security alerts, and database migrations.
- **Recommended direction** — Automation can retry and alert, but security incidents, unusual failures, restoration decisions, and customer disputes may still require human intervention.

## Customer domains

- **Recommended direction** — Support a Cloutal-controlled fallback hostname and customer-owned subdomains such as `staff.customer.com`.
- **Recommended direction** — Domain-to-organization mapping, CNAME-based onboarding, ownership verification, status tracking, automated HTTPS certificate provisioning and renewal, canonical URL handling, centralized OAuth callback handling, and safe behavior when DNS stops pointing to the service should be planned.
- **Approved foundation** — One customer must not be able to claim another customer's hostname, and a hostname must be verified and mapped to the correct organization before tenant-scoped requests or authentication handoffs are accepted.

### Deferred decision: authentication on customer-owned domains

- **Deferred decision** — Browser session cookies cannot be shared across unrelated customer-owned domains and a central Cloutal login domain. A future reviewed architecture decision must choose how authenticated users move between those domains.
- **Deferred decision** — Approaches to evaluate include central authentication followed by a short-lived, signed, single-use login handoff to the verified customer hostname, or independently established authenticated sessions on each customer domain.
- **Approved foundation** — Reusable session credentials must never be placed in query strings.
- **Approved foundation** — Any handoff token must be short-lived, single-use, audience-bound to the intended hostname, and protected against replay.
- **Approved foundation** — The destination hostname must already be verified and mapped to the correct organization.
- **Approved foundation** — Session cookies must be Secure, HTTP-only, SameSite-aware, and scoped only to the appropriate hostname.
- **Recommended direction** — OAuth callbacks should remain centralized where practical to avoid per-customer callback sprawl.
- **Recommended direction** — Domain-onboarding and authentication-handoff health checks should fail safely when ownership verification, DNS, certificate state, hostname mapping, or replay protection cannot be confirmed.

## Scaling stages

### Initial stage

- **Recommended direction** — One application server, MySQL, scheduled jobs, local session and cache drivers where appropriate, off-server encrypted backups, and monitoring.

### First growth stage

- **Recommended direction** — Separate MySQL database server, Redis for shared sessions/cache/queues, separate queue workers, shared or object storage for customer files, and centralized application logs.

### Larger growth stage

- **Recommended direction** — Load balancer, multiple identical application servers, centralized sessions and cache, shared file storage, dedicated background workers, managed or replicated database, and centralized logs and metrics.

## Statelessness and recovery expectations

- **Recommended direction** — The application must avoid permanent dependency on one server's filesystem, one server's sessions, one server's cache, one server's scheduled process, hardcoded hostnames, or hardcoded environment settings.
- **Recommended direction** — Server migration should be possible by restoring configuration, connecting to the correct database and shared storage, running health checks, and moving traffic only after validation.
- **Recommended direction** — Recovery expectations should distinguish automated rollback from human decisions about restores, customer disputes, data incidents, and unusual operational failures.

## Open questions

- **Open question** — Which hosting provider, DNS provider, certificate strategy, monitoring tools, and backup-retention period should be selected first?
- **Open question** — What health checks are required before UAT promotion and production release?