Monthly Archives: 5月 2017

2017-05-23

『Mastodon』の概略と、サーバ構築方法について

インフラ担当Mです。

今回は4月初旬からにわかに話題になり始めた『Mastodon』の概略と、サーバ構築方法についてです。

世界的にはTwitterやFacebook、国内ではLINEを始めとして、
ここ10年ほどで急速にソーシャルネットワークサービスが社会に普及したことは
皆さんもご存じの通りかと思います。

ですが普及と共に、その問題点も浮き彫りとなってきました。
例えば以下のようなポイントです。

  1. 運営ポリシーの不透明さからくる、アカウント凍結や削除への不信感
  2. 企業運営であるが故のマネタイズから逃れられないこと。またその難しさ。
  3. グローバル展開に伴う、社会倫理や法律の差異から生じる軋轢
  4. サービスの継続性が運営企業の運営方針、運営状態と紐付いてしまっている。

例に挙げた問題点は、サービス運営側が特定の国家に属するいち企業であるという
点に端を発しているとも考えられます。

であるが故に、解決が難しい問題でもあります。

Mastodonの特徴と利点

そこで登場するのが今回取り上げるMastodonです。
GNU Social互換のコミュニケーションツールとして、国内でにわかに注目を集めています。

特徴としては以下のようなものがあります。

  1. Twitterライクなインタフェースを持つマイクロブログシステム
  2. 個別に立てられたサーバ(インスタンスと呼びます)が、緩やかに接続されて連合として動くこと
  3. 公開範囲の設定が細かく行える。
  4. 連合間でキャッシュしあうため、特定インスタンスがサービス停止しても完全な参照不能には為り難い。
  5. 環境構築手順が確立されており、容易であること。

これにより前述の既存SNSの抱える問題点に対し、いくつかの解決方法が提示されてます。

(問題1)運営ポリシーの不透明さからくる、アカウント凍結や削除への不信感
(回答)運営ポリシーは、インスタンスの運営者次第となるが、
Mastodonというサービスの範囲内で、複数のインスタンスの中から、
自らに適した運営ポリシーを持つインスタンスを選択する余地がある。

(問題2)企業運営であるが故のマネタイズから逃れられないこと。またその難しさ。
(回答)個々のインスタンスでは、運営者が管理可能な範囲のユーザを管理すればよく、
設備への投資が適正な範囲で収められるため、マネタイズの重要性が相対的に低くなる。

(問題4)サービスの継続性が運営企業の運営方針、運営状態と紐付いてしまっている。
(回答)仮に利用していたインスタンスが閉鎖されても、他のインスタンスに移転する余地がある。
また、連合での他サーバキャッシュにより、情報が失われづらい。

筆者の雑感

15~20年ほど前、個々のWebサイトが独自に「掲示板」を持っていた時代がありました。
Mastodonは、見方によってはその再来とも言えます。

ただ、「掲示板」の時代と大きく違うのは特徴としてあげた

2,個別に立てられたサーバ(インスタンスと呼びます)が、緩やかに接続されて連合として動くこと

の部分ですね。

Mastodonでは、特定のインスタンスにアカウントを取得しますが、
インスタンスを跨いだ形でのユーザフォローが可能です。
例えば、AインスタンスにいるBさんが、CインスタンスのDさんをフォローすることができます。
逆も当然可能です。
こうやってフォローが成立した段階で、AインスタンスとCインスタンスが連合となります。

連合になると、お互いのインスタンス上でPublic指定でToot(TwitterでいうTweet)されたものが、
お互いの連合タイムラインに表示されるようになります。
こうやってそれぞれのインスタンスで繋がっていくことで、
大きなひとつの連合タイムラインが発生するというわけです。

もちろん、自分自身のタイムラインや、ローカルインスタンスのみのタイムラインもありますので
必要に応じて使い分けることが出来ます。

「掲示板」時代は、利用者の流入方法や、過疎化という問題がつきまといましたが
そのあたりの問題はこの緩やかな繋がりでかなり解消されるのではないかと考えます。

また公開範囲設定が細かく行えることで、ローカルのみ、もしくはフォロワーのみでの
コミュニケーションなども行える点にも注目です。

Mastodonの問題点

最後にMastodonが抱える問題点についても記載しておきます。

1,インスタンス自体のセキュリティ的な安全性やコスト

個々人がインスタンスを容易に立てることが可能であるということは、裏返せば
そのインスタンスの管理は、インスタンスを立てた人物に委ねられるということです。
プログラム的なセキュリティ問題もありますし、またGNUプロダクトということで
改造も可能なため、悪意ある人物が運営するインスタンスというものが発生しないとも限りません。

