Day 2 - 部屬

完成 CakePHP 基本概念的認識之後，接下來要建立實際的執行環境。

這一章會使用 Docker Compose 建立一套 CakePHP 開發環境，包含：

• Apache
• PHP 8.5
• MySQL
• phpMyAdmin
• Composer
• CakePHP 5.x

並完成 Apache Rewrite 設定與 CakePHP Database Configuration，讓 CakePHP 能夠正常運作並連接 MySQL。

1. CakePHP 執行需求

CakePHP 需要一個可以執行 PHP 的 Web Server。

教材使用：

Apache

CakePHP 也可以搭配其他 Web Server，例如：

nginx
Microsoft IIS

PHP 最低版本為：

PHP 8.2

教材使用：

PHP 8.5

另外需要安裝以下 PHP Extensions：

mbstring
intl
SimpleXML
PDO

資料庫方面，教材使用：

MySQL

CakePHP 也支援其他 Database Engine，例如：

MariaDB
PostgreSQL
Microsoft SQL Server
SQLite
Oracle

2. LAMP 與開發環境

傳統 PHP Web Development 常會看到：

LAMP

代表：

L = Linux
A = Apache
M = MySQL / MariaDB
P = PHP / Perl / Python

而 Windows 常見的：

XAMPP

則包含：

X = Cross Platform
Apache
MySQL / MariaDB
PHP
Perl

這次不直接在電腦中安裝整套環境，而是使用 Docker Container 建立需要的服務。

3. 準備檔案

開始前先準備：

Dockerfile
compose.yaml
.env
CMS/DB/cake_cms.sql

其中：

Dockerfile

負責建立 PHP + Apache Container。

compose.yaml

負責整合：

MySQL
Web Server
phpMyAdmin

等服務。

.env 則存放 Database 相關設定。

Dockerfile

教材中的 Dockerfile 以：

FROM php:8.5-apache

為基礎。

接著加入 Composer：

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

安裝需要的 PHP Extension 與 System Tool：

RUN apt-get update && apt-get install -y unzip zip git \
    libicu-dev libonig-dev libxml2-dev \
    && docker-php-ext-install intl mbstring pdo_mysql simplexml \
    && docker-php-ext-enable intl mbstring simplexml

設定工作目錄：

WORKDIR /var/www/html

啟用 Apache Rewrite Module：

RUN a2enmod rewrite

設定檔案擁有者與權限：

RUN chown -R www-data:www-data /var/www/html

最後讓 Apache 保持在前景執行：

CMD ["apachectl", "-D", "FOREGROUND"]

這個 Container 就會成為我們執行 CakePHP 的 Web Server。

compose.yaml

Docker Compose 會建立多個 Service。

教材中主要有：

mysql
web
phpmyadmin

三個服務。

MySQL Service

MySQL 使用：

image: mysql:latest

並透過環境變數取得：

MYSQL_ROOT_PASSWORD
MYSQL_DATABASE
MYSQL_USER
MYSQL_PASSWORD

Database Data 會透過 Volume 保存：

mysql-data:/var/lib/mysql

另外：

./CMS/DB:/docker-entrypoint-initdb.d

可以讓 MySQL 啟動時讀取準備好的 SQL 檔案。

教材也加入 Healthcheck：

healthcheck:
  test: [ "CMD", "mysqladmin", "ping", "-h", "localhost" ]
  interval: 10s
  timeout: 1s
  retries: 4

讓其他 Container 可以等待 MySQL 正常啟動後再開始工作。

Web Service

Web Service 使用前面的：

Dockerfile

建立 PHP + Apache Container。

對外 Port：

ports:
  - "8080:80"

因此 Browser 可以透過：

http://localhost:8080

存取 Apache。

專案資料夾：

volumes:
  - ./CMS:/var/www/html

會掛載到 Container 中：

/var/www/html

phpMyAdmin

教材也建立：

phpMyAdmin

用來管理 MySQL。

設定：

PMA_HOST: mysql
PMA_USER: ${MYSQL_USER}
PMA_PASSWORD: ${MYSQL_PASSWORD}
PMA_PORT: 3306

對外使用：

ports:
  - "8081:80"

因此可以透過：

http://localhost:8081

開啟 phpMyAdmin。

.env

教材中的 Database 設定如下：

MYSQL_HOST=mysql:3306
MYSQL_ROOT_PASSWORD=CakePHP-Password
MYSQL_DATABASE=CakePHP-DB
MYSQL_USER=CakePHP-User
MYSQL_PASSWORD=CakePHP-Password

這些資料會提供給：

MySQL
Web Container
phpMyAdmin

共同使用。

後面設定 CakePHP Database Connection 時，也必須與這裡的內容一致。

4. 建立 Container

完成檔案準備後，在 Terminal 執行：

docker compose up --build

如果希望 Container 在背景執行，可以使用：

docker compose up --build -d

Compose 會依照設定建立：

CakePHP-mysql
CakePHP-php8.5-apache2
CakePHP-phpmyadmin

等 Container。

5. 進入 PHP Container

開啟新的 Terminal：

docker exec -it CakePHP-php8.5-apache2 bash

這樣就會進入 PHP + Apache Container。

接著使用 Composer 建立 CakePHP 5.x 專案：

composer self-update && composer create-project --prefer-dist cakephp/app:5.* CMS

下載完成後：

cd CMS

即可進入 CakePHP Application。

教材示範也可以執行（若不是使用 Docker 開發的話使用）：

bin/cake server -p 8080

啟動 CakePHP Built-in Server。

成功時會看到類似：

