first commit

README.md

@@ -0,0 +1,153 @@
+# KTVCentral 開發環境部署說明
+
+本專案使用 Docker 開發環境，整合以下元件：
+
+- Laravel 12
+- PHP 8.3 (FPM)
+- MariaDB
+- Redis + RedisInsight
+- 自動 HTTPS：`nginx-proxy` + `letsencrypt-nginx-proxy-companion`
+
+---
+
+## 🚀 啟動方式
+
+### 1. 建立 `.env`
+
+複製 `.env.example` 為 `.env` 並設定參數：
+
+```bash
+cp .env.example .env
+```
+
+設定如下變數：
+
+```env
+APP_DOMAIN=your-domain.local
+LETSENCRYPT_EMAIL=you@example.com
+
+PROJECT_NAME=ktvcentral
+DB_DATABASE=ktvcentral
+DB_USERNAME=ktvcentral
+DB_PASSWORD=secret
+```
+
+---
+
+### 2. 啟動 Docker（自動 HTTPS）
+
+預設使用 nginx-proxy + Let's Encrypt 自動管理憑證。
+
+```bash
+docker-compose -f docker-compose.yaml -f docker-compose.letsencrypt.yaml up -d
+```
+
+---
+
+### 3. 首次初始化（自動執行於 entrypoint）
+
+包含：
+
+- 專案 clone（來自 `GIT_REPO_URL`）
+- `composer install`
+- `.env` 設定替換（自動注入 DB、Redis 等）
+- `php artisan key:generate`
+- `php artisan migrate --force`
+- `npm install && npm run build`
+- Laravel schedule 加入 crontab
+- 透過 `supervisord` 啟動：
+  - php-fpm
+  - queue worker
+  - cron
+
+---
+
+## 🔧 手動 HTTPS 控制
+
+### 自動 HTTPS（預設）
+
+使用：
+
+```bash
+docker-compose -f docker-compose.yaml -f docker-compose.letsencrypt.yaml up -d
+```
+
+### 關閉 HTTPS（無 Let's Encrypt）
+
+使用：
+
+```bash
+docker-compose -f docker-compose.yaml up -d
+```
+
+---
+
+## 📁 資料目錄結構
+
+```
+.
+├── data/                 # 專案會被 clone 到這（/var/www/html）
+│   └── html/
+├── docker/
+│   ├── entrypoint.sh     # 初始與 Laravel 任務處理
+│   └── supervisord.conf  # 管理 php-fpm、queue、cron
+├── docker-compose.yaml
+├── docker-compose.letsencrypt.yaml
+├── .env
+└── README.md
+```
+
+---
+
+## 📥 Laravel 專案匯入來源
+
+請於 `.env` 設定：
+
+```env
+GIT_REPO_URL=https://your.git.repo/your-project.git
+```
+
+---
+
+## 🔒 自動 HTTPS 注意事項
+
+- 需將你的 `APP_DOMAIN` 指向本機 IP，例如透過 `/etc/hosts`：
+
+```plaintext
+127.0.0.1 your-domain.local
+```
+
+- 憑證會儲存在 `./certs` 資料夾
+- 若為公開伺服器，請確保 80 / 443 連接埠已開啟
+
+---
+
+## 🧹 常見指令
+
+```bash
+# 查看容器狀態
+docker ps
+
+# 重啟容器
+docker-compose restart
+
+# 進入 app 容器
+docker exec -it ktvcentral_app bash
+
+# 查看 log
+docker-compose logs -f
+```
+
+---
+
+## ✅ 預設啟動的 Supervisor 服務
+
+- PHP-FPM (`php-fpm`)
+- Laravel Queue Worker (`php artisan queue:work`)
+- Cron（執行 `php artisan schedule:run` 每分鐘）
+
+---
+
+## 📄 License
+
+MIT