sphinx+jenkins+gitでドキュメントサーバを建てた

背景

ドキュメントを作成したが、notesDBやexcelで保管しても参照が難しい
- 検索難
- よって見られない
git+sphinx+jenkins+nginxでドキュメントサーバを立てたので備忘録的に残す
リモートレポジトリにpushしたのを検知して、自動でsphinxがhtmlを作成し、公開する

用意するもの

git
sphinx
jenkins
nginx
サーバ(今回はVM上のubuntu)

各ソフトの導入

割愛
git,sphinxはローカルマシンにもインストールする

[サーバ]sphinx

.rstファイルや.mdファイルをhtmlに変換するビルドツール
インストールされてればOK

sudo apt-get install python-pip
pip install sphinx
pip install recommonmark=='0.4.0'

[サーバ]git

ドキュメントを管理するためにレポジトリ
- なるべくルートディレクトリに近いディレクトリにgit用のディレクトリを作る

sudo mkdir /repo

作成したディレクトリの実行権限等をユーザにする

sudo chown -R usr /repo
sudo chgrp -R usr /repo

レポジトリ用のディレクトリを作成し、初期化

cd /repo
mkdir ProjectName.git
cd ProjectName.git
git init --bare --share

[ローカル]プロジェクトの準備

sphinx+gitでドキュメントを作成する
プロジェクトのディレクトリを作成

mkdir ProjectName
cd ProjectName

gitで初期化

git init

sphinxのディレクトリ構成を作成

sphinx-quickstart

途中聞かれる質問にお好みに答える
- sourceとbuildは分ける
sourceディレクトリ以下に参照したいドキュメントを追加する
- デフォルトでは、rst記法のみに対応している
Makefileがあるディレクトリに移動して、以下のコマンドを実行

make html

上記のコマンドが正常に終了していれば、buildディレクトリが生成され、htmlディレクトリ以下に変換後のドキュメントが格納される
commit→リモートレポジトリにpush

git add .
git commit -m "First Commit!"
git remote add origin ssh://[ログインユーザ]@[IP]:[ポート番号]/repo/ProjectName.git
git push origin master

[サーバ]リモートレポジトリから公開ディレクトリへファイル移動

サーバ上のレポジトリから、htmlを作成する
作業用ディレクトリを作成

mkdir /work/
cd /work/

cloneしてhtmlを作成

git clone /repo/ProjectName.git
cd ProjectName
make clean html

結果、build/htmlにhtmlができていることを確かめる
- nginxの公開ディレクトリにコピーすれば公開完了
- 手動でもいいが、面倒なのでjenkinsを用いて自動化する

[サーバ]jenkins

インストール方法は割愛
- ローカルマシンからブラウザでjenkinsが見れる状態を想定
以下の様なシェルスクリプトを作成
- 引数にProjectNameを与えることで、git clone or git pullを実行し、htmlをビルドする
- /work/script/MakeRepo.shとして作成

#//bin/sh
WORK_DIR=/work
BUILD_DIR=/work/$1/build/html

echo "check dir:"$1

 if [ -e $WORK_DIR/$1 ]; then
        cd $WORK_DIR/$1
        git pull
 else
        cd $WORK_DIR
        git clone /repo/$1.git
        cd $WORK_DIR/$1
 fi

 make clean html

このシェルスクリプトをjenkinsに登録する

f:id:crewfanq:20160531180517p:plain

この場合、プロジェクト名はdocumentとしている
あとはプロジェクト名等をわかるように設定してジョブを作成する
作成したjobをjenkinsのインターフェースからkickして、htmlが作成されるか確かめる

ls /work/ProjectName/build/html

作成したジョブによってリモートレポジトリからhtmlを作成するところまで、自動化できた
- ドキュメントのリモートレポジトリが更新されたタイミングで、このジョブが実行できるようにしたい

[サーバ]git pushを検知して、jenkinsのジョブを実行する

jenkinsのインターフェースから、先ほど作成したジョブの設定を表示する
- 中腹にあるビルドトリガの"リモートからビルド"にチェック
- 認証トークンを任意に決める
- この設定により、該当URLにGETするだけでジョブが実行するようになった
git push時にジョブが実行されるようにする
- /repo/ProjectName.git/hooks/post-updateを作成する

cp /repo/ProjectName.git/hooks/post-update.sample /repo/ProjectName.git/hooks/post-update

"exec git update-server-info"の前にいかのコマンドを記述

wget --spider --auth-no-challenge --http-user=[jenkins-username] --http-password=[jenkins-password] http://[HOST]:[ポート番号]/job/document-sphinx-autobuild/build?token=documentjobtoken&cause=git-push

この設定によって、git push時に、jenkinsのジョブが実行される

nginx

公開サーバの設定をする
- 社内向けの設定を想定しているので、最低限
- listen:ポート番号、server_name:IP
- /etc/nginx/site-enable/sphinx

 server {
      listen 5000;
      server_name 0.0.0.0:;

      root /work/document/build/html;
      index index.html;
      location /{
              auth_basic "Restricted";
              auth_basic_user_file /etc/nginx/.htpasswd;
      }

 }

作成後、ファイルをコピー

sudo ln -s /etc/nginx/site-available/sphinx /etc/nginx/site-enable/sphinx

アクセスを制限したいので、Basic認証を利用
- インストール

sudo apt-get install apache2-utils

ユーザ名、パスワードの設定

$ sudo htpasswd -c /etc/nginx/.htpasswd username
New password: password
Re-type new password: password
Adding password for user username

この設定によってページアクセス時にusername/passwordの入力を求められる。
nginxの設定ファイルの文法を確認

sudo nginx -t

nginxの起動

sudo systemctl start nginx
sudo systemctl enable nginx

設定したIP,ポート番号にアクセスすると、nginxが起動していることがわかる
- ブラウザからアクセスすると、site-enable/sphinxに設定したindex.htmlが見れるはず

crewfanqのlog

いろんな備忘録的な

sphinx+jenkins+gitでドキュメントサーバを建てた

背景

用意するもの

各ソフトの導入

[サーバ]sphinx

[サーバ]git

[ローカル]プロジェクトの準備

[サーバ]リモートレポジトリから公開ディレクトリへファイル移動

[サーバ]jenkins

[サーバ]git pushを検知して、jenkinsのジョブを実行する

nginx