コンテンツにスキップ
Oleaflyv0.4.12

サーバーを運用する

ストレージ、バックアップ、上限

Oleafly Server のすべての設定、ディスクまたは S3 バケットへのファイル保存、コンパイル済みの PDF、プロキシの内側での運用、1 つのネットワーク上のクラスのための制限とアカウントごとの上限、ログ、バックアップ、復元、更新を説明します。

このページでは、Oleafly Server を日々運用する方法を説明します。インストールするには、まず共同編集サーバーを運用するから始めてください。

サーバーは、設定を環境変数から読み取ります。設定されていても空の変数は、設定されていないものとして扱われます。設定がない、または形式が正しくない場合、サーバーは起動せず、ログにどの設定かが示されます。

変数内容既定値
OLEAFLY_PUBLIC_URLユーザーが Oleafly に入力する HTTPS のアドレス。https://www.cs.example.edu/oleafly のようにパスを含められます。必須です。Compose と Coolify のファイルでは自動で設定されます。なし
OLEAFLY_BINDサーバーが待ち受けるアドレスとポート。0.0.0.0:8080
OLEAFLY_DATA_DIRデータベースと保存されたファイルのフォルダ。/data
OLEAFLY_SERVER_NAMEOleafly でユーザーに表示される名前(Smith Lab など)。Oleafly Server
OLEAFLY_SERVER_ICON_URL名前の横に表示される正方形の画像の HTTPS アドレス。なし
OLEAFLY_SETUP_CODE自分で決める 1 回限りのセットアップコード。英数字で 12 文字以上とし、ダッシュやスペースを入れてもかまいません。指定しない場合は、サーバーが生成します。自動生成
OLEAFLY_GITHUB_CLIENT_ID, OLEAFLY_GITHUB_CLIENT_SECRETGitHub でのサインインをオンにします。オフ
OLEAFLY_GITHUB_URLGitHub Enterprise Server のアドレス。https://github.com
OLEAFLY_GITHUB_API_URLGitHub API のアドレス。特殊な場合にだけ設定します。https://api.github.com、または OLEAFLY_GITHUB_URL の下の /api/v3
OLEAFLY_GITHUB_LABELGitHub のサインインボタンに表示するテキスト。GitHub
OLEAFLY_OIDC_<NAME>_ISSUER, OLEAFLY_OIDC_<NAME>_CLIENT_ID, OLEAFLY_OIDC_<NAME>_CLIENT_SECRET<NAME> という名前の OpenID Connect プロバイダをオンにします。オフ
OLEAFLY_OIDC_<NAME>_LABELそのサインインボタンに表示するテキスト(University login など)。<NAME>
OLEAFLY_OIDC_<NAME>_TRUST_EMAILこのプロバイダが返すすべてのメールアドレスを、確認済みとして扱います。先に確認済みのメールアドレスをお読みください。false
OLEAFLY_SMTP_URL, OLEAFLY_MAIL_FROMメール。メールをお読みください。オフ
OLEAFLY_OPEN_SIGNUP設定したプロバイダのいずれかでサインインした人なら誰にでも、メンバーとしてアカウントを与えます。オープンサインアップをお読みください。false
OLEAFLY_WEBブラウザからのアクセスをオンにします。ブラウザからのアクセスをお読みください。false
OLEAFLY_BLOB_STORE図や PDF などのファイルの保存先。fs は OLEAFLY_DATA_DIR に保存します。s3://lab-bucket や s3://lab-bucket/oleafly のようなアドレスは、バケットに保存します。fs
OLEAFLY_S3_ENDPOINTAmazon S3 以外の S3 互換ストア(MinIO や Cloudflare R2 など)のアドレス。Amazon S3 の場合は空のままにします。Amazon S3
OLEAFLY_S3_REGIONバケットのリージョン。us-east-1
OLEAFLY_S3_ACCESS_KEY_ID, OLEAFLY_S3_SECRET_ACCESS_KEYサーバーがバケットに使うキー。s3:// のアドレスを使う場合は必須です。なし
OLEAFLY_MAX_PROJECT_MBサーバーが受け付ける最大のプロジェクトのサイズ(メガバイト単位)。200
OLEAFLY_MAX_FILE_MB1 つのファイルの最大サイズ(メガバイト単位)。50
OLEAFLY_MAX_MEMBERS_PER_PROJECT1 つのプロジェクトの最大人数。20
OLEAFLY_ACCOUNT_STORAGE_MB1 つのアカウントが所有するプロジェクトが保存できる最大量(メガバイト単位)。アカウントごとの上限をお読みください。上限なし。オープンサインアップでは 100
OLEAFLY_MAX_PROJECTS_PER_ACCOUNT1 つのアカウントが所有できる共有プロジェクトの最大数。上限なし。オープンサインアップでは 50
OLEAFLY_UPLOADS_PER_HOUR1 つのアカウントが 1 時間に行えるファイルとスナップショットのアップロードの回数。上限なし。オープンサインアップでは 300
OLEAFLY_SIGN_IN_BURST1 つのネットワークアドレスが、短時間にまとめて送れるサインインリクエストの数。1 回のサインインに約 6 件使うため、既定値は、同じアドレスの 50 人が同時にサインインできる数です。300
OLEAFLY_SIGN_IN_PER_MINUTEバーストの後に、1 つのネットワークアドレスに 1 分ごとに戻されるサインインリクエストの数。120
OLEAFLY_EMAIL_LINKS_PER_IP1 つのネットワークアドレスのユーザーに対して、サーバーが 15 分間に送るサインインメールの数。100
OLEAFLY_EMAIL_LINKS_PER_ADDRESS1 つのメールアドレスが 15 分間に受け取れるサインインメールの数。OLEAFLY_EMAIL_LINKS_PER_IP を超えることはできません。3
OLEAFLY_DEVICE_CODES_PER_IP1 つのネットワークアドレスのユーザーが 10 分間にリクエストできるサインインコードの数。100
OLEAFLY_SNAPSHOT_MEMORY_MBプロジェクトのスナップショットの作成にサーバーが使えるメモリ(メガバイト単位)。コンテナのメモリ上限の半分。上限がない場合は 1024
OLEAFLY_BEHIND_PROXYプロキシが追加する X-Forwarded-For ヘッダーから、各ユーザーのアドレスを取得します。Compose、Coolify、Render のファイルではオンになっています。false
OLEAFLY_PROXY_HOPSサーバーに届くまでに、すべてのリクエストが通過するプロキシの数。OLEAFLY_BEHIND_PROXY=true が必要です。1
OLEAFLY_LOG_LEVELサーバーが記録するログの量。error、warn、info、debug、trace のいずれかです。debug か trace を選ばない限り、サーバーが使うライブラリは警告だけを記録します。info
OLEAFLY_SECURITY_LOG_DAYSセキュリティログの項目、プロジェクトのアクセスログの項目、応答済みまたは期限切れのゲストの招待を保持する日数。365
OLEAFLY_ARCHIVE_DAYS所有者が共有を停止した後、プロジェクトを保持する日数。30
OLEAFLY_POLL_HOLD_SECONDS待機中の編集がないとき、サーバーがロングポーリングのリクエストを開いたままにする時間(1 秒から 40 秒)。サーバーの手前にあるプロキシのアイドルタイムアウトより数秒短くしてください。25

