KTVSinglePublisher/README.md

# Laravel + Docker 開發環境

本專案提供一個以 Docker 為基礎的 Laravel 開發環境，整合以下功能：

- Laravel App with PHP 8.3
- Nginx 作為 Web Server
- MariaDB 作為資料庫
- Supervisor 管理 Laravel 的 queue 與 scheduler
- Git Worker 自動同步程式碼 (透過 git pull)
- 多容器架構支援 `.env` 配置

---

## 📁 專案結構

```
.
├── docker/                  # 各服務用到的設定檔
│   ├── nginx/               # Nginx templates
│   ├── mariadb/             # MariaDB my.cnf
│   ├── php/                 # PHP 設定
│   ├── entrypoint.git.sh    # Git worker 初始化腳本
│   ├── supervisord.conf     # Laravel App 用 Supervisor 設定
│   └── supervisord.git.conf # Git Worker 用 Supervisor 設定
├── data/                    # 資料儲存與服務掛載目錄
│   ├── html/                # Laravel 專案程式碼 (git clone 下來)
│   ├── logs/                # Log 檔目錄
│   ├── mariadb/             # DB 資料儲存
│   └── nginx/               # Nginx 設定
├── Dockerfile               # Laravel App Dockerfile
├── Dockerfile.git           # Git Worker Dockerfile
├── docker-compose.yml
└── README.md
```

---

## 🚀 快速開始

### 1️⃣ 建立 `.env` 檔案

```bash
cp .env.example .env
```

填寫必要參數：

```env
APP_NAME=ktvcentral
APP_URL=http://localhost
APP_DOMAIN=localhost
APP_PORT=80

REPO_URL=https://github.com/your/laravel-repo.git
REPO_BRANCH=main

DB_HOST=mariadb
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=laravel
DB_PASSWORD=secret
```

---

### 2️⃣ 使用容器方法

```bash
./start.sh --wipe 
./stop.sh --wipe
./restart.sh
```

完成後會啟動：

- Laravel app
- Git worker (定期同步程式碼)
- Queue worker / Scheduler（由 Supervisor 管理）
- MariaDB
- Nginx

---

## 🛠️ 服務說明

| 容器名稱           | 說明                                        |
|--------------------|---------------------------------------------|
| `ktvcentral_app`   | Laravel App (PHP 8.3 + Supervisor)          |
| `ktvcentral_db`    | MariaDB 10.6                                |
| `ktvcentral_nginx` | 靜態資源與反向代理（連接 Laravel App）     |

---

## 📚 Laravel 常見操作

```bash
# 進入 app 容器
docker compose exec app bash

# Laravel 操作範例
php artisan migrate --seed
php artisan queue:restart
npm install && npm run build
```

---

## 🧼 目錄權限與 Log

請確保以下目錄存在且權限正確：

```bash
mkdir -p data/html
mkdir -p data/logs/php
mkdir -p data/logs/nginx
mkdir -p data/logs/mariadb
```

Laravel 儲存相關：

```bash
chown -R www-data:www-data storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
```

---

## 🐳 Supervisor 管理進程

| 進程名稱       | 功能                             |
|----------------|----------------------------------|
| `queue-worker` | 執行 Laravel 的 queue 任務       |
| `scheduler`    | 每分鐘執行 Laravel schedule:run |
| `git-worker`   | 每分鐘從 Git 拉取最新程式碼      |

查看 log：

```bash
docker compose exec app tail -f /var/www/logs/supervisord.log
```

---

## 🧪 Git 版本控制（手動）

```bash
# 回到上一個版本
git checkout HEAD^

# 建立回退分支
git switch -c fix-rollback-version

# 回 commit 並推送
git push origin fix-rollback-version
```

---

## 📦 附加服務（可擴充）

你可以額外整合以下服務：

- Redis
- phpMyAdmin
- Laravel Telescope / Horizon
- Mailpit / Mailhog

---

## ✅ 建議調整

- 若為生產環境，請考慮設定更嚴格的權限與環境變數
- 使用 `.env.production` 搭配 `.env` 切換設定檔

---

## 📜 License

MIT © 2025