用 Envoy 現代化佈署 Laravel

SSL

1.需用SSH 你的 vps／server

2.假設你用github, 你vps/server 要經ssh 可進入 github

建立ssh key可參考此文章前半部： https://skychoy.com/posts/175-%E7%94%9F%E6%88%90ssh-key-%E4%B8%A6%E7%AE%A1%E7%90%86server-%E6%88%96-vps%E4%B8%AD%E7%9A%84docker

Envoy 是什麼

Envoy 可理解為簡易版的CI/CD

Envoy是Laravel 開發的，用來佈署Laravel當然很適合

Envoy 用Blade語法，適合Laravel使用者

即使你的項目不是Laravel 也可用來部署你的網站，比如我的next project 也是用Envoy來部署

1.安裝 Envoy

composer require laravel/envoy --dev

2. 設定本地與SERVER SSH

本地生成key

ssh-keygen -t rsa -b 4096 -C "your-email@example.com"

生成時可設定密碼短語加密，但用了後，每次使用這個key ssh server時都要再一次輸入密碼短語，但這樣相對安全，即使你這個文件被流出，別人也無法用來直接登入你的server

找到對應的位置，再執行 pbcopy

pbcopy < ~/.ssh/id_rsa.pub

登入server／vps 後把自己的key放入去

把第2步 pbcopy獲取到的一大段內容，取代下面的 your-public-key-content 不用懷疑，是很長的，很大段，開頭是 ssh-rsa 而結尾是你的電郵

echo "your-public-key-content" >> ~/.ssh/authorized_keys

如果報錯 No such file or directory 這句執行以下

mkdir -p ~/.ssh
chmod 700 ~/.ssh
touch ~/.ssh/authorized_keys
// 然後再執行上面的
echo "your-public-key-content" >> ~/.ssh/authorized_keys

// 如果每次登入仍要打user密碼,那麼請嘗試下面這一行
chmod 600 ~/.ssh/authorized_keys

嘗試登入

key_name 是你剛剛在本機建立的ssh key name your-username 是你ssh login server 的 username

ssh -i ~/.ssh/key_name your-username@your-server-ip

如果你 ssh port不是22，請用

ssh -i ~/.ssh/key_name your-username@your-server-ip -p 1234

1234改為你的ssh port

如手動，每次都需要上面這樣很煩，所以我們簡化一下日後的登入

去修改~/.ssh/config 如果沒有就建立

參考文件：本機的 ~/.ssh/config

Host myserver
    HostName 123.123.123.123. //ssh server
    port 22    // 如果是22可以不用這行，但如果不是不可在此更換
    User root   //server username
    IdentityFile ~/.ssh/key_name

我相信用SSH連server的朋友的會為不同server建立不同的ssh key？

但如果按照上面的~/.ssh/config 做法

ssh myserver
//就等同於
ssh -i ~/.ssh/key_name root@123.123.123.123

特別注意： 上面嘗試登入 那步驟一定要先做，否則加了去config也沒有用，無論如何都要先執行一次手動登入，才能用 ssh xxx 這些快捷登入

3. 登入server建立並添加公鑰到 GitHub

先登入到server

ssh myserver

建立ssh key

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

會彈出來名你建個名稱，假設名為github

copy公鑰

cat ~/.ssh/github.pub

把copy到的公鑰貼去GITHUB

1.將生成的公鑰（假設名為 ~/.ssh/github.pub）複製到 GitHub：

2.登錄到你的 GitHub 帳戶。

3.進入 Settings > SSH and GPG keys > New SSH key。

4.將公鑰粘貼到相應的欄位並保存。

chmod 600 ~/.ssh/github

文件參考：server上的 ~/.ssh/config

Host github.com
    User git
    IdentityFile ~/.ssh/github

測試 (建議要做，因為第一次要回應一個yes)

ssh -T git@github.com

見到這句就代表已成功登入了

Hi {Github Username} !  You've successfully authenticated, but GitHub does not provide shell access.

4. 參考文件 Envoy.blade.php

@servers(['web' => 'myserver'])

@setup
    $repository = 'git@github.com:username/someone.git';
    $app_dir = '/opt/apache/www/domain.com/public_html';
    $docker_dir = '/www/domain.com/public_html';
    $container_name = 'php8'; 
@endsetup

@story('deploy')
    prepare_directory
    clone_or_pull
    install_dependencies
    migrate
@endstory

@task('prepare_directory')
    echo 'Preparing directory...'
    mkdir -p {{ $app_dir }}
    sudo chown -R root:root {{ $app_dir }}

@endtask

@task('clone_or_pull')
    echo 'Cloning or pulling repository...'
    if [ -d {{ $app_dir }}/.git ]; then
        cd {{ $app_dir }}
        git pull origin main
    else
        git clone {{ $repository }} {{ $app_dir }}
    fi
@endtask

@task('install_dependencies')
    echo 'Installing dependencies...'
    docker exec -w {{ $docker_dir }} {{ $container_name }} composer install --no-interaction --prefer-dist
    sudo chown -R www:www {{ $app_dir }}
@endtask

@task('migrate')
    echo 'Running migrations...'
    docker exec -w {{ $docker_dir }} {{ $container_name }} php artisan migrate --force
@endtask

解釋一下：

因為上一步~/.ssh/config設定了連線，所以@servers(['web' => 'myserver'])就足夠

$repository 填寫你的git 對應的帳號及git name

$app_dir vps/server, 你網站的root path, 但要詳細的絕對路徑

$docker_dir因為我的案例是用docker運作PHP，對docker而言，路徑訪問不出外層的，所以由/opt 開始的路徑好像去不了？所以這樣填解決了我一個大坑

$container_name 如上，因為我是用docker，執行composer install時需要經docker 去執行，所以需要知道docker中 PHP 的容器名稱

執行

cd laravel_project
php vendor/bin/envoy run deploy

常見問題

1.建立SSH key時不一定自動是放 ~/.ssh/ 需要確定一下生成了在什麼位置，常見是應該存放在這

2.我是因為server中PHP經docker運作，所以composer路徑是個大坑，要注意

3.SSH登入時一般用root登入，但是apache等網頁server一般情況下是執行不了文件為root擁有人的文件，所以在 Envoy.blade.php 的 install_dependencies 這一步我做了 sudo chown -R www:www {{ $app_dir }} 把整個目錄都還給原本的 apache使用者，不一定是www 視乎你server個別設定

4.如上問題 Envoy.blade.php 的prepare_directory做了sudo chown -R root:root {{ $app_dir }} 把chown全設定為登入者相同的名稱，比如root，這樣才能繼續做下面的動作

5.建立ssh key時很多時都會設定個密碼短語，但如果在 Envoy 所用的SSH Key 我建議就不用設定，主要是因為...Envoy本來就是自動化佈署，但如果你的ssh key 有密碼短語，那麼你執行時幾乎每一步都要打一次密碼，一點也不自動，所以你自己可考慮一下是否需要短語

6.@task('xxxx') 至 @endtask 之間就是直接打 Linux command，所以需要對Linux command 有一定的基礎認知