Compose の .env ファイルでは、値に $ や # が含まれる場合、値を一重引用符で囲みます。シークレットを保持する設定は、ファイルから読み取ることもできます。.env にシークレットを置かないをお読みください。

既定では、サーバーはすべてを OLEAFLY_DATA_DIR に保存します。データベース、ユーザーが共有するファイル、プロジェクトのスナップショットです。スナップショットは各プロジェクトを保存したコピーで、ユーザーが素早く参加して追いつけるようにするためのものです。

サーバーは、ファイルとスナップショットを、代わりに Amazon S3 や、MinIO や Cloudflare R2 など S3 互換の API を持つほかのストアに保存することもできます。どちらの場合も、データベースは OLEAFLY_DATA_DIR に残るため、サーバーにはデータフォルダが引き続き必要です。

  1. バケットを作成し、パブリックアクセスをブロックします。

  2. そのバケット内のオブジェクトの読み取り、書き込み、削除ができ、それ以外はできないキーを作成します。Amazon S3 では、arn:aws:s3:::lab-bucket/*(フォルダを使う場合は arn:aws:s3:::lab-bucket/oleafly/*)に対する s3:GetObject、s3:PutObject、s3:DeleteObject を意味します。

  3. 変数を設定します。たとえば .env に次のように書きます。

    ターミナルウィンドウ
    OLEAFLY_BLOB_STORE=s3://lab-bucket/oleafly
    OLEAFLY_S3_REGION=eu-west-1
    OLEAFLY_S3_ACCESS_KEY_ID=your-access-key-id
    OLEAFLY_S3_SECRET_ACCESS_KEY=your-secret-access-key

Amazon S3 以外のストアでは、OLEAFLY_S3_ENDPOINT にもそのアドレス(https://minio.example.org:9000 や https://<account-id>.r2.cloudflarestorage.com など)を設定し、OLEAFLY_S3_REGION にはそのストアが期待するリージョン(R2 では auto)を設定します。通常の http:// も使えますが、ストアがサーバーと同じプライベートネットワーク上にある場合にだけ使ってください。

バケット名の後ろの部分は、任意のフォルダです。各ファイルは SHA-256 ハッシュを名前とし、そのハッシュの最初の 2 文字のフォルダの下に置かれます。たとえばハッシュが 3f9a で始まるファイルは oleafly/3f/3f9a... として保存されます。スナップショットには専用の snapshots フォルダがあり、プロジェクトごとにフォルダがあります。サーバーはファイルやスナップショットを読み戻すとき、バイト列をハッシュと照合し、一致しないものは拒否します。バケットを使わない場合は、同じ構成が OLEAFLY_DATA_DIR 内の blobs フォルダにあります。

バケットがリクエストを拒否した場合、そのアップロードまたはダウンロードは失敗し、サーバーのログには 403 Forbidden (AccessDenied) など、バケットの応答が表示されます。サーバーエラー、タイムアウト、接続の切断は別で、サーバーは短いランダムな間隔を置いて最大 3 回試行します。オブジェクトを削除できなかった場合は、それを記録し、6 時間ごとのメンテナンスのたびに再試行するので、障害でオブジェクトが残り続けることはありません。

プロジェクトが共有されると、所有者のアプリが最初のスナップショットをアップロードし、そのデバイスのキーで署名します。それ以降は、サーバーが前のスナップショットと、その後にユーザーが送った変更から、すべてのスナップショットを自分で作成します。新しいスナップショットは、プロジェクトに前回から 1,000 件の変更が溜まると作成されます。サーバーは、少なくとも直近 2,000 件の変更を常に保持するので、短時間離れていたデバイスは、それらから追いつき、プロジェクト全体をダウンロードし直す必要はありません。

スナップショットの作成には、前のスナップショットとその後の変更を合わせたサイズの約 10 倍が必要です。サーバーは OLEAFLY_SNAPSHOT_MEMORY_MB に収まる作成だけを開始し、同時に実行される作成は、その量を共有します。作成が収まらない場合、サーバーはそれをスキップし、必要なメモリ量をログに記録して、プロジェクトのすべての変更を保持します。その場合、デバイスはそれらの変更から、数メガバイトずつ追いつきます。設定を引き上げると、次のスナップショットが作成されます。サーバーは、OLEAFLY_MAX_PROJECT_MB より大きなスナップショットを保存しません。

所有者または編集者が共有プロジェクトのコンパイルに成功すると、そのアプリは PDF を、SyncTeX ファイルがあればそれも一緒に、サーバーに送ります。送信は、プロジェクトごとに 1 分に 1 回までです。サーバーは、プロジェクトごとに PDF と SyncTeX ファイルを 1 つずつ、メインファイルの名前、コンパイルした人、日時とともに保持します。ブラウザからのアクセスでは、この PDF がプロジェクトのユーザーに表示されます。

アップロードのたびに前のものが置き換えられ、古いファイルは、どこからも使われなくなった時点で削除されます。コンパイル済みのファイルは、ほかのファイルと同じくディスクまたはバケットに保存され、プロジェクトとともに削除されます。コンパイル済みのファイルの大きさは、最大で OLEAFLY_MAX_FILE_MB です。所有者のアカウントのストレージには数えられますが、1 時間あたりのアップロード数には数えられません。

プロジェクトのメンバーは誰でも、コンパイル済みのファイルを読めます。置き換えられるのは、所有者と編集者だけです。

リバースプロキシの内側で動かす

「リバースプロキシの内側で動かす」セクション

サーバーは通常の HTTP で通信するため、手前にある何かが HTTPS を処理します。Compose のセットアップでは Caddy、あるいは Coolify のプロキシや、大学の Web サーバーなど、すでに運用している Web サーバーです。手前にあるものは、次のことを満たす必要があります。

  • OLEAFLY_MAX_PROJECT_MB と同じ大きさまでのリクエストを受け付ける
  • クライアントのアドレスを X-Forwarded-For に追加する

また、/ws への WebSocket アップグレードを通し、その接続を少なくとも 1 時間は開いたままにする必要があります。ライブ編集は、可能なときにそれらを使います。ブラウザからのアクセスがオンの場合は、/web/ws へのアップグレードも通す必要があります。ブラウザ用アプリには、より遅い代わりの経路がないためです。

サーバーは、プロキシだけが到達できる場所で動かします。同じマシン上なら、OLEAFLY_BIND=127.0.0.1:8080 を設定します。そのうえで、OLEAFLY_BEHIND_PROXY=true を設定します。

WebSocket 接続がブロックされるとき

「WebSocket 接続がブロックされるとき」セクション

WebSocket 接続をブロックするネットワークがあります。フィルタリングプロキシのある大学や会社のネットワークに多く見られます。そうしたネットワークでも、ライブ編集は動作しますが、速度は遅くなります。サーバーが HTTPS では応答しているのに WebSocket の試行が 2 回続けて失敗すると、Oleafly は HTTP のロングポーリングに切り替えます。編集は /api/v1/projects/<project>/frames に送り、ほかのユーザーの編集は /api/v1/projects/<project>/poll で待ちます。各リクエストは、最大 OLEAFLY_POLL_HOLD_SECONDS の間開いたままになります。すべての編集は、これまでどおり届きます。Oleafly は 1 分ごとに WebSocket を再試行し、接続できた時点でそちらに戻ります。

Oleafly の接続をテストと管理コンソールの接続チェックは、これが起きていることを「このネットワークが通常の経路をブロックしているため、ライブ編集はより遅い経路を使っています。編集はそれでも届きます」と表示して知らせます。

サーバーの手前でプロキシを運用している場合は、それでも WebSocket アップグレードを通してください。ロングポーリングも動作しますが、編集のまとまりごとに追加のリクエストが必要になり、遅延も少し増えます。

30 秒未満で、通信のないリクエストを閉じるプロキシがあります。たとえば、短い proxy_read_timeout を設定した nginx です。そうしたプロキシは、ロングポーリングのリクエストに 502 または 504 のエラーを返し、編集が遅れて届きます。OLEAFLY_POLL_HOLD_SECONDS は、そのタイムアウトより数秒短くしてください。タイムアウトが 10 秒なら 8 です。

サーバーがクライアントのアドレスを記録するのは、2 か所です。セキュリティログと、1 つのアドレスがサインインを開始したりライブ接続を開いたりできる頻度の制限です。

この設定がない場合、サーバーは、接続してきたものそのもののアドレスを使います。プロキシの内側では、それは常にプロキシなので、全員が 1 つの制限を共有し、セキュリティログにはプロキシのアドレスしか表示されません。

OLEAFLY_BEHIND_PROXY=true にすると、サーバーは X-Forwarded-For ヘッダーを読み取り、その最後のアドレス(プロキシが追加したもの)を使います。ヘッダーがない場合や、有効なアドレスが含まれていない場合は、接続元のアドレスにフォールバックします。ほかに変わることはありません。サーバーは X-Forwarded-Proto、X-Forwarded-Host、Forwarded を無視し、自分が発行するアドレスはすべて OLEAFLY_PUBLIC_URL から組み立てます。

すべてのリクエストがプロキシ経由で届く場合にだけ、オンにしてください。ユーザーがサーバーに直接アクセスすることもできる場合、誰でも偽の X-Forwarded-For を送って、セキュリティログに好きなアドレスを記録させ、サインインの制限を回避できてしまいます。

プロキシが 2 つ連続している場合(たとえば Coolify のプロキシの手前に Cloudflare がある場合)は、OLEAFLY_PROXY_HOPS=2 を設定します。サーバーは、末尾から 2 番目のアドレスを使います。数えるのは、すべてのリクエストが通過するプロキシだけです。サーバーに直接つながる Cloudflare Tunnel は 1 つと数えます。

この数を確認するには、自分のコンピュータからサインインし、管理コンソールのセキュリティログを開きます。最新の項目に、あなたのパブリックアドレスが表示されるはずです。ifconfig.me のようなサイトが示すアドレスです。代わりにプライベートアドレスや Cloudflare のアドレスが表示される場合は、OLEAFLY_PROXY_HOPS を 1 つ増やします。

Caddy は、追加の設定なしで WebSocket 接続と X-Forwarded-For を通し、証明書も自分で取得します。Caddyfile の全体は、手前に HTTPS を置くにあります。

まず、certbot などでドメインの証明書を取得します。次に、これを /etc/nginx/conf.d/oleafly.conf として保存し、sudo nginx -t && sudo systemctl reload nginx を実行します。

map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
server_name collab.example.org;
ssl_certificate /etc/letsencrypt/live/collab.example.org/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/collab.example.org/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_read_timeout 1h;
proxy_send_timeout 1h;
client_max_body_size 200m;
}
}

client_max_body_size は、OLEAFLY_MAX_PROJECT_MB の既定値である 200 に合わせています。どちらかを引き上げたら、もう一方も引き上げてください。

Apache 2.4.47 以降が必要です。Debian 12 と Ubuntu 22.04 以降には含まれています。モジュールを有効にします。

ターミナルウィンドウ
sudo a2enmod proxy proxy_http ssl

これを /etc/apache2/sites-available/oleafly.conf として保存し、sudo a2ensite oleafly && sudo systemctl reload apache2 を実行します。

<VirtualHost *:443>
ServerName collab.example.org
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/collab.example.org/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/collab.example.org/privkey.pem
ProxyPreserveHost On
ProxyPass / http://127.0.0.1:8080/ upgrade=websocket timeout=3600
ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>

upgrade=websocket が WebSocket 接続を通し、timeout=3600 がその接続を 1 時間開いたままにします。Apache は、クライアントのアドレスを X-Forwarded-For に自分で追加します。

サーバーをパスの下で動かす場合は、OLEAFLY_PUBLIC_URL(たとえば https://www.cs.example.edu/oleafly)と、サインインプロバイダに登録するコールバックのアドレスに、そのパスを含めます。サーバーはそのパスがあってもなくても応答するため、プロキシはパスをそのまま渡しても、取り除いてもかまいません。nginx では、location /oleafly/ { を使い、中の行は同じにします。そして proxy_pass http://127.0.0.1:8080; はパスなしのままにして、nginx がパスをそのまま渡すようにします。

1 つのネットワーク上のクラスのための制限

「1 つのネットワーク上のクラスのための制限」セクション

クラス全体が、大学の NAT など、1 つのネットワークアドレスからサインインすることはよくあります。既定値は、それを想定して設定されています。

  • サインイン:1 つのアドレスにつき、300 件のサインインリクエストをまとめて送れ、その後は 1 秒に 2 件です。1 回のサインインに約 6 件使うので、50 人が同時にサインインできます。OLEAFLY_SIGN_IN_BURST と OLEAFLY_SIGN_IN_PER_MINUTE で変更できます。
  • メールのリンク:1 つのアドレスに 15 分間で 100 通、1 つのメールアドレスに 3 通です。OLEAFLY_EMAIL_LINKS_PER_IP と OLEAFLY_EMAIL_LINKS_PER_ADDRESS で変更できます。
  • サインインコード:1 つのアドレスから 10 分間に、100 個のコードのリクエストと、10 回の誤ったコードの入力です。OLEAFLY_DEVICE_CODES_PER_IP で変更できます。
  • ライブ接続には専用のより大きな制限があるため、1 つのアドレスの背後にいるクラス全体が、再起動後にまとめて再接続できます。この制限を消費するのは、セッションの証明に失敗する接続だけで、300 件のバーストの後は 1 秒に 10 件です。セッションを証明した接続は、そのデバイス自身の制限に数えられ、バーストで 60 回、その後は 1 秒に 1 回再接続できます。

1 つの /64 ネットワーク内のすべての IPv6 アドレスは、1 つのアドレスとして数えられます。これらの制限がユーザー単位で機能するのは、サーバーが各ユーザーの実際のアドレスを見られる場合だけなので、プロキシを正しく設定してください。

サーバーは、各ライブ接続に 30 秒ごとに ping を送ります。その ping に 90 秒間応答しない接続と、サーバーが送るものを読まなくなった接続は、閉じられます。

プロジェクトの制限は全員に適用されます。プロジェクト全体には OLEAFLY_MAX_PROJECT_MB(既定では 200 MB)、1 つのファイルには OLEAFLY_MAX_FILE_MB(50 MB)、1 つのプロジェクトの人数には OLEAFLY_MAX_MEMBERS_PER_PROJECT(20 人)です。管理コンソールの概要に、現在の制限が表示されます。

各アカウントには、3 つの上限が適用されます。設定するまではオフですが、オープンサインアップがオンの場合は、次の既定値でオンになります。

上限設定オープンサインアップの場合
アカウントが所有するプロジェクトのストレージOLEAFLY_ACCOUNT_STORAGE_MB100 MB
アカウントが所有する共有プロジェクトOLEAFLY_MAX_PROJECTS_PER_ACCOUNT50
アカウントが 1 時間に行うアップロードOLEAFLY_UPLOADS_PER_HOUR300

設定した値は、常に既定値より優先されます。どの値も、1 以上の整数にする必要があります。

  • ストレージは、アカウントが所有するすべてのプロジェクト(アーカイブ済みのものを含む)のファイルと変更履歴、そしてそのコンパイル済みの PDF を合計します。スナップショットは数えません。プロジェクトに追加されたファイルは、誰が追加したものでも、プロジェクトの所有者の分として数えられます。所有者のアカウントがいっぱいになると、サーバーはその人のプロジェクトへの新しいファイルとコンパイル済みの PDF を拒否し、所有者はほかのプロジェクトを共有できなくなります。ファイルは、追加した人のコンピュータに残ります。入力したテキストは引き続き同期されます。
  • 共有プロジェクトは、アカウントが共有しているプロジェクトを、まだアップロード中のものも含めて数えます。アーカイブ済みのプロジェクトは数えないので、どれか 1 つの共有を停止すると空きができます。
  • アップロードは、1 時間の枠の中で行われたすべてのファイルとスナップショットのアップロードを数えます。コンパイル済みの PDF は数えません。拒否されたファイルは、あとで Oleafly が自動で送り直します。

管理コンソールの概要には、これらの上限は表示されません。オープンサインアップがオンの場合は、サーバーのログが起動のたびにそれらを示します。

  • サーバーログは、docker compose logs oleafly-server、Coolify の Logs、journalctl -u oleafly-server で表示されるものです。OLEAFLY_LOG_LEVEL で記録する量を設定します。
  • セキュリティログには、サインインと拒否されたサインイン、デバイス、ユーザー、役割、設定、プロジェクト、ゲストが、それぞれ時刻と IP アドレスとともに記録されます。管理者とメンテナーは、管理コンソールのセキュリティログで読めます。OLEAFLY_SECURITY_LOG_DAYS 日より古い項目は削除されます。
  • プロジェクトのアクセスログには、誰がプロジェクトを開いたか、参加したか、コピーをダウンロードしたかが、デバイス名と時刻とともに記録されます。プロジェクトのアクセスログを許可がオンのとき、プロジェクトの所有者がオンにでき、読めるのもその所有者だけです。保持期間は同じです。

完全なバックアップに何が必要かは、ファイルの保存先によって決まります。

  • ディスク上のファイル(OLEAFLY_BLOB_STORE=fs、既定):データベース、ファイル、スナップショットはすべてデータフォルダにあります。フォルダ全体をバックアップします。
  • バケット内のファイル:データフォルダにはデータベースがあり、バケットにはファイルとスナップショットがあります。データベースのコピーとバケットを合わせたものが、完全なバックアップです。誤って削除したオブジェクトを元に戻せるよう、バケットのバージョニングをオンにしてください。
サーバーのデータの保存場所とバックアップ対象ファイルをディスクに置く場合(デフォルト)は、データフォルダにデータベースと、ファイルとスナップショットを入れた blobs フォルダが入るので、フォルダ全体をバックアップします。ファイルをバケットに置く場合は、データフォルダにデータベースが入り、S3 バケットにファイルとスナップショットが入るので、データベースとバケットをバックアップします。ディスク上のファイル(デフォルト)バケット内のファイルoleafly-serverデータフォルダデータベース: アカウント、設定、ログblobs: ファイルとスナップショットフォルダ全体をバックアップoleafly-serverデータフォルダデータベースS3 バケットファイルとスナップショットデータベースとバケットをバックアップサーバーのデータの保存場所とバックアップ対象ファイルをディスクに置く場合(デフォルト)は、データフォルダにデータベースと、ファイルとスナップショットを入れた blobs フォルダが入るので、フォルダ全体をバックアップします。ファイルをバケットに置く場合は、データフォルダにデータベースが入り、S3 バケットにファイルとスナップショットが入るので、データベースとバケットをバックアップします。ディスク上のファイル(デフォルト)バケット内のファイルoleafly-serverデータフォルダデータベースと blobs(ファイル、スナップショット)フォルダ全体をバックアップoleafly-serverデータフォルダデータベースS3 バケットファイルとスナップショットデータベースとバケットをバックアップ
完全なバックアップに必要なものは、ファイルの保存場所によって決まります。

バックアップは定期的に取り、コピーはすべてのプロジェクトを含むため非公開にしてください。.env などの設定はデータフォルダにないので、そのコピーも保管してください。

Docker では、ボリュームをコピーする間、サーバーが数秒間停止します。Oleafly は自動で再接続します。これらのコマンドは、サーバーのフォルダで実行します。インストーラーを使った場合は /opt/oleafly-server です。

ターミナルウィンドウ
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo docker run --rm -v oleafly-server_oleafly-data:/data:ro -v "$PWD":/backup debian:13.7-slim tar -C /data -czf /backup/oleafly-data-$(date +%F).tar.gz .
sudo docker compose start oleafly-server

systemd の場合:

ターミナルウィンドウ
sudo systemctl stop oleafly-server
sudo tar -C /var/lib/private/oleafly-server -czf /root/oleafly-data-$(date +%F).tar.gz .
sudo systemctl start oleafly-server

アーカイブは別のマシンにコピーしてください。

Coolify では、ボリューム名はリソースの ID で始まります。docker volume ls --filter name=oleafly-data で見つけ、oleafly-server_oleafly-data の代わりに使い、サーバーの停止と起動は docker compose ではなく Coolify のダッシュボードから行います。

一度も復元したことのないバックアップは、希望にすぎません。この演習では、バックアップからサーバーの 2 つ目のコピーを起動し、動作中のサーバーには手を加えず、両者が同じサーバーであることを確認します。2026-10-11 の代わりに、自分のアーカイブの日付を使ってください。

ターミナルウィンドウ
cd /opt/oleafly-server
sudo docker volume create oleafly-restore-drill
sudo docker run --rm -v oleafly-restore-drill:/data -v "$PWD":/backup:ro debian:13.7-slim tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz
sudo docker run -d --name oleafly-restore-drill -v oleafly-restore-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"
sudo docker run --rm --network container:oleafly-restore-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-server
curl -fsS https://collab.example.org/.well-known/oleafly-server

2 つの応答の server_id が一致している必要があります。演習用のコピーには、誰もサインインできないダミーの GitHub サインインがあり、開いているポートもないため、誰も使えません。終わったら削除します。

ターミナルウィンドウ
sudo docker rm -f oleafly-restore-drill
sudo docker volume rm oleafly-restore-drill

Docker Compose で実際に復元するには、サーバーを停止し、ボリュームの中身をアーカイブで置き換えて、再び起動します。

ターミナルウィンドウ
cd /opt/oleafly-server
sudo docker compose stop oleafly-server
sudo docker run --rm -v oleafly-server_oleafly-data:/data -v "$PWD":/backup:ro debian:13.7-slim sh -c 'find /data -mindepth 1 -delete && tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz'
sudo docker compose start oleafly-server

systemd の場合:

ターミナルウィンドウ
sudo systemctl stop oleafly-server
sudo find /var/lib/private/oleafly-server -mindepth 1 -delete
sudo tar -C /var/lib/private/oleafly-server -xzf /root/oleafly-data-2026-10-11.tar.gz
sudo systemctl start oleafly-server

復元されたサーバーには、バックアップの後にユーザーが行った変更がありません。各アプリは、開いたままでも後から開いた場合でも、再接続したときにそれに気づき、足りない自分の変更を再送します。そのために誰かが何かをする必要はありません。他のユーザーの欠けた変更を土台にした変更は、そのユーザーがプロジェクトを開くまで待機します。そのユーザーの変更を送れるのは、そのユーザーのアプリだけだからです。障害の前後に編集していた全員に、プロジェクトを一度開くよう依頼してください。

アーカイブに入っているのは、作成した時点にあったものだけです。Litestream (新しいタブで開きます) は、サーバーのデータベースへの変更を、発生の約 1 秒後に S3 互換のバケットへコピーします。Compose ファイルには、オプションのサービスとして含まれています。

Litestream がコピーするのはデータベースだけです。ファイルがバケットにある場合は、バケットにファイルとスナップショットがすでにあるため、Litestream のコピーとバケットがあれば、失われたディスクを復元できます。ファイルがディスク上にある場合は、Litestream が blobs フォルダをコピーしないため、ボリュームのアーカイブも引き続き作成してください。

  1. バケット(またはバケット内のフォルダ)を作成し、このサーバーの Litestream だけが使うようにします。OLEAFLY_BLOB_STORE と共有しないでください。Litestream には、バケットの一覧表示と、バケット内のオブジェクトの読み取り、書き込み、削除ができるキーを渡します。

  2. 詳細を .env に追加します。

    ターミナルウィンドウ
    LITESTREAM_REPLICA_URL=s3://lab-backups/oleafly-server
    LITESTREAM_REGION=eu-west-1
    LITESTREAM_ACCESS_KEY_ID=your-access-key-id
    LITESTREAM_SECRET_ACCESS_KEY=your-secret-access-key
    COMPOSE_PROFILES=litestream

    Amazon S3 以外のストアでは、LITESTREAM_ENDPOINT にそのアドレスを、LITESTREAM_REGION にそのストアが期待するリージョン(R2 では auto)も設定します。COMPOSE_PROFILES により、すべての docker compose コマンドに Litestream が含まれるようになります。

  3. 起動します。

    ターミナルウィンドウ
    sudo docker compose up -d
  4. データベースがコピーされたことを確認します。snapshot complete を含む行が表示されます。

    ターミナルウィンドウ
    sudo docker compose logs litestream | grep 'snapshot complete'

Litestream は 1 日に 1 回、完全なコピーを取り、1 週間分のコピーと、その間の変更を保持します。スケジュールは litestream.yml にあります。

この演習では、バケットからデータベースを一時的なボリュームに復元し、その上でサーバーの 2 つ目のコピーを起動して、両者が同じサーバーであることを確認します。動作中のサーバーには手を加えません。

ターミナルウィンドウ
cd /opt/oleafly-server
sudo docker run --rm -v oleafly-litestream-drill:/data "$(sudo docker compose images -q oleafly-server)" --version
sudo docker compose run --rm --no-deps -v oleafly-litestream-drill:/restore litestream restore -config /etc/litestream.yml -o /restore/oleafly-server.sqlite3 /data/oleafly-server.sqlite3
sudo docker run -d --name oleafly-litestream-drill -v oleafly-litestream-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"
sudo docker run --rm --network container:oleafly-litestream-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-server
curl -fsS https://collab.example.org/.well-known/oleafly-server

最初のコマンドは、サーバーに必要な所有者を設定して、一時的なボリュームを作成します。最後の 2 つの応答の server_id が一致している必要があります。終わったらコピーを削除します。

ターミナルウィンドウ
sudo docker rm -f oleafly-litestream-drill
sudo docker volume rm oleafly-litestream-drill

Litestream からデータベースを復元する

「Litestream からデータベースを復元する」セクション

データベースファイルが壊れたか失われたものの、データフォルダのそれ以外が無事な場合は、サーバーと Litestream を停止し、残っているデータベースを削除し、復元してから、再び起動します。

ターミナルウィンドウ
cd /opt/oleafly-server
sudo docker compose stop oleafly-server litestream
sudo docker run --rm -v oleafly-server_oleafly-data:/data debian:13.7-slim rm -rf /data/oleafly-server.sqlite3 /data/oleafly-server.sqlite3-wal /data/oleafly-server.sqlite3-shm /data/.oleafly-server.sqlite3-litestream
sudo docker compose run --rm --no-deps litestream restore -config /etc/litestream.yml /data/oleafly-server.sqlite3
sudo docker compose up -d

ファイルをバケットに置いた状態でディスクを失った場合は、新しい空のボリュームで上記のコマンドを実行し、.env のバケット設定を同じままにします。すべてのプロジェクトが、ファイルとスナップショットとともに戻ります。

ファイルをディスク上に置いた状態でディスクを失った場合は、最新のアーカイブを復元して、それ以上は何もしません。古いアーカイブの上に、Litestream の新しいデータベースを重ねないでください。データベースが、アーカイブにないファイルやスナップショットを指すことになり、それらのプロジェクトが開かなくなります。

先にバックアップします。サーバーは、新しいリリースが初めて起動したときにデータベースを更新するため、古いリリースに戻すには、更新前に取ったバックアップを復元することになります。

  • 1 つのコマンドでのインストール:curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update を実行します。.env はそのままに、新しいリリースのファイルとイメージを取得し、サーバーを再起動します。
  • Docker Compose を手動で使う場合:Docker Compose を手動で使うと同じように新しいリリースのファイルをサーバーのフォルダにダウンロードし、sudo docker compose up -d を実行します。
  • Coolify:Redeploy を選びます。公開済みのイメージを使っている場合は、イメージのタグの下で最新のリリースが取得されます。
  • Render:サービスを開いて手動デプロイを開始します。イメージが再び取得されます。
  • Railway:メニューからサービスをもう一度デプロイします。Railway は、GitHub のレジストリのイメージを自動で更新することもできます。
  • systemd:サーバーをダウンロードすると同じように新しいリリースをインストールし、sudo systemctl restart oleafly-server を実行します。

Oleafly は、接続のたびにサーバーのバージョンを確認します。アプリとサーバーの組み合わせで動作しない場合は、Oleafly がどちらの更新が必要かを知らせます。

画像のプレビュー

AI の回答を読み込めませんでした

もう一度試すか、ドキュメントを検索してください。