2022.06.20

Amazon LightsailとVisual Studio Codeでロックインされないナレッジベースを作る

yassan

最近は柴犬を飼いたく、いつのタイミングで飼おうか、どこで柴犬を受け取ろうか考えてしまいます。やっさんでございます。

本エントリーでは、Amazon LightsailとVisual Studio Codeを利用したナレッジベースの構築について紹介します。

Contents

最初にまとめ
ナレッジベース、皆さんは何を使ってらっしゃいますか？
1. 技術的知見のアウトプットベースとして活用するナレッジベース
LightsailとVisutal Studio Codeを利用したナレッジベースのアーキテクチャ
1. アーキテクチャ図の説明
Amazon Lightsailを選ぶ理由
git-o-maticによるGitHubとの自動同期の実現
1. git-o-maticによる自動同期の具体的な方法
MKDocsによるブラウジング環境
Amazon LightsailとVisual Studio Codeによるロックインされないナレッジベースのメリットとは
トレードオフはあるの？
最後のまとめ
参考リンク

最初にまとめ

最初に、本記事で書いていることをまとめます。

ナレッジベースのサービスにロックインされないナレッジベースを構築する方法をご紹介します。
個人向けのナレッジベースです。
Amazon Lightsailを使って月額3.5ドルで運用できます。
Visual Studio Codeをエディターとして使うことができます。
フォーマットはMarkdownであるため、他のナレッジベースのサービスに転記や移行が簡単にできます。

ナレッジベース、皆さんは何を使ってらっしゃいますか？

当社はナレッジベースにesaを利用しておりまして、技術的知見はもとより議事録や自己紹介など、様々なドキュメントに利用されています。

技術的知見のアウトプットベースとして活用するナレッジベース

技術的知見のアウトプットと言いましても、コマンドの切れ端だけであったり、数百文字の手順であったりと、そのレベル感は様々です。ナレッジにはクレデンシャル情報などセンシティブな情報が含まれる場合もあり、共有できる段階になるまでには段階が発生することもあります。

そこで、ロックインされない個人的なナレッジベースを作成して知識の展開をいつでもできるよう準備することをおすすめいたします。私がアウトプットしたものの中には、 ゼルダの伝説ブレスオブザワイルド攻略 といったエンジニア路線ではないものも含まれますが、More Funを掲げる当社では好評でした。

LightsailとVisutal Studio Codeを利用したナレッジベースのアーキテクチャ

アーキテクチャ図を紹介します。

アーキテクチャ図を見ていただくと分かります通り、難易度が高いことは行っておりません。以下の前提知識は必要にはなります。

SSH
サーバーのサービス
Git
Docker
Nginx
MKDocs

アーキテクチャ図の説明

ユーザーはAmazon Lightsailに保存しているドキュメントにVisutal Studio CodeのRemote SSHエクステンションを利用してアクセスし、コンテンツを作成・更新します。
コンテンツはgit-o-maticを利用してGitHubのPrivateリポジトリと自動同期します。
コンテンツを定期的にNginxのディレクトリと同期します。
MKDocsの静的コンテンツが配置されたNginxのWebサーバーにアクセスしナレッジベースを閲覧します。

Amazon Lightsailを選ぶ理由

小規模のナレッジベースですと1ユーザー5ドル前後となり、そこまで価格的に優れているわけではありません。では何故、Amazon Lightsailを選んだのか。それは、エンジニアの技術的探究心を満たしてくれるからです。サーバーを保持できるため、技術的知識の向上やモチベーション維持に繋がります。

git-o-maticによるGitHubとの自動同期の実現

このアーキテクチャを実現する上で重要なのが、GitHubのプライベートリポジトリへのバックアップです。今回はgit-o-maticを利用しています。git-o-maticはGo言語で実装されていて、Gitリポジトリを監視し変更を自動的にプル＆プッシュする機能を持ちます。

git-o-maticによる自動同期の具体的な方法

まず、Amazon Lightsailの仮想マシンで以下の共通的な手順を実施する必要があります。

