サーバーを運用する
ストレージ、バックアップ、上限
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_NAME | Oleafly でユーザーに表示される名前(Smith Lab など)。 | Oleafly Server |
OLEAFLY_SERVER_ICON_URL | 名前の横に表示される正方形の画像の HTTPS アドレス。 | なし |
OLEAFLY_SETUP_CODE | 自分で決める 1 回限りのセットアップコード。英数字で 12 文字以上とし、ダッシュやスペースを入れてもかまいません。指定しない場合は、サーバーが生成します。 | 自動生成 |
OLEAFLY_GITHUB_CLIENT_ID, OLEAFLY_GITHUB_CLIENT_SECRET | GitHub でのサインインをオンにします。 | オフ |
OLEAFLY_GITHUB_URL | GitHub Enterprise Server のアドレス。 | https://github.com |
OLEAFLY_GITHUB_API_URL | GitHub API のアドレス。特殊な場合にだけ設定します。 | https://api.github.com、または OLEAFLY_GITHUB_URL の下の /api/v3 |
OLEAFLY_GITHUB_LABEL | GitHub のサインインボタンに表示するテキスト。 | 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_ENDPOINT | Amazon 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_MB | 1 つのファイルの最大サイズ(メガバイト単位)。 | 50 |
OLEAFLY_MAX_MEMBERS_PER_PROJECT | 1 つのプロジェクトの最大人数。 | 20 |
OLEAFLY_ACCOUNT_STORAGE_MB | 1 つのアカウントが所有するプロジェクトが保存できる最大量(メガバイト単位)。アカウントごとの上限をお読みください。 | 上限なし。オープンサインアップでは 100 |
OLEAFLY_MAX_PROJECTS_PER_ACCOUNT | 1 つのアカウントが所有できる共有プロジェクトの最大数。 | 上限なし。オープンサインアップでは 50 |
OLEAFLY_UPLOADS_PER_HOUR | 1 つのアカウントが 1 時間に行えるファイルとスナップショットのアップロードの回数。 | 上限なし。オープンサインアップでは 300 |
OLEAFLY_SIGN_IN_BURST | 1 つのネットワークアドレスが、短時間にまとめて送れるサインインリクエストの数。1 回のサインインに約 6 件使うため、既定値は、同じアドレスの 50 人が同時にサインインできる数です。 | 300 |
OLEAFLY_SIGN_IN_PER_MINUTE | バーストの後に、1 つのネットワークアドレスに 1 分ごとに戻されるサインインリクエストの数。 | 120 |
OLEAFLY_EMAIL_LINKS_PER_IP | 1 つのネットワークアドレスのユーザーに対して、サーバーが 15 分間に送るサインインメールの数。 | 100 |
OLEAFLY_EMAIL_LINKS_PER_ADDRESS | 1 つのメールアドレスが 15 分間に受け取れるサインインメールの数。OLEAFLY_EMAIL_LINKS_PER_IP を超えることはできません。 | 3 |
OLEAFLY_DEVICE_CODES_PER_IP | 1 つのネットワークアドレスのユーザーが 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 に残るため、サーバーにはデータフォルダが引き続き必要です。
-
バケットを作成し、パブリックアクセスをブロックします。
-
そのバケット内のオブジェクトの読み取り、書き込み、削除ができ、それ以外はできないキーを作成します。Amazon S3 では、
arn:aws:s3:::lab-bucket/*(フォルダを使う場合はarn:aws:s3:::lab-bucket/oleafly/*)に対するs3:GetObject、s3:PutObject、s3:DeleteObjectを意味します。 -
変数を設定します。たとえば
.envに次のように書きます。ターミナルウィンドウ OLEAFLY_BLOB_STORE=s3://lab-bucket/oleaflyOLEAFLY_S3_REGION=eu-west-1OLEAFLY_S3_ACCESS_KEY_ID=your-access-key-idOLEAFLY_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
「コンパイル済みの PDF」セクション所有者または編集者が共有プロジェクトのコンパイルに成功すると、そのアプリは 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 です。
OLEAFLY_BEHIND_PROXY が変えるもの
「OLEAFLY_BEHIND_PROXY が変えるもの」セクションサーバーがクライアントのアドレスを記録するのは、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
「Caddy」セクションCaddy は、追加の設定なしで WebSocket 接続と X-Forwarded-For を通し、証明書も自分で取得します。Caddyfile の全体は、手前に HTTPS を置くにあります。
nginx
「nginx」セクションまず、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
「Apache」セクション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_MB | 100 MB |
| アカウントが所有する共有プロジェクト | OLEAFLY_MAX_PROJECTS_PER_ACCOUNT | 50 |
| アカウントが 1 時間に行うアップロード | OLEAFLY_UPLOADS_PER_HOUR | 300 |
設定した値は、常に既定値より優先されます。どの値も、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、既定):データベース、ファイル、スナップショットはすべてデータフォルダにあります。フォルダ全体をバックアップします。 - バケット内のファイル:データフォルダにはデータベースがあり、バケットにはファイルとスナップショットがあります。データベースのコピーとバケットを合わせたものが、完全なバックアップです。誤って削除したオブジェクトを元に戻せるよう、バケットのバージョニングをオンにしてください。
バックアップは定期的に取り、コピーはすべてのプロジェクトを含むため非公開にしてください。.env などの設定はデータフォルダにないので、そのコピーも保管してください。
Docker では、ボリュームをコピーする間、サーバーが数秒間停止します。Oleafly は自動で再接続します。これらのコマンドは、サーバーのフォルダで実行します。インストーラーを使った場合は /opt/oleafly-server です。
cd /opt/oleafly-serversudo docker compose stop oleafly-serversudo 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-serversystemd の場合:
sudo systemctl stop oleafly-serversudo 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-serversudo docker volume create oleafly-restore-drillsudo 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.gzsudo 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-servercurl -fsS https://collab.example.org/.well-known/oleafly-server2 つの応答の server_id が一致している必要があります。演習用のコピーには、誰もサインインできないダミーの GitHub サインインがあり、開いているポートもないため、誰も使えません。終わったら削除します。
sudo docker rm -f oleafly-restore-drillsudo docker volume rm oleafly-restore-drillDocker Compose で実際に復元するには、サーバーを停止し、ボリュームの中身をアーカイブで置き換えて、再び起動します。
cd /opt/oleafly-serversudo docker compose stop oleafly-serversudo 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-serversystemd の場合:
sudo systemctl stop oleafly-serversudo find /var/lib/private/oleafly-server -mindepth 1 -deletesudo tar -C /var/lib/private/oleafly-server -xzf /root/oleafly-data-2026-10-11.tar.gzsudo systemctl start oleafly-server復元されたサーバーには、バックアップの後にユーザーが行った変更がありません。各アプリは、開いたままでも後から開いた場合でも、再接続したときにそれに気づき、足りない自分の変更を再送します。そのために誰かが何かをする必要はありません。他のユーザーの欠けた変更を土台にした変更は、そのユーザーがプロジェクトを開くまで待機します。そのユーザーの変更を送れるのは、そのユーザーのアプリだけだからです。障害の前後に編集していた全員に、プロジェクトを一度開くよう依頼してください。
Litestream による継続的なコピー
「Litestream による継続的なコピー」セクションアーカイブに入っているのは、作成した時点にあったものだけです。Litestream (新しいタブで開きます) は、サーバーのデータベースへの変更を、発生の約 1 秒後に S3 互換のバケットへコピーします。Compose ファイルには、オプションのサービスとして含まれています。
Litestream がコピーするのはデータベースだけです。ファイルがバケットにある場合は、バケットにファイルとスナップショットがすでにあるため、Litestream のコピーとバケットがあれば、失われたディスクを復元できます。ファイルがディスク上にある場合は、Litestream が blobs フォルダをコピーしないため、ボリュームのアーカイブも引き続き作成してください。
-
バケット(またはバケット内のフォルダ)を作成し、このサーバーの Litestream だけが使うようにします。
OLEAFLY_BLOB_STOREと共有しないでください。Litestream には、バケットの一覧表示と、バケット内のオブジェクトの読み取り、書き込み、削除ができるキーを渡します。 -
詳細を
.envに追加します。ターミナルウィンドウ LITESTREAM_REPLICA_URL=s3://lab-backups/oleafly-serverLITESTREAM_REGION=eu-west-1LITESTREAM_ACCESS_KEY_ID=your-access-key-idLITESTREAM_SECRET_ACCESS_KEY=your-secret-access-keyCOMPOSE_PROFILES=litestreamAmazon S3 以外のストアでは、
LITESTREAM_ENDPOINTにそのアドレスを、LITESTREAM_REGIONにそのストアが期待するリージョン(R2 ではauto)も設定します。COMPOSE_PROFILESにより、すべてのdocker composeコマンドに Litestream が含まれるようになります。 -
起動します。
ターミナルウィンドウ sudo docker compose up -d -
データベースがコピーされたことを確認します。
snapshot completeを含む行が表示されます。ターミナルウィンドウ sudo docker compose logs litestream | grep 'snapshot complete'
Litestream は 1 日に 1 回、完全なコピーを取り、1 週間分のコピーと、その間の変更を保持します。スケジュールは litestream.yml にあります。
Litestream の復元の演習
「Litestream の復元の演習」セクションこの演習では、バケットからデータベースを一時的なボリュームに復元し、その上でサーバーの 2 つ目のコピーを起動して、両者が同じサーバーであることを確認します。動作中のサーバーには手を加えません。
cd /opt/oleafly-serversudo docker run --rm -v oleafly-litestream-drill:/data "$(sudo docker compose images -q oleafly-server)" --versionsudo 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.sqlite3sudo 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-servercurl -fsS https://collab.example.org/.well-known/oleafly-server最初のコマンドは、サーバーに必要な所有者を設定して、一時的なボリュームを作成します。最後の 2 つの応答の server_id が一致している必要があります。終わったらコピーを削除します。
sudo docker rm -f oleafly-litestream-drillsudo docker volume rm oleafly-litestream-drillLitestream からデータベースを復元する
「Litestream からデータベースを復元する」セクションデータベースファイルが壊れたか失われたものの、データフォルダのそれ以外が無事な場合は、サーバーと Litestream を停止し、残っているデータベースを削除し、復元してから、再び起動します。
cd /opt/oleafly-serversudo docker compose stop oleafly-server litestreamsudo 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-litestreamsudo docker compose run --rm --no-deps litestream restore -config /etc/litestream.yml /data/oleafly-server.sqlite3sudo 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 がどちらの更新が必要かを知らせます。