besolab

# Hello Vuepress

https://vuepress.vuejs.org/ (opens new window) という静的サイトジェネレータを作成してサイト作成を行った時の手順について説明する．

# 環境構築

ホストOSによる違いが出るのは嫌だったのですべてdocker上で動作させる．

$ cat docker/Dockerfile

FROM node:13.12-alpine
ENV NODE_PATH /opt/node_modules

RUN apk update && apk add git

WORKDIR /workspace
ADD .yarnrc /workspace/.yarnrc
ADD package.json /workspace/package.json
RUN yarn install

ADD docs /workspace/docs
CMD ["yarn", "build"]
1
2
3
4
5
6
7
8
9
10
11
12
13
14

gitインストールしているのはvscodeのRemote-Containerでdockerイメージ内で作業する際にgitコマンドを直接入力できるようにするため．

TIP

@vuepress/plugin-last-updated (opens new window)を利用する場合はgitが必須．

内部でgitコマンドを叩いて最終更新日を取得しているため入っていないと動いてくれない． またファイルがgit管理対象に入っていないと更新されないので注意．

追加するファイルは.yarnrcとpackage.jsonの2種類．

まず.yarnrcでyarn installした時に/workspace/node_module/から/opt/node_modules以下にインストールされるように修正． 全ファイルをdocker -vでマウントする際にnode_modulesを上書きしないようにするためで，ちゃんと読み込まれるようにNODE_PATHも一緒に設定しておく．

$ cat .yarnrc

--modules-folder /opt/node_modules
1
2
3

またpackage.jsonでRUN yarn installでインストールされるパッケージのバージョンを固定．

$ cat package.json

{
    "scripts": {
        "dev": "yarn vuepress dev docs",
        "build": "yarn vuepress build docs",
        "debug": "node --nolazy --inspect-brk=9229 /opt/node_modules/.bin/vuepress dev docs"
    },
    "devDependencies": {
        "vuepress": "^1.4.0"
    }
}
1
2
3
4
5
6
7
8
9
10
11
12

ついでにコマンドをいくつか登録しておく．

  • ローカルサーバ起動(scripts.dev)
  • ビルド実行(scripts.build)
  • vscodeでのデバッグ実行用(scripts.debug)

またdocker-compose用のファイルも作成しておく．

$ cat docker-compose.yml

version: "3"

services:
  www:
    build:
      context: .
      dockerfile: docker/Dockerfile
    ports:
      - "8080:8080"
      - "9229:9229"
    volumes:
      - ".:/workspace"
    command: yarn dev
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

この時点でフォルダ構成は以下の通り．

<prj-root>/
├── package.json
├── .yarnrc
├── docker-comopse.yml
└── docker/
    └── Dockerfile
1
2
3
4
5
6

ビルドがうまくいくかこの時点で一度確認する．

docker-compose build
1

OKだったら次の作業へ．

# Tutorial

公式のチュートリアルが一番分かりやすいと思うが，作業手順としてやったことを残しておく．

各ファイルを配置するdocs/と，ジェネレートしたファイルを配置するbuild/を追加する．

<prj-root>/
├── package.json
├── .yarnrc
├── docker-comopse.yml
|── docker/
|   └── Dockerfile
|── docs/
|   |── index.md
|   |── about/
|   |   └── index.md
|   └── .vuepress/
|       └── config.js
└── build/
1
2
3
4
5
6
7
8
9
10
11
12
13

docs/index.mdとdocs/about/index.mdがジェネレート元のmarkdownファイルになる． 現時点では適当に作る(あとでしっかり書き直すこと)．

mkdir -p docs/about

echo "# Home" >> docs/index.md
echo "# About" >> docs/about/index.md
1
2
3
4

でdocs/.vuepress/config.jsがVuePressの設定ファイルとなる．