また、特定のインスタンスに人が集中した場合は、
管理者に掛かるコスト(インフラ的な金銭面、管理コスト面)も無視出来ません。

2,グローバル展開での社会的、法律的な軋轢

個々のインスタンスはそれぞれの国の社会倫理や法律に従う必要があるのは言うまでもありません。
しかし、連合の機能により、世界を跨いだインスタンスで繋がると、途端に複雑化します。

A国では合法であっても、B国では違法であるということも当然あるわけです。
特に画像等はキャッシュであっても違法とされることもありますので注意が必要です。

既に国内で乱立したインスタンスと、西欧のインスタンス間で問題化した事例もあり、
今後システム的にも改善が必要と思われます。

まだまだ開発進行中のプロダクトですが、それ故に開発者としてはコミットする余地が
大きく残されており、今後のSNSの動向を見る上でも無視出来ない存在に急速になりつつあります。
この後で簡単に説明しますが、立ち上げも非常に簡潔に済みますので、
技術者の方は是非挑戦してみてください。


Mastodonのセットアップについて

gitリポジトリにdocker-compose.ymlがデフォルトで含まれているため、それを利用するのが尤も手軽です。
Mastodonの運用方針として、通常の複数人で利用するモードと、シングルユーザモードの2種類があります。
また、DBの永続化なども視点としてはありますが、
まずは尤もシンプルな複数人利用モードでの立ち上げを目指します。

基本以下のページの内容を補足する形です。

https://github.com/tootsuite/documentation/blob/master/Running-Mastodon/Docker-Guide.md

1,環境準備
まずはDockerとdocker-composeが動作する環境を準備します。
CentOSであれば7以上が必要となりますので、セットアップします。

2,gitのクローン
適当なディレクトリ以下で、githubからソースをcloneします。

3,.env.productionの編集

Cloneして生成されたmastodonディレクトリに移動し、
そこにある.env.production.sampleをコピーして必要項目を埋めていきます。

3-1,ドメイン設定

ドメインと、SSL利用の有無を設定します。
ドメインは適当なものを準備を。
最初はSSLを切っておいた方がいいかもしれません。

.env.production内では以下が該当項目です。

3-2.シリアルの生成

複数のインスタンスが立つことが前提のMastodonではユニークなシリアルキーを設定する必要があります。

.env.production内での項目としては以下の3つです。

シリアルキーは以下のコマンドを./mastodonで実行することで得られます。

これを、3回実施し、それぞれで得られたシリアルを前述の3項目にセットしてください。

3-3.SMTPサーバの設定

ユーザ登録などでメール送信を行うため、SMTPサーバの設定が必要です。
.env.production上では以下が該当します。

なにを設定するかは環境次第ですが、推奨とされている従量課金型のメールサービスや
GMail、もしくはローカルのSMTPサーバなどを利用すると良いでしょう。

4,ビルドとマイグレーション

まずはDockerコンテナをビルドします。

続いてDockerコンテナ上に構築されたDBに対してマイグレーションを実施します。

マイグレーション時は以下のコマンドを./mastodon直下で実行します。

5,イメージ起動

ここまでエラー無く完了したら、いよいよイメージの起動です。

を実行すると、mastodonが起動します。

起動したMastodonは、Port番号3000でWebサービスを開始しますので、

などで、ブラウザから閲覧可能です。
閲覧して、可愛い(?)マストドンさんとログインページが出てくれば成功です。

6,リバースプロキシの設定

このまま勢いに任せて公開…してしまってもいいのですが、このままだと
ポート指定でのアクセスになり少々不便ですし、SSLも使えません。
ですので、Dockerの親機などにnginxなどでリバースプロキシを噛ませます。

nginxの設定ファイルなどは公式で配布されているものを利用すると手軽です。

https://github.com/tootsuite/documentation/blob/master/Running-Mastodon/Production-guide.md

SSL証明書もリバースプロキシ上で設定すると良いでしょう。

7,管理アカウントの作成

Mastodonには管理用のアカウントを作成する機能があります。
管理用アカウントでは、通常のWebインタフェースの管理画面上に、管理用のメニューが追加されます。

まずは普通にアカウントを作成し、そのアカウントに対してAdoministrator権限を付与します。
付与するには./mastodon直下にて

を実施すればOKです。Webインタフェース上からの新規アカウント追加の可否も
このメニュー内で設定出来ますので、まずは管理用のアカウントを作成してください。

8,最後に

単純な起動方法については以上です。
これでとりあえずインスタンスが立ち上がります。
ここからの運用はあなた次第です。是非趣味のインスタンスを立ち上げて、色々試してみてください。

