【ITニュース解説】Self-Host Supabase with Docker: Studio, API Keys and Errors

システムエンジニアを目指す皆さん、今回はバックエンド開発を効率化するツール「Supabase」を、自分たちの手でサーバーに構築・運用する「セルフホスティング」について解説する。Supabaseは、PostgreSQLという高機能なデータベースを基盤に、認証機能、データを自動でAPIとして公開する機能、ファイルストレージ、リアルタイム通信機能、そしてプログラムを実行できるエッジ関数といった、アプリケーション開発に必要なバックエンドサービスをまとめて提供している。これらの機能は「Studio」と呼ばれるWebダッシュボードから簡単に管理できるため、初心者でも扱いやすい。

セルフホスティングを選ぶ利点は、自分たちが環境を完全にコントロールできる点にある。例えば、データの所在地を厳密に管理したい場合や、サービスが外部に情報を送信しない「テレメトリーなし」の環境を構築したい場合に適している。一方で、Supabaseのクラウド版（マネージドプラットフォーム）が提供する一部の高度な機能、例えばプロジェクトのブランチング、詳細なメトリクス、自動バックアップ、特定の時点への復元（PITR）、データ連携（ETL）、そしてAPI経由での管理機能などはセルフホスト版では利用できない。また、セルフホスト版は一つのサーバーで複数のプロジェクトを管理する機能は持たず、基本的には単一のプロジェクト運用となる。そのため、バックアップ作業なども自分たちで行う必要がある点を理解しておくべきだ。

セルフホスティングの環境を構築するには、DockerとそのComposeプラグイン、そしてGitというバージョン管理ツールが必要だ。ハードウェア要件としては、最低でも4GBのメモリと2コアのCPU、40GBのSSDが必要だが、安定した運用のためには8GBのメモリ、4コアのCPU、80GBのSSDが推奨されている。Supabaseのセルフホスト環境は、データベース本体のPostgres、認証を扱うAuth、APIゲートウェイのEnvoy、REST APIを提供するPostgREST、そしてStudioなど、合計11の独立したサービス（コンテナ）が連携して動作する。これらのコンテナをまとめて管理するのがDocker Composeだ。

インストールは、まずSupabaseのセルフホスト版のソースコードをGitでクローンするところから始まる。次に、Docker Composeの設定ファイルや環境変数を格納する.envファイルを準備し、秘密鍵やパスワードといった重要な情報を生成するスクリプトを実行する。これらの鍵は、APIへのアクセス認証や内部的なセキュリティに不可欠なもので、特に「JWT_SECRET」はAPIがユーザーを認証するためのトークン（JWT）を署名する際に使われる。また、「ANON_KEY」（またはSUPABASE_PUBLISHABLE_KEY）は匿名ユーザーがAPIにアクセスする際に使用し、「SERVICE_ROLE_KEY」（またはSUPABASE_SECRET_KEY）は、特別な権限を持つサーバーサイドの処理などで使われる、いわば「マスターキー」のようなものだ。Studioへのログインには、「DASHBOARD_USERNAME」と「DASHBOARD_PASSWORD」が使われる。

環境変数の設定が完了したら、docker compose up -d --waitコマンドを実行して全てのコンテナをバックグラウンドで起動する。これにより、Studioがhttp://localhost:8000で利用可能になり、設定したユーザー名とパスワードでログインできるようになる。Studioの「Table Editor」で新しいテーブルを作成し、データを挿入すれば、そのデータは自動的にAPI経由でアクセスできるようになる。例えば、http://localhost:8000/rest/v1/your_table_nameというURLでデータの読み込みが可能だ。

しかし、運用しているといくつかのエラーに遭遇することがある。特に初心者が陥りやすい問題とその解決策を理解しておくことは重要だ。

まず、APIにアクセスしようとすると「401 Unauthorized」というエラーが表示されることがある。これは、APIリクエストに必要な「apikey」ヘッダーが不足しているか、無効なキーが設定されている場合に発生する。APIへの全てのアクセスには、前述のANON_KEYなどをapikeyヘッダーとして含める必要がある。

