kokoni

クラウドおじさんの備忘録

Re:VIEWとAzure DevOpsで技術同人誌を執筆するためのCI/CD環境を構築する その1

技術書典8が昨今の状況により開催中止になり意気消沈している最中に、とある勉強会で技術同人誌の執筆環境について話をしたら、面白いのでブログに投稿したほうがいいと助言を受けたので備忘も兼ねて記載します。

技術同人誌を執筆する時に便利なのが「Re:View」というrubyで作成された書籍作成支援ソフトウェアです。 ある程度の環境設定が出来てしまえば執筆することに専念できるので非常に便利です。

github.com

review-knowledge-ja.readthedocs.io

ちなみに執筆にはVS Codeを利用しています。 VS Code用のRe:VIEWのExtensionも有志によって提供されています。

azure.microsoft.com

marketplace.visualstudio.com

Re:VIEWの記述フォーマットについてはいつも下記を参考にしています。

github.com

PDFやEPUB形式に出力できるのも魅力なのですが、出力を行うためにはrubyの実行環境を構築する必要があります。 私の環境はだいたいWindowsベースなのでWindows向けの環境構築をするのですが、環境構築ではまりたくないのでDockerを使うことをお勧めします。

Docker Hubに有志によって作成されたRe:VIEW用のコンテナが用意されているのでこちらを利用しましょう。 WSL(Windows Subsystem for Linux)を使ったりRubyインストールしなくて済むのでラクチンです。

github.com

Windwow10 Proを利用しているとHyper-Vの利用を求められるのでHyper-Vを利用したくない環境ではすこし煩わしいです。 また、複数端末を持っている時に端末毎に環境構築するのもこれまためんどうなのでクラウドの力を借りることにします。 ということで、ここではAzure DevOpsを利用してRe:VIEWの執筆効率を高めるための環境構築について説明します。

Re:VIEWの設定方法や利用方法についてはここでは説明しません。あらかじめ設定および作成が完了していることが前提になります。

※本投稿は2020年3月28日時点での情報になります。

Azure DevOpsでCI/CD環境の構築

なぜAzure DevOpsの利用を選択したかというと私が仕事でもプライベートでもよく使うDevOpsツールだからです。 Re:VIEWでよく使われてるのはCircle Ciのようです。

Azure DevOpsにアクセスしてプロジェクトを作成しましょう。 今回はAzure ReposとAzure Pipelinesを利用します。

前提作業としてAzureとDockerHubも利用するので両方のアカウントも作成してください。

hub.docker.com

azure.microsoft.com

Azureのアカウントを作成したらリソースグループとAzure Storageを作成しておいてください。 作成の方法は下記のリンクが参考になります。

docs.microsoft.com

docs.microsoft.com

Azure DevOpsの作成

Azure DevOpsを作成していない方は下記にアクセスして作成してください。

azure.microsoft.com

f:id:kingkino:20200328104635j:plain 作成を始めると下記のような画面が表示されるのでContinueを押してください。

f:id:kingkino:20200328104638j:plain 組織名の作成と作成するリージョンを選択します。 組織名は任意に設定してください。

f:id:kingkino:20200328104641j:plain 作成するプロジェクト名と公開・非公開を設定します。 プロジェクト名は任意に設定してください。

f:id:kingkino:20200328104644j:plain 下記の画面が表示されたらDevOpsの作成は完了です。

Azure Reposの作成

Re:VIEWで作成したファイルをAzure Reposで管理します。 Azure ReposのベースはGitなのでGitに慣れている人であれば問題なく操作可能だと思います。 ここでは詳細な利用方法については割愛しますので下記のリンクを参考にしてください。

docs.microsoft.com

Variable Groupの設定

ここではセキュアな情報を管理するための方法について説明します。 Pipelineに直に接続文字列等のセキュアな情報を記載するとセキュリティ事故につながる可能性があるので、そういった情報は Variable Groupsという機能で管理することができます。

