diff --git a/openspec/changes/cloud-ready-zero-impact/.openspec.yaml b/openspec/changes/archive/2026-06-18-cloud-ready-zero-impact/.openspec.yaml similarity index 100% rename from openspec/changes/cloud-ready-zero-impact/.openspec.yaml rename to openspec/changes/archive/2026-06-18-cloud-ready-zero-impact/.openspec.yaml diff --git a/openspec/changes/cloud-ready-zero-impact/design.md b/openspec/changes/archive/2026-06-18-cloud-ready-zero-impact/design.md similarity index 100% rename from openspec/changes/cloud-ready-zero-impact/design.md rename to openspec/changes/archive/2026-06-18-cloud-ready-zero-impact/design.md diff --git a/openspec/changes/cloud-ready-zero-impact/proposal.md b/openspec/changes/archive/2026-06-18-cloud-ready-zero-impact/proposal.md similarity index 100% rename from openspec/changes/cloud-ready-zero-impact/proposal.md rename to openspec/changes/archive/2026-06-18-cloud-ready-zero-impact/proposal.md diff --git a/openspec/changes/cloud-ready-zero-impact/specs/compose-cloud-baseline/spec.md b/openspec/changes/archive/2026-06-18-cloud-ready-zero-impact/specs/compose-cloud-baseline/spec.md similarity index 100% rename from openspec/changes/cloud-ready-zero-impact/specs/compose-cloud-baseline/spec.md rename to openspec/changes/archive/2026-06-18-cloud-ready-zero-impact/specs/compose-cloud-baseline/spec.md diff --git a/openspec/changes/cloud-ready-zero-impact/specs/env-cloud-annotations/spec.md b/openspec/changes/archive/2026-06-18-cloud-ready-zero-impact/specs/env-cloud-annotations/spec.md similarity index 100% rename from openspec/changes/cloud-ready-zero-impact/specs/env-cloud-annotations/spec.md rename to openspec/changes/archive/2026-06-18-cloud-ready-zero-impact/specs/env-cloud-annotations/spec.md diff --git a/openspec/changes/cloud-ready-zero-impact/tasks.md b/openspec/changes/archive/2026-06-18-cloud-ready-zero-impact/tasks.md similarity index 100% rename from openspec/changes/cloud-ready-zero-impact/tasks.md rename to openspec/changes/archive/2026-06-18-cloud-ready-zero-impact/tasks.md diff --git a/openspec/specs/compose-cloud-baseline/spec.md b/openspec/specs/compose-cloud-baseline/spec.md new file mode 100644 index 0000000..b510dd8 --- /dev/null +++ b/openspec/specs/compose-cloud-baseline/spec.md @@ -0,0 +1,36 @@ +# compose-cloud-baseline + +Docker Compose 雲端基準設定——healthcheck 使用真實端點、正式 compose 不含開發工具、dev-only 服務透過 override 隔離。 + +## Requirements + +### Requirement: App service healthcheck 驗證 PHP-FPM FastCGI port +`docker-compose.yml` 的 `app` service healthcheck SHALL 使用 `nc -z 127.0.0.1 9000` 確認 PHP-FPM FastCGI port 正在監聽,而非執行 `php -v`(只驗證 binary 存在)。 + +注意:app container 內無 HTTP server,無法透過 HTTP 打 `/health`;`netcat-openbsd` 已在 Dockerfile 安裝。 + +#### Scenario: PHP-FPM 啟動後 healthcheck 通過 +- **WHEN** `app` container 啟動且 PHP-FPM 程序已監聽 port 9000 +- **THEN** `nc -z 127.0.0.1 9000` 回傳 exit code 0,container 標記為 healthy + +#### Scenario: PHP-FPM 未啟動時 healthcheck 失敗 +- **WHEN** `app` container 啟動但 PHP-FPM 程序尚未就緒(port 9000 未開) +- **THEN** `nc -z 127.0.0.1 9000` 回傳非 0 exit code,container 維持 unhealthy 狀態直到重試成功 + +### Requirement: 正式 compose 不含開發工具服務 +`docker-compose.yml` SHALL 不包含 `phpmyadmin` 及 `mailpit` service 定義。這兩個服務屬開發/管理工具,不得出現在正式雲端部署的 compose 設定中。 + +#### Scenario: 只使用 docker-compose.yml 啟動 +- **WHEN** 執行 `docker compose -f docker-compose.yml up -d` +- **THEN** 啟動的服務不包含 `phpmyadmin`(port 8081)及 `mailpit`(port 8025) + +### Requirement: 開發工具服務透過 compose.override.yml 提供 +`compose.override.yml` SHALL 定義 `phpmyadmin`(port 8081)與 `mailpit`(port 8025)service,供本機開發與 VPS 管理使用。 + +#### Scenario: 有 override 檔時開發工具正常啟動 +- **WHEN** 專案根目錄存在 `compose.override.yml` 且執行 `docker compose up -d`(不指定 -f) +- **THEN** Docker Compose 自動合併 override,`phpmyadmin`(port 8081)與 `mailpit`(port 8025)一同啟動 + +#### Scenario: 雲端部署排除開發工具 +- **WHEN** CI/CD 執行 `docker compose -f docker-compose.yml up -d --remove-orphans` +- **THEN** `phpmyadmin` 與 `mailpit` 不啟動,不佔用任何 port 或資源 diff --git a/openspec/specs/env-cloud-annotations/spec.md b/openspec/specs/env-cloud-annotations/spec.md new file mode 100644 index 0000000..fe6abb4 --- /dev/null +++ b/openspec/specs/env-cloud-annotations/spec.md @@ -0,0 +1,23 @@ +# env-cloud-annotations + +`.env.example` 補充雲端部署必要環境變數的說明與正確預設值。 + +## Requirements + +### Requirement: QUEUE_CONNECTION 預設值為 redis +`.env.example` 的 `QUEUE_CONNECTION` SHALL 預設為 `redis`,與 VPS 實際運作設定一致,避免新環境按範本初始化後跑在效能較差的 database queue。 + +#### Scenario: 新環境照 .env.example 初始化 +- **WHEN** 開發者或 CI 以 `.env.example` 為基礎建立 `.env`,未手動修改 `QUEUE_CONNECTION` +- **THEN** Laravel queue driver 使用 Redis,queue worker 正常消費 Redis 佇列中的 job + +### Requirement: .env.example 標示雲端必要變數 +`.env.example` SHALL 以行內註解標示以下雲端部署時必須明確設定的變數: +- `FILESYSTEM_DISK`:雲端應設為 `s3`(預設 `local` 在容器重啟後遺失上傳檔案) +- `LOG_STACK`:雲端建議改為 `stderr` 以接入雲端 logging aggregator +- `QUEUE_CONNECTION`:應為 `redis` +- `SESSION_DRIVER`:雲端建議改為 `redis` + +#### Scenario: 操作者閱讀 .env.example 進行雲端部署 +- **WHEN** 操作者參照 `.env.example` 設定雲端環境的 `.env` +- **THEN** 每個雲端關鍵變數旁有說明,提示預設值在雲端環境的限制與建議替代值