公式サイトからgit-o-maticのバイナリをダウンロードする。
GitHubのリポジトリにSSH接続できるようセットアップを行う
ナレッジベース用のリポジトリをSSHオプションでクローンする
ナレッジベースリポジトリのGitユーザーとメールアドレスを設定する

上記のセットアップを行った後に、git-o-maticを定期的に実行するスクリプトを用意します。
私は以下のスクリプトを作成しました。Amazon Linux2前提となっております。

#!/bin/sh

/home/ec2-user/gitomatic/gitomatic \
-interval 5m -author "xxxxxxx" -email "xxxxxxxxx@xxxxx.xxx" \
-privkey /home/ec2-user/.ssh/xxxxxxxxxxxxxx /home/ec2-user/tech/xxxxxx

次に、作成したスクリプトを自動的に起動するためのサービス定義を作成します。
私は以下のようにサービス定義を作成しました。

[Unit]
Description=gitomatic_issues
After=network.service

[Service]
Type=simple
Restart=on-success
ExecStart=/home/ec2-user/tech/xxxxxx/script/script_files/gitomatic_amazon_linux2.sh
User=ec2-user

[Install]
WantedBy=multi-user.target

そして、以下のようにsystemctlコマンドを実行してgit-o-maticサービスを有効化しました。

sudo systemctl start gitomatic_xxxxxx.service

その後、git-o-maticサービスが正常に起動していることを以下のコマンドを使って確認します。

sudo systemctl status gitomatic_xxxxxx.service

以上のgit-o-maticのセットアップが完了すると、自動的に変更をGitHubにプッシュしてくれるようになります。これで、バックアップ体制は万全です。

MKDocsによるブラウジング環境

git-o-maticのセットアップが完了すれば、実用に耐えられる個人用ナレッジベースは完成しておりますが、ブラウジング用としてNginxサーバーにMkDocsでビルドしたナレッジベースを配置します。

詳細は割愛しますが、以下の手順を実施する必要があります。

MkDocsのドキュメントをビルドする環境をAmazon Lightsailにセットアップします。今回はビルドにDockerを利用しました。
静的コンテンツをMkDocsでビルドし、Nginxの所定ディレクトリに配置するシェルスクリプトを作成します。
シェルスクリプトをcronで定期実行します。
今回は個人用のナレッジベースのためNginxはBasic認証をかけ、複雑なパスワードを用いて他人には見られないようにします。

シェルスクリプトは以下のような内容です。

#!/bin/sh

# copy contents
echo copy contents
cp -pr /home/ec2-user/tech/xxxxxx/* /home/ec2-user/tech/xxxxxx-mkdocs/docs/issues/
echo $?

# build
echo build
cd /home/ec2-user/tech/xxxxxx-mkdocs && /usr/bin/docker run --rm -v ${PWD}:/docs squidfunk/mkdocs-material build
echo $?

# copy to nginx
echo copy to nginx
sudo cp -pr /home/ec2-user/tech/xxxxxx-mkdocs/site/* /usr/share/nginx/html/
echo $?

以上のセットアップによりブラウジング環境のセットアップが完了しました。

Amazon LightsailとVisual Studio Codeによるロックインされないナレッジベースのメリットとは

1. どこからでもアクセス可能

ナレッジベースと言っていますが、その実態はGitのリポジトリをどこで管理しているかだけになります。リモートサーバーに置けばどこからでもアクセス可能となり、ローカルに置けば手元のPCだけでアクセスできます。

2. Visual Studio Codeという人気のエディタを使うことができる

Visual Studio CodeのRemote SSHエクステンションを利用してリモートのコンテンツを編集しますので、豊富なエクステンションや優秀な検索機能を持つエディタをフルに活用することが出来ます。

3. Markdownであるため、転記や移行が簡単

ナレッジベースとしていますが、使い方は様々です。上記のスクリーンショットのようにブログの下書きを書くために使うことも可能です。Markdownのフォーマットであるため、他のサービスへの転記も容易です。まだどのナレッジベースを使うか決めかねている方は是非とも、本ナレッジベースを試していただければと思います。