HackMDでGitLab認証を利用する

HackMDは同時編集が便利なコラボレーションツールです。HackMDは認証なしでも十分に使えますが、外部認証を利用するとさらに便利に使えます。公式リポジトリのドキュメントによると、HackMDは以下の認証方式に対応しています。

GitHub
Twitter
GitLab (self hosted)
SAML

本稿ではGitLab認証を利用する方法を説明します。

HackMDのデプロイ

HackMDをKubernetes クラスタにデプロイします。公式の stable/hackmd Helm chart を利用すると簡単にデプロイできます。

ここでは構成管理にHelmfileを利用します。

# helmfile.yaml
releases:
  - name: hackmd
    namespace: devops
    chart: stable/hackmd
    values:
      - ingress:
          enabled: true
          hosts:
            - hackmd.{{ requiredEnv "kubernetes_ingress_domain" }}
        resources:
          limits:
            memory: 256Mi
          requests:
            memory: 256Mi
        persistence:
          size: 50Gi
        postgresql:
          install: false
          postgresHost: {{ requiredEnv "database_host" }}
          postgresDatabase: hackmd
          postgresUser: hackmd
          postgresPassword: hackmd

環境変数の kubernetes_ingress_domain や database_host は環境に合わせて設定してください。

export kubernetes_ingress_domain=dev.example.com
export database_host=xxx.xxx..ap-northeast-1.rds.amazonaws.com
helmfile sync

https://hackmd.dev.example.com を開いてHackMDの画面が表示されたら成功です。

これでKubernetes クラスタにHackMDがデプロイされました。

GitLabの設定

GitLabの管理画面で Applications を開き、New application ボタンをクリックします。以下の項目を入力します。

Name: hackmd
Redirect URI: https://hackmd.dev.example.com/auth/gitlab/callback
Trusted: YES
Scopes: api

System OAuth applicationsに hackmd が追加されたことを確認します。

HackMDの設定

HackMDでGitLab認証を設定するには以下の環境変数を設定します。

名前	設定値	例
`HMD_DOMAIN`	HackMDのドメイン名	`hackmd.dev.example.com`
`HMD_URL_ADDPORT`	HackMDのポート	`443`
`HMD_PROTOCOL_USESSL`	HackMDでHTTPSを利用している場合はtrue	`true`
`HMD_GITLAB_BASEURL`	GitLabのURL	`https://gitlab.dev.example.com`
`HMD_GITLAB_CLIENTID`	前項で追加したOAuth ClientのApplication ID
`HMD_GITLAB_CLIENTSECRET`	前項で追加したOAuth ClientのSecret

Helmfileを利用している場合は以下のように環境変数を追加します。

# helmfile.yaml
releases:
  - name: hackmd
    namespace: devops
    chart: stable/hackmd
    values:
      - ingress:
          enabled: true
          hosts:
            - hackmd.{{ requiredEnv "kubernetes_ingress_domain" }}
        resources:
          limits:
            memory: 256Mi
          requests:
            memory: 256Mi
        persistence:
          size: 50Gi
        postgresql:
          install: false
          postgresHost: {{ requiredEnv "database_host" }}
          postgresDatabase: hackmd
          postgresUser: hackmd
          postgresPassword: hackmd
        extraVars:
          - name: HMD_DOMAIN
            value: hackmd.{{ requiredEnv "kubernetes_ingress_domain" }}
          - name: HMD_URL_ADDPORT
            value: "443"
          - name: HMD_PROTOCOL_USESSL
            value: "true"
          - name: HMD_GITLAB_BASEURL
            value: https://gitlab.{{ requiredEnv "kubernetes_ingress_domain" }}
          - name: HMD_GITLAB_CLIENTID
            value: xxx
          - name: HMD_GITLAB_CLIENTSECRET
            value: xxx