次に、「PGRST301」というエラーが表示される場合がある。これは、APIゲートウェイを通過したものの、データベースのAPIであるPostgRESTがJWT（JSON Web Token）を正しくデコードできないことを示している。これは主に、JWT_SECRETという秘密鍵が途中で変更されたり、生成されたキーと実際に使われているキーが一致しない場合に起こる。このような場合は、generate-keys.shスクリプトを再度実行して全ての鍵を再生成し、sh run.sh recreateコマンドで関連するサービス（api-gw, rest, authなど）を再作成する必要がある。

テーブルを作成したのにデータが取得できない、という状況もよくある。「[]」という空の配列が返ってくる場合、これは「Row Level Security (RLS)」という機能が原因であることが多い。SupabaseのStudioで新しくテーブルを作成すると、デフォルトでRLSが有効になる。RLSは、誰がどのデータにアクセスできるかを細かく制御するセキュリティ機能だが、何のポリシーも設定されていないと、匿名ユーザーはデータを見ることができない。この問題を解決するには、StudioのSQLエディタなどで、匿名ユーザー（anonロール）が特定のテーブルを読み取れるようにするポリシーを記述する必要がある。例えば、create policy "Public can read notes" on public.notes for select to anon using (true);のようなSQLコマンドを実行する。

ファイルストレージ機能を利用する際も注意が必要だ。ファイルをアップロードしようとすると、「NoSuchBucket」や「AccessDenied」といったエラーが表示されることがある。これは、バケットがまだ作成されていないか、ストレージのデータにもRLSが適用されるため、適切なアクセス権限がない場合に発生する。ファイルをアップロードするには、まずバケットを作成し、必要に応じてstorage.objectsテーブルに対するRLSポリシーを設定するか、SERVICE_ROLE_KEYのような特別な権限を持つキーを使用する必要がある。

ユーザー登録時のメール認証に関する問題も発生しやすい。デフォルトのセルフホスト版の設定では、メール送信のために存在しないサーバーを参照しているため、ユーザー登録が完了しない、あるいは504タイムアウトエラーが発生することがある。本番環境では、実際に利用できるSMTPサーバーの設定（ホスト名、ポート、ユーザー名、パスワードなど）を.envファイルに記述し、Authサービスを再作成する必要がある。開発やテスト目的であれば、一時的にENABLE_EMAIL_AUTOCONFIRM=trueという設定を.envに追加し、sh run.sh recreate authコマンドでAuthサービスを再作成することで、メール認証なしでユーザー登録を完了させることができる。.envファイルを変更した際には、必ずsh run.sh recreate <サービス名>を実行して、変更をサービスに反映させることを忘れてはならない。単なるdocker compose restartでは環境変数が更新されない場合があるためだ。

セルフホスト環境をインターネットに公開する際には、HTTPS化が必須となる。セルフホスト版のSupabaseは、そのままではHTTPSをサポートしないため、CaddyやNginxといったリバースプロキシを前面に配置し、それらのプロキシでTLS（HTTPS）終端を行う必要がある。この際、.envファイル内のSUPABASE_PUBLIC_URL、API_EXTERNAL_URL、SITE_URLといったURL設定を、実際のドメインに合わせて適切に更新する必要がある。特にSITE_URLは、認証後のリダイレクト先やメールからのリンク先として重要だ。

最後に、データのバックアップとシステムアップグレードについてだが、これらはセルフホスト版のSupabaseを利用する上で非常に重要な自己責任の部分となる。クラウド版のようなマネージドバックアップ機能はないため、PostgresデータベースのデータやStorageに保存されたファイルは、自分自身で定期的にバックアップを取る必要がある。Postgresのデータはdocker exec supabase-db pg_dumpコマンドで論理バックアップを取得でき、ファイルデータはvolumes/storageやvolumes/db/dataディレクトリをコピーすることでバックアップできる。システムのアップグレードはupdate.shスクリプトを使って行えるが、アップグレード前には必ずバックアップを行い、--dry-runオプションで変更内容をプレビューすることが推奨されている。誤ってsh reset.shコマンドを実行すると、全てのデータが削除されてしまうため、このコマンドの利用には最大限の注意が必要だ。

このように、Supabaseのセルフホスティングは、多くのバックエンド機能を手軽に利用できる強力な選択肢だが、その運用にはDockerの知識や、キー管理、セキュリティポリシー、バックアップといった基本的なシステム管理の知識が求められる。今回の解説が、システムエンジニアを目指す皆さんの学習の一助となれば幸いだ。