文書を書くときMarkdownって便利ですよね。GitHubでドキュメントを書いたりサイトの記事を書いたりするのにも使われるMarkdownですが、私はもっとカジュアルに使いたいんですよね。会議中にとるノートとかクライアントに送る重要なメールの案とか、メモ帳代わりにパッと書ける、そして書いているMarkdownを変換したHTMLをパッと他人と共有したいですね。書いている途中でもURLを共有すればすぐに文書を共有でき、かつMarkdownを編集すればリアルタイムで共有した他人のHTML文書も変わっていく、さらには権限を持っていればMarkdownの編集もリアルタイムに複数人で同時に行える、そんなふうに文章が作れたら便利だと思いませんか？ということでそれを行う方法を紹介するのがこの記事です。
ちなみにOSSで、Dockerでセルフホストする方法です。クラウドサービスではないので書いた文書は100%自分の管理下に置けます。秘密の文書でも安心です。
HedgeDoc
HedgeDocというOSSを使います。HedgeDocはHackMDというSaaSが元になっており、HackMDはソースコードは非公開になりましたが今もサービスが続いています。
セットアップ
Docker Composeで立ち上げ
Docker Composeを使って立ち上げる。以下のcompose.yamlファイルを作成。イメージのバージョンは適宜変える。
services:
database:
image: postgres:13.4-alpine
environment:
- POSTGRES_USER=hedgedoc
- POSTGRES_PASSWORD=password
- POSTGRES_DB=hedgedoc
volumes:
- database:/var/lib/postgresql/data
restart: always
app:
# Make sure to use the latest release from https://hedgedoc.org/latest-release
image: quay.io/hedgedoc/hedgedoc:1.9.6
environment:
- CMD_DB_URL=postgres://hedgedoc:password@database:5432/hedgedoc
- CMD_DOMAIN=localhost
- CMD_URL_ADDPORT=true
volumes:
- uploads:/hedgedoc/public/uploads
ports:
- "3000:3000"
restart: always
depends_on:
- database
volumes:
database:
uploads:
$ docker compose up -dで起動する。これでローカルホストのブラウザからhttp://localhost:3000/でアクセスできる。
ユーザ作成
ブラウザでアクセスすると右上に「サインイン」ボタンがあるので、そこからユーザアカウントを作成しておく。
不正利用対策
デフォルトではログインしていないユーザも文書を作成できてしまうし、誰でもユーザアカウントを作れてしまう。セルフホストして個人や社内で使うのなら問題なのでそれらを無効化する。
以下のように環境変数を追加する。
@@ -13,10 +13,12 @@
image: quay.io/hedgedoc/hedgedoc:1.9.6
environment:
- CMD_DB_URL=postgres://hedgedoc:password@database:5432/hedgedoc
- CMD_DOMAIN=localhost
- CMD_URL_ADDPORT=true
+ - CMD_ALLOW_ANONYMOUS=false
+ - CMD_ALLOW_EMAIL_REGISTER=false
volumes:
- uploads:/hedgedoc/public/uploads
ports:
- "3000:3000"
restart: always
ユーザを追加するときは一時的に- CMD_ALLOW_EMAIL_REGISTER=falseの行をコメントアウトして立ち上げ、ユーザを追加し終わったらまた元に戻すという運用が求められる。
リバースプロキシの裏で公開する
HedgeDocはContent Security Policyヘッダを厳格に指定しているので、公開するときのURLを指定する必要がある。例えばhttps://example.net/として公開されるなら、
@@ -11,12 +11,12 @@
app:
# Make sure to use the latest release from https://hedgedoc.org/latest-release
image: quay.io/hedgedoc/hedgedoc:1.9.6
environment:
- CMD_DB_URL=postgres://hedgedoc:password@database:5432/hedgedoc
- - CMD_DOMAIN=localhost
- - CMD_URL_ADDPORT=true
+ - CMD_DOMAIN=example.net
+ - CMD_PROTOCOL_USESSL=true
- CMD_ALLOW_ANONYMOUS=false
- CMD_ALLOW_EMAIL_REGISTER=false
volumes:
- uploads:/hedgedoc/public/uploads
ports:
リバースプロキシからは今までと同じでポート3000番に接続すれば良い。
http://example.net:8080/として公開されるなら、
@@ -11,18 +11,18 @@
app:
# Make sure to use the latest release from https://hedgedoc.org/latest-release
image: quay.io/hedgedoc/hedgedoc:1.9.6
environment:
- CMD_DB_URL=postgres://hedgedoc:password@database:5432/hedgedoc
- - CMD_DOMAIN=localhost
- - CMD_URL_ADDPORT=true
+ - CMD_DOMAIN=example.net
+ - CMD_PORT=8080
- CMD_ALLOW_ANONYMOUS=false
- CMD_ALLOW_EMAIL_REGISTER=false
volumes:
- uploads:/hedgedoc/public/uploads
ports:
- - "3000:3000"
+ - "8080:8080"
restart: always
depends_on:
- database
volumes:
database:
この場合、リバースプロキシからHedgeDocへの接続も8080ポートで行う。ブラウザからリバースプロキシへのポート番号がプロトコルのデフォルトではないときは、リバースプロキシからHedgeDocへのポート番号と同じにする必要があるっぽい。
サブパスの下で公開する（例：https://example.net/hedgedoc/）ことができそうな環境変数もあるのだが、私が試したところリダイレクトが無限ループして使えなかった。
使ってみる
文書を書くときはこの画面で書く。基本的なMarkdown記法はもちろん、コードのシンタックスハイライト、数式、Mermaidを使ったシーケンス図、フローチャート、ER図などなど、さらには楽譜を書く記法まで使えるらしい。
書いた文書を共有したいと思ったときには右上の「公開する」ボタンを押すだけ。押すと以下のようなページが別タブで開くのでこのURLを共有すれば良い。この表示画面は編集画面の変更がリアルタイムで反映される。
表示や編集ができる人の範囲は青文字の「EDITABLE」の部分から変えられる。先ほどの「公開する」ボタンでは権限の設定変更は行われていない。あのボタンはあくまで共有用URLを開いているだけで、公開非公開の設定はここで行う。
ちなみに閲覧可能だが編集不可能な人が文書を見た場合も編集画面は表示できるのだが、編集しようとするとポップアップが出て拒否されるという仕様になっている。少し紛らわしいので注意。
複数人で同時に編集することも可能。これも互いの変更部分がリアルタイムで反映される。
あとがき
Markdownで文書を書けて、リアルタイムな編集・閲覧ができて、共有も簡単で、とても便利です。ただユーザ管理の機能が無く、特定のユーザだけ閲覧できるといったこともできないのが欠点かもしれません。