Welcome to CakePHP v5.4.1 Console

App : src
Path: /var/www/html/CMS/src/
DocumentRoot: /var/www/html/CMS/webroot

這代表 CakePHP 的基本結構已經完成。

6. Apache 403 Forbidden

在透過 Apache 開啟專案時，可能會看到（正常照步驟部屬不須手動修改）：

403 Forbidden

教材指出，這通常與 Apache 對：

/var/www/html

的 Override Permission 有關。

此時需要修改 Apache Configuration。

修改 Apache Override

在 VS Code 中按：

F1

輸入：

Dev Containers: Attach To Running Container

選擇：

CakePHP-php8.5-apache2

進入：

/etc/apache2

並開啟：

apache2.conf

如果不小心切換到錯誤 Workspace，可以使用：

Ctrl + K

放開後再按：

F

關閉目前資料夾。

修改 apache2.conf

原本可能有：

<Directory /var/www/>
    Options Indexes FollowSymLinks
    AllowOverride None
    Require all granted
</Directory>

加入：

<Directory /var/www/html>
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

最重要的是：

AllowOverride All

它允許 /var/www/html 中的設定被覆寫。

CakePHP 使用 Apache 時，Rewrite 設定會需要這項設定。

修改後儲存檔案。

重新啟動 Apache Container

修改 Apache Configuration 後執行：

docker restart CakePHP-php8.5-apache2

Container 重啟後，再重新開啟 Browser。

教材畫面中，403 問題排除後，Apache 會顯示 /var/www/html 下的目錄內容，包含建立完成的 CMS 專案。

7. Linux File Permission

部署過程中也會碰到 Linux File Permission。

Linux 權限主要分為：

Owner
Group
Others

每一組可以有：

Read
Write
Execute

權限。

數字表示：

Read    = 4
Write   = 2
Execute = 1

例如：

755

可以拆成：

7 = Read + Write + Execute
5 = Read + Execute
5 = Read + Execute

因此：

Owner  → rwx
Group  → r-x
Others → r-x

教材中也使用：

RUN chmod -R 755 /var/www/html
RUN chown -R www-data:www-data /var/www/html

設定 Web Application 的權限與擁有者。

8. CakePHP Check Page

CakePHP 安裝完成後，可以進入：

CMS

查看 CakePHP 的 Check Page。

CakePHP 會檢查：

PHP Environment
File Permission
Database Connection

等項目是否符合要求。

此時通常會看到 Database Connection 尚未完成。

Database Connection Error

教材中的 CakePHP Check Page 顯示：

CakePHP is NOT able to connect to the database.

也就是 CakePHP 雖然已經啟動，但尚未正確連接 MySQL。

原因是 CakePHP 預設的 Database Configuration 還沒有配合 Docker Compose 修改。

修改 app_local.php

開啟：

CMS/CMS/config/app_local.php

找到：

'Datasources'

中的：

'default'

設定。

修改為：

'Datasources' => [
    'default' => [
        'host' => 'mysql:3306',
        'username' => 'CakePHP-User',
        'password' => 'CakePHP-Password',
        'database' => 'CakePHP-DB',
        'url' => env('DATABASE_URL',null),
    ],
],

這裡的設定必須與：

.env

中的 Database 設定一致。

為什麼 host 是 mysql？

這裡：

'host' => 'mysql:3306'

使用：

mysql

不是：

localhost

因為在 Docker Compose 中，MySQL Service 的名稱就是：

mysql:

Web Container 與 MySQL Container 都位於同一個 Docker Network：

lamp-networks

所以 CakePHP 可以使用 Service Name：

mysql

找到 Database Container。

教材的 Database Configuration 即使用這個設定。

確認 Database Connection

儲存：

config/app_local.php

後重新整理 Browser。

如果設定正確，CakePHP Check Page 中的 Database 區塊會從：

CakePHP is NOT able to connect to the database.

變成：

CakePHP is able to connect to the database.

這就是成功連線後的結果。

9. 完整部署流程

整個部署流程可以整理成：

準備 Dockerfile
      ↓
準備 docker-compose.yaml
      ↓
設定 .env
      ↓
docker compose up --build
      ↓
建立 PHP / Apache / MySQL / phpMyAdmin
      ↓
Composer 安裝 CakePHP
      ↓
修改 Apache AllowOverride
      ↓
重新啟動 Container
      ↓
開啟 CakePHP Check Page
      ↓
修改 config/app_local.php
      ↓
連接 MySQL

10. Day 2 重點整理

完成這一章後，應該能理解：

Docker Compose

使用多個 Container 組成完整的 Web Development Environment。

Apache + PHP
MySQL
phpMyAdmin

Apache

提供 HTTP Web Server，並透過：

AllowOverride All

讓 CakePHP Rewrite 設定能夠正常工作。

Composer

用來建立 CakePHP Application：

composer create-project --prefer-dist cakephp/app:5.* CMS

MySQL

由 Docker Compose 建立 Database Service。

CakePHP 使用：

'host' => 'mysql:3306'

與 Database 連線。

app_local.php

CakePHP 的 Database Connection Configuration 位於：

config/app_local.php

其帳號、密碼與 Database Name 需要與：

.env

設定一致。

下一步

完成 CakePHP 的執行環境與 Database Connection 後，我們已經具備建立 Web Application 的基本環境。

接下來就可以正式進入 CMS 實作，開始建立：

ArticlesTable
Article Entity
ArticlesController
Templates

並逐步完成：

Create
Read
Update
Delete

也就是 CakePHP CMS 的基本文章管理功能。