module.exports = {
    base: '/',
    dest: './build',

    title: '<your site title>',
    description: '<your site description>',
    locales: {
        '/': { lang: 'ja' },
    },
    themeConfig: {
        sidebar: 'auto',
        nav: [
            { text: 'Home', link: '/' },
            { text: 'About', link: '/about/' },
        ]
    },
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

それぞれ<something>となっている部分は適宜書き換えること．

ここまで出来たら一度テスト実行してみる．

docker-compose.ymlのservices.www.commandでyarn devが実行されるようにしているのでdocker-compose upするだけでローカルサーバが立ち上がる．

起動完了した旨のログが出力されたら http://localhost:8080 (opens new window) にアクセスして確認する，

# Githubへの自動デプロイ

生成したページをgithub上で公開する． githubユーザ用のページ https://your-github-id.github.io/ (opens new window) と，リポジトリ用のページ https://your-github-id.github.io/repository-name/ (opens new window) の2種類の方法がある．

今回は前者の方法をとり，さらに自ドメインからアクセスできるようにする．

更に，いちいち記事書いてbuildしてpushして．．．が面倒なので，developブランチにマークダウンファイルがpushされたら自動で公開までやってくれるようGithub Acions設定も行う．

# リポジトリ設定

最低限必要なのは以下の3つ．

  1. your-github-id.github.io というリポジトリを作成する
  2. Github Pages有効化
  3. リポジトリにpushするための公開鍵，秘密鍵を登録する

# リポジトリ作成

リポジトリ名を間違えないことに注意

# GithubPages有効化

リポジトリサイトから Settings(Tab) > Options(Left-Navigation) > Github Pages と移動し，Sourceをmaster branchにする． 以降 https://your-github-id.github.io/ (opens new window) にアクセスするとmasterブランチ以下のファイルを読み込んで表示される．

custom domain に自ドメインを登録すると https://your-domain/ (opens new window) に切り替わるが，自動デプロイ実行した際に設定が初期化されるのでここでは何もしない．

なおGithub Pages サイトのカスタムドメインを管理する (opens new window) のApexドメインを設定するを参考に，自ドメインにAレコードを幾つか登録しておくこと．

# 鍵登録

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""
1

出来上がった公開鍵(gh-pages.pub)と秘密鍵(gh-pages)をリポジトリサイトに登録する．

  • 公開鍵: Setting(Tab) > Deploy Keys(Left-Navigation) > Add deploy key
    • Titleは適当でよい(あとでなんの鍵か分かれば)
    • Keyに公開鍵の中身をコピペする
  • 秘密鍵: Setting(Tab) > Secrets(Left-Navigation) > Add new secret
    • NameはACTIONS_DEPLOY_KEYにする(actions内で参照する際に利用するので変えないように)
    • Valueは秘密鍵の中身をコピペする

# ソースコード設定

リポジトリ側の設定が終わったら，ソースコードの設定に移る． まずこれまで作成したファイルをdevelopブランチにpushしておく．

cd <prj-root>
git init
git remote add origin git://your-github-id.github.io

git branch develop
git checkout develop

git add .
git commit -m "first commit."
git push -u origin develop
1
2
3
4
5
6
7
8
9
10

次にgithub action用のファイルを追加する．

<prj-root>/
├── .github/
|   |── actions/
|   |   └── build/
|   |       └── Dockerfile
|   └── workflows/
|       └── vuepress.yml
|── static/
|   |── README.md
|   └── CNAME
...
1
2
3
4
5
6
7
8
9
10
11

.github/workflows/vuepress.ymlがAction実行フローが記載されたファイルで，.gihub/actions/build/Dockerfileがその中でビルドするために利用するファイル．

$ cat .github/workflows/vuepress.yml

name: CI
on:
  push:
    branches: [ develop ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Copy package
      run: cp ./package.json ./.yarnrc .github/actions/build
    - name: Build
      uses: ./.github/actions/build
    - name: Copy static files
      run: sudo cp -rf ./static/* ./build/
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v2
      env:
        ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
        EXTERNAL_REPOSITORY: matsuura0831/matsuura0831.github.io
        PUBLISH_BRANCH: master
        PUBLISH_DIR: ./build
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

ポイントはname: Copy packageと，name: Copy static filesの2箇所．

Copy packageでは.github/actions/build/Dockerfileのビルド用ファイルを同階層にコピーしている． ビルド時のディレクトリが.github/actions/build以下で行われる用で，../../../package.jsonで参照できなかったための苦肉の策．

Copy static filesではビルドしたファイルにstatic/以下のファイルをコピーしている． actions-gh-pagesでデプロイした場合，同階層内がごっそり置き換えられるため，README.mdやCNAME(リポジトリ設定のcustom domainを入力すると作られるファイル)も失われてしまう． これらファイルを混ぜ込むことで維持する用にしている． sudoをつけてるのはPermission Deniedで怒られたためで，なぜ必要かはちゃんと理解していない．

echo "# Blog" > static/README.md
echo "your-domain" > static/CNAME
1
2

.github/actions/build/Dockerfileも作成しておく．中身はdocker/Dockerfileと変わらない．

FROM node:13.12-alpine
ENV NODE_PATH /opt/node_modules

RUN apk update && apk add git

WORKDIR /workspace
ADD .yarnrc /workspace/.yarnrc
ADD package.json /workspace/package.json
RUN yarn install

CMD ["yarn", "build"]
1
2
3
4
5
6
7
8
9
10
11

ここまで完成したらpushして動作するか確認する．

git add .github
git add static
git commit -m "add auto deploy github action flow."
git push
1
2
3
4

適当にdocs/index.mdを弄ってビルドが成功するか確認する．

echo "# Home!" > docs/index.md
git add docs/index.md
git commit -m "github action test!"
git push
1
2
3
4

ビルド状況はgithubのリポジトリサイトのActionsタブから確認できる． 失敗していたら当該箇所の修正を行い，成功したら https://your-domain (opens new window) にアクセスして確認すること．

# VSCodeデバック実行

VuePressをカスタマイズするにあたりデバック実行ができるように環境を整える．

IDEとしてはVisual Studio Code(vscode) (opens new window)を利用する． またホストOSではなくdockerイメージ内で動作させるためRemote Development拡張 (opens new window)をインストールしておく．

上記が完了したら以下の手順でコンテナ内に入る．

  1. developブランチをvscodeで開く
  2. F1を押下して出た入力欄にRemote-Containers: Open Folder in Containerを入力
  3. どのコンテナを参照するか聞かれるので，ローカルのdocker-compose.ymlを指定する
  4. ビルドが走ってwindowが立ち上がり直したら完了

メニューのDebug > Run > Start Debuggingを押下した際にvuepressがデバック実行されるように設定を行う．

$ cat .vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Debug VuePress",
            "runtimeExecutable": "npm",
            "runtimeArgs": [
                "run-script",
                "debug"
            ],
            "port": 9229
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

あとはdocs/.vuepress/config.jsに適当にBreakpointを設置して，デバック実行すると止まってくれることを確認できればOK．

Last Updated: 2022/3/7 15:18:37