f:id:kingkino:20200328134925p:plain

PipelinesのLibraryからVariable Groupsの作成を行います。 作成したら図のようにVariable Group NameとVariablesを設定してください。 ここではAzureStorageへの接続用の名称とKeyを設定しています。 VaribalesのNameは任意の文字列にしてください。

Azure Storageの名称とKeyの取得方法は下記のリンクを参考にしてください。

docs.microsoft.com

ServiceConnectorの設定

ここではAzureとDockerHubに接続するための設定方法について説明します。 外部サービスにアクセスするためには外部接続用の情報を管理する必要があります。 ここではAzureとDockerHubに接続するための接続情報を作成します。

f:id:kingkino:20200328140756p:plain

左シテにあるProject SettingsからService Connectionsを選択します。

Dockerの接続作成

Dockerの接続情報の作成を行います。 右上にある「New Service Connection」を選択して作成していきます。

f:id:kingkino:20200328140146p:plain

検索ボックスにdockerと入力して検索結果に出てくる「Docker Registry」を選択します。

f:id:kingkino:20200328140150p:plain

Dockerに接続するために必要な情報を入力します。 RegistryTypeをDockerHubにして先に作成しておいたDockuer IDとDocker Passwordを入力します。

入力項目で接続可能かVerifyを押して確認してみましょう。Verification Succeededと表示されれば成功です。 もしエラーが表示されたらDockerHubのアカウントの見直しをしてください。 最後にService Connections nameに任意の名称を入力してVerofy and saveを押して完了です。

Azureの接続作成

Azureの接続情報の作成を行います。 右上にある「New Service Connection」を選択して作成していきます。

f:id:kingkino:20200328140153p:plain

検索ボックスにazureと入力して検索結果に出てくる「Azure Resource Manager」を選択します。

f:id:kingkino:20200328140156p:plain

Azure Service Connectionで「Service Principak(automatic)」を選択してください。

f:id:kingkino:20200328140449p:plain

Azureの接続情報を入力していきます。 Scope levelはSubscriptionを選択してください。

Subscirpitonでは先に作成したSubscriptionを選択します。 ここでAzureへのログインを要求されるのでログインを行ってください。

次にResourceGroupを要求されるので、先に作成したResourceGroupを選択してください。 最後にService Connections nameに任意の名称を入力してsaveを押して完了です。

Pipelineの設定

もろもろの設定が完了したらいよいよPipelineの作成に入ります。

f:id:kingkino:20200328150053p:plain

左のメニューからPipelinesを選択して「New pipelines」を選択します。

f:id:kingkino:20200328150057p:plain

リポジトリの選択が要求されるので、ここではAzure Repos Gitを選択してください。

f:id:kingkino:20200328150100p:plain

先に作成したRepositoryが表示されると思いますので選択してください。

f:id:kingkino:20200328150104p:plain

Pipelineの種別の選択をします。ここでは「Starter Pipeline」を選択してください。

f:id:kingkino:20200328150108p:plain

デフォルトのYAMLが表示されますがここでは編集をせずに「Save and run」で保存してください。 実行も行われるのでもし何かしらの事由でエラーが起きた場合はPipelineの一覧でエラーが表記されます。

f:id:kingkino:20200328150111p:plain

無事に作成されるとRepositoryのほうに「azure-pipelines.yml」が追加されます。 Pipelineのyamlファイルもリポジトリで管理されます。

Pipelinesの編集

Pipelinseが作成できたら次にyamlファイルの編集を行います。

f:id:kingkino:20200328151321p:plain

Pipelinesの一覧から対象のPiplinesを選択してEditを選択します。 YAMLの編集画面が表示されるので下記のソースをコピペして上書きしてください。

YAMLはインデントでスクリプトを管理するのでコピペミスをするとエラーになります。 上書きしてエラーが出たときはインデントを確認してください。

※Service ConnectorやVaribles Groupを任意の名称で作成した場合は個別に変更してください。

trigger:
  branches:
    include:
      - master
  # 変更検知から外したいファイルの設定
  paths:
    exclude:
    - azure-pipelines.yml

resources:
  - repo: self
  
# LibraryのVariableGroups設定
variables:
  - group: Techbook8Settings
  
stages:
  - stage: Build
    displayName: TechBook08
    jobs:
      - job: Build
        displayName: MakePDF
        pool:
          vmImage: "ubuntu-latest"
        steps:
          # ここではDockerHubからRe:VIEWのDockerをPullしてPDF出力のコマンドを実行します
          - task: DockerCompose@0
            displayName: Make-PDF
            inputs:
              containerregistrytype: "Container Registry"
              # service connectorで作成したDockerHub接続情報
              dockerRegistryEndpoint: "DockerHub"
              action: "Run a Docker Compose command"
              dockerComposeCommand: "run --rm review rake pdf"
              imageDigestComposeFile: 'vvakame/review'
              detached: false
              qualifyImageNames: true
              abortOnContainerExit: false
          # ここではAzure Storageに出力したPDFをアップロードします
          - task: AzureCLI@2
            inputs:
              # service connectorで作成したAzure接続情報
              azureSubscription: "Azure"
              scriptType: "bash"
              scriptLocation: "inlineScript"
              # azコマンドによるAzureStorageへのアップロードを行います
              # --fileで指定するpdfファイルのパスはフォルダ構成によってかるので環境庭せて変更してください
              # -cで選択するコンテナは予めAzure上に作成しておいてください
              # $(storageKey) $(storageName) はVariblesで設定したNameを指定します
              inlineScript: 'az storage blob upload 
              --file ./book08/AzureHodgepodgeVol.02.pdf 
              -c techbook 
              --account-key $(storageKey) 
              --account-name $(storageName) 
              --name techbook08.`date "+%Y%m%d_%H%M%S"`.pdf'

編集が完了したら右上の「Run」を選択してPipelinesを実行します。

f:id:kingkino:20200328151706p:plain

f:id:kingkino:20200328151834p:plain

Pipelinesの一覧でJobの実行ステータスが確認できます。

f:id:kingkino:20200328152042p:plain

問題なく実行が完了したら図のようにステータスがオールグリーンになります。 もしステップのどこかでエラーが発生したらその箇所でエラーステータスになるのでログを確認してください。 また、エラーの時は登録されているユーザにメール通知もされます。

Azureで確認

生成されたPDFがAzrue Storageに正常にアップロードされているか確認します。 確認方法としてはAzure Storage Explorerのようなクライアントツールを使うかAzure Portalで確認をする方法があります。 ここではAzure Storage Explorerを使った確認方法を説明します。

Azure Storage Explorerをインストールしていない方は下記からインストールしてください。

azure.microsoft.com

Azure Storage Explorerをインストールしたら各種設定を行います。

f:id:kingkino:20200328154413p:plain

左上にあるコンセントのアイコンを選択して接続方法を選択します。

f:id:kingkino:20200328154417p:plain

ここではAzureを選択してログインによるアクセストークンでの接続方法を実施します。 Azureを選択したら表示されるURLにアクセスし、表示されているコードを入力します。 Azureへのログイン画面が表示されるのでログインを行い暫くするとAzure Storageにログインユーザに紐づくサブスクリプションがすべて表示されます。

f:id:kingkino:20200328154419p:plain

対象となるAzureStorageを選択してコンテナの中を確認してみましょう。 作成されたPDFがアップロードされていることが確認できると思います。 このツールでダウンロードすることもできるのでダウンロードしてPDFの中身を確認してみてください。

ちょっと長くなりましたがこれでRe:VIEWのCI/CD環境の構築が出来ました。 次回はAzure StorageにアップロードされたPDFをSlackに通知する仕組みについて説明をします。

blog.kokoni.jp