2017-05-17

API Blueprint で API 仕様書を書いて、配布用の HTML を自動生成する方法

(画像は API Blueprint の Web サイト より転載)

GMO アドパートナーズ グループ CTO 室の M. Y.(DevOps ネタ担当)です。今回は、API 開発時に使って便利だったツールの話をします。

きっかけ

最近、私が担当している広告関係のプロダクトに、お客様向けに公開する API を新規追加することになりました。この API はお客様側のエンジニアが利用するため、API 仕様書を作る必要があります。

過去の社内事例では、Word ファイルで API 仕様書を作成して、配布していました。しかし、Word ファイルでは差分を確認しづらいので、API 仕様自体のバージョン管理が大変です。そこで、今回は API 仕様書から配布用の HTML を自動生成することにしました。

API 仕様書を自動生成する技術としては Swagger が有名ですが、今回のプロダクトでは API Blueprint と Swagger を比較して、API Blueprint を採用しました。この記事では、実際の API に似せた具体例を示しつつ、API Blueprint の使い方をご紹介します。

今回の要件

今回のプロダクトでの要件は、次のようなものでした。クライアントやモックサーバの自動生成よりも、ドキュメント管理の敷居を下げることを重視しました。

  • 仕様書をテキストファイルに書いて、GitHub で変更履歴を管理したい
  • 一部機能の契約者のみに配布する、見た目の良いマニュアルを自動生成したい
  • 特定のツールに詳しくないメンバでも、少し学習すれば API を追加していけるようにしたい
  • API の数はそれほど多くない

API Blueprint と Swagger の比較

比較にあたり、まず仮の API 仕様を決めて、それぞれのフォーマットで実際に仕様書を書いてみました。そして、その仕様書を以下のツールにかけて動作確認しました。

その結果をもとに、いくつかの評価軸で両者を比較してみました。これは今回の要件に照らして比較したもので、Swagger の得意な分野(コード自動生成など)が一部抜けていることにご注意ください。

No. 評価軸 API Blueprint Swagger
1 言語仕様 Markdown を拡張した形式で書く(拡張子名は apib) YAML、JSON またはソースコード上のアノテーションで書く
2 編集方法 ローカルディスク上のファイルを好きなエディタで編集すると、Web アプリ(aglio)の表示が自動更新される ローカルディスク上のファイルをWeb アプリ(swagger-editor)で開いて編集し、表示を確認する
3 文法ミスの訂正 aglio のコマンドライン表示で警告される swagger-editor の編集画面で警告される
4 HTML ファイルの生成 ローカルで開ける単一の HTML ファイルを aglio で生成できる bootprint または swagger-codegen-cli で生成できるが、swagger-editor や swagger-ui よりも見た目が劣る
5 記載の柔軟性 言語仕様に含まれない情報も Markdown 形式で自由に記載できる 言語仕様に含まれない情報の表現力は低い

ドキュメントの編集のしやすさ(No.1〜3)、および単一の HTML ファイルを生成する場合の表現力の高さ(No.4〜5)から、今回は API Blueprint を採用しました。

以下では、上記の評価軸を順に触れながら、API Blueprint の使い方をご紹介します。

API Blueprint の詳細

言語仕様

API Blueprint は、API ドキュメントを書くために、Markdown を拡張して作られた仕様です。ファイルの拡張子名は apib です。

API 開発プラットフォームを提供する Apiary2017年1月に Oracle が買収したスタートアップ)が主に推進していますが、仕様自体はオープンで、後述する aglio などのツールが多数開発されています。

言語仕様については、大まかに知りたい場合は API Blueprint Tutorial を読むのが良いと思います。

具体例は、公式サイトからリンクされた Examples もありますが、これは apib ファイルしかないので、どういう HTML が生成されるのかイメージしづらいです。

aglio のページで、API Blueprint 形式のファイルと、それに対応した HTML が公開されているので、以下の2つのファイルを見比べてみるのが、最初はわかりやすいと思います。

私の方でも、もう少し短くてシンプルな例を書いてみたので、こちらもご参考ください。

API Blueprint の詳細な仕様は API Blueprint Specification で公開されています。API Blueprint にある程度慣れたら、この仕様をざっと読んで、どういう表現ができるのか押さえておくことをオススメします。私はこれを読んで、enum の使い方やデフォルト値の指定方法などを知りました。

ところで、API Blueprint のなかでは、以下のようにリクエストやレスポンスのデータ形式を定義できます。

これは Markdown Syntax for Object Notation (MSON) という、Markdown で JSON および JSON Schema を表現するための仕様です。API Blueprint の内部で JSON を表現するために Apiary が開発した、とのことです。

編集方法・文法ミスの訂正

apib ファイルを編集する際には、aglio という API ドキュメント生成ツールを使います。

aglio は、apib ファイルから単一の HTML ファイルを生成するツールです。また、aglio には HTTP サーバとしての機能もあり、apib ファイルの更新を自動検知して、その HTTP サーバ上のページを自動的にリロードする機能を持ちます。

まず、以下のように –server オプションを付けて aglio を起動します。

http://127.0.0.1:3000/ にアクセスすると、以下のようなページが表示されます。

この状態で、好きなエディタで sample.apib を編集して保存すると、編集を自動検出してレンダリングが再実行され、http://127.0.0.1:3000/ 上のページが更新されます。Web ベースのエディタを強制されないというのは、個人的には嬉しいポイントでした。

なお、保存した apib ファイルに文法ミスがあると、以下のように、該当箇所を強調表示して知らせてくれます。

ちなみに、HTML ファイルの生成にこだわらないのであれば、Apiary にアカウントを作って、Apiary の Editor を使うこともできます。Apiary Editor は、swagger-editor と同様に Web ブラウザ上で編集可能で、文法エラーをリアルタイムに表示してくれます。

HTML ファイルの生成

-o オプションを指定して aglio を実行すると、aglio で表示されものと同じページが、単一の HTML ファイルとして生成されます。CSS なども HTML ファイルに同梱されるため、配布するのはとても楽です。

公式サイトの Tools のページ にある Renderers を一通り試したのですが、aglio の HTML が最も洗練されているように見えました。

記載の柔軟性

API Blueprint では、仕様書全体の先頭や、各 API の説明の先頭に、Markdown 形式で自由に説明を書くことができます。

例えば、aglio のページにある例(HTML)の Overview の部分や、Notes API の先頭に書かれた “Important Info” の部分は、Markdown で書かれた説明です。リンク、引用、リスト、表などが自由に使えることがわかると思います。

ちなみに、aglio は aglio でしか使えない拡張表現(注意点をブロック表示する ::: warning など)にも対応しています。

Markdown で自由に説明を書けるのは便利ですが、それがどこにレンダリングされるかはツールに依存するので注意が必要です。例えば、aglio ではきれいに表示される説明が、Apiary では変な位置に表示される、ということがありました。

API Blueprint を使ってみて、つまづいた点

リクエスト/レスポンス例の書き方

MSON のデータ例にハイフン(-)が含まれていると、そのハイフンの前までしか読み込まれないという問題があります。例えば、以下のように書くと、url は http://techblog.gmo、publishedAt は 2017 までしか読み込まれません。

この問題は、以下のようにデータ例をバッククォートで囲むことで解決します。

API Blueprint Specification の説明では、データ例 (example value) はすべてバッククォートで囲まれているので、ハイフンの有無に関係なく、普段からそうしておくのが無難だと思います。

aglio の制限

API Blueprint では、リクエストの URL パラメータ、ボディ、およびレスポンスのボディを、MSON 形式で定義することができます。また、”Data Structures” という節で独自の型を定義し、その型をボディの定義などから参照することができます。

しかし、現在の aglio(執筆時のバージョンは 2.3.0)には、ボディ部の定義を表示できないという制限があります。また、Data Structures で定義された型については、JSON Schema にも表示されません。これらの定義は、ボディ部の例には反映されているので、書いた定義が無視されているわけではなさそうなのですが……。

aglio の GitHub にこの issue は登録されていて、開発は進んでいるようなので、今後のアップデートに期待したいと思います(参考:Rendering “attributes” section and Data Structures · Issue #103 · danielgtaylor/aglio)。

ちなみに、aglio 以外のレンダラも同様の問題があったのですが、Apiary のエディタではこれらの情報は問題なく表示されました。そのため、API Blueprint 自体の制限ではなさそうです。

まとめ

今回は、API Blueprint と aglio を使って、配布用の API 仕様書を自動生成する方法をご紹介しました。

  • Markdown を知っていれば、他の人が書いた例を参考になんとなく書ける
  • aglio だけインストールすれば、あとは好きなエディタを使ってすぐ書き始められる

という敷居の低さが、API Blueprint の魅力だと思います。

逆に、API 仕様書を先に作るのは嫌で、コードを先に書いてあとから API 仕様書を自動生成したい、という場合には Swagger のほうが良いと思います。そのあたりは、その時の要件に合わせて選択するのがよさそうです。この記事が、皆さんの今後の API 開発の参考になれば幸いです。