Sandboxed Compiles

Ayakaleaf Pro には、エンタープライズレベルのセキュリティのために、コンパイルを安全なサンドボックス環境で実行するオプションが用意されています。これは、各プロジェクトをそれぞれ専用の安全な Docker 環境で実行することで実現されます。

​

セキュリティの向上

多くの LaTeX ドキュメントは PDF コンパイル処理の一部として任意のシェルコマンドを実行する必要がある(または実行できる)ため、Ayakaleaf Pro では Sandboxed Compiles の使用が推奨されます。Sandboxed Compiles を使用すると、各コンパイルは機能が制限された個別の Docker コンテナで実行されます。このコンテナは他のユーザーやプロジェクトと共有されず、ホストネットワークなどの外部リソースにもアクセスできません。

Sandboxed Compiles なしで Ayakaleaf Pro を実行しようとすると、コンパイルはメインの Docker コンテナ内で他の同時実行中のコンパイルと並行して実行され、ユーザーは LaTeX のコンパイル実行時に sharelatex コンテナのリソース(ファイルシステム、ネットワーク、環境変数)に対して完全な読み書きアクセス権を持つことになります。

​

パッケージ管理の簡素化

パッケージを手動でインストールする手間を避けるため、Sandboxed Compiles を有効にすることをお勧めします。これは Server Pro 内の設定項目で、オンプレミス環境内でありながら、overleaf.com と同じ TeX Live 環境をユーザーに提供します。Sandboxed Compiles で使用される TeX Live イメージには、ギャラリーのテンプレートでテスト済みの人気のパッケージとフォントが含まれており、オンプレミスのプロジェクトとの最大限の互換性を確保します。

Sandboxed Compiles を有効にすると、ユーザーがプロジェクト内で選択できる TeX Live のバージョンを設定できるほか、新規プロジェクト用のデフォルトの TeX Live イメージのバージョンも設定できます。

Sandboxed Compiles なしで Ayakaleaf Pro を実行しようとすると、インスタンスはデフォルトで TeX Live の basic scheme 版を使用してコンパイルします。この basic 版は軽量で、ごく限られた LaTeX パッケージしか含まれていないため、特にユーザーが既製のテンプレートを使おうとした場合に、パッケージ不足のエラーが発生する可能性が高くなります。

Ayakaleaf Pro はオフラインで動作するように設計されているため、overleaf.com のギャラリーテンプレートをオンプレミス環境に統合する自動化された方法はありません。ただし、テンプレートごとに手動で行うことは可能です。この仕組みの詳細については、overleaf.com からのテンプレート移行ガイドを参照してください: #transferring-templates-from-overleaf.com。

Sandboxed Compiles では、sharelatex コンテナがこれらの兄弟コンパイルコンテナを管理できるように、(バインドマウントを介して)ホストマシン上の Docker ソケットにアクセスできる必要があります。

​

仕組み

Sandboxed Compiles を有効にすると、ホストマシンの Docker ソケットが sharelatex コンテナにマウントされ、コンテナ内のコンパイラーサービスがホスト上に新しい Docker コンテナを作成できるようになります。その後、各プロジェクトでコンパイラーが実行されるたびに、LaTeX コンパイラーサービス(CLSI)は次の処理を行います。

• プロジェクトファイルを OVERLEAF_DATA_PATH 内の場所に書き出す。
• マウントされた Docker ソケットを使用して、コンパイル実行用の新しい texlive コンテナを作成する。
• texlive コンテナに OVERLEAF_DATA_PATH 配下の場所からプロジェクトデータを読み込ませる。
• texlive コンテナ内でプロジェクトをコンパイルする。

​

Sandboxed Compiles の有効化

​

Toolkit ユーザーの場合

Sandboxed Compiles(兄弟コンテナとも呼ばれます)を有効にするには、overleaf-toolkit/config/overleaf.rc で次の設定オプションを指定します。

config/overleaf.rc

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

Docker Compose ユーザーの場合

Overleaf CE/Server Pro 5.0.3 以降、環境変数は SHARELATEX_* から OVERLEAF_* にリブランディングされました。

4.x バージョン(またはそれ以前)を使用している場合は、変数に適切な接頭辞が付いていることを確認してください(例: OVERLEAF_MONGO_URL ではなく SHARELATEX_MONGO_URL)。

version: '2'
services:
    sharelatex:
        #...
        volumes:
            - /data/overleaf_data:/var/lib/overleaf
            - /var/run/docker.sock:/var/run/docker.sock
        environment:
            #...
            DOCKER_RUNNER: "true"
            SANDBOXED_COMPILES: "true"
            SANDBOXED_COMPILES_HOST_DIR: "/data/overleaf_data/data/compiles"
            #...
        #...

​

TeX Live イメージのセットアップ

中国本土のユーザーは、ダウンロードを高速化するために ghcr.io を ghcr.nju.edu.cn に置き換えることができます。ただし、Toolkit の環境設定で ghcr.nju.edu.cn を直接使用しないでください。ghcr.io を唯一の選択肢として維持する必要があります。

Ayakaleaf Pro は、Sandboxed Compiles で使用する TeX Live イメージを決定するために 3 つの環境変数を使用します。

• TEX_LIVE_DOCKER_IMAGE (必須): 新規プロジェクトのコンパイルに使用されるデフォルトの TeX Live イメージ。このイメージは ALL_TEX_LIVE_DOCKER_IMAGES に含まれている必要があります。
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (必須): フロントエンドの選択肢に使用される、イメージのわかりやすい名前のカンマ区切りリスト。
• ALL_TEX_LIVE_DOCKER_IMAGES (必須): 使用する TeX Live イメージのカンマ区切りリスト。デプロイに Overleaf Toolkit を使用している場合、これらのイメージがダウンロードまたは更新されます。ダウンロードをスキップするには、config/overleaf.rc で SIBLING_CONTAINERS_PULL=false を設定します。

bin/up コマンドで Ayakaleaf Pro インスタンスを起動すると、Toolkit は ALL_TEX_LIVE_DOCKER_IMAGES に記載されているすべてのイメージを自動的に pull します。

以下は、新規プロジェクトのデフォルトを TeX Live 2026 にし、既存のプロジェクト用に 2025 も引き続き使用する例です。

最小インストール

次の設定では、2025 年から 2026 年までのすべてのフル TeX Live Docker イメージをインストールします。この設定を使用する前に、少なくとも 64 GB の空きストレージを用意することをお勧めします。

config/variables.env

ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1, ghcr.io/ayaka-notes/texlive-full:2025.1
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026, Texlive 2025
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

フルインストール

次の設定では、2020 年から 2026 年までのすべてのフル TeX Live Docker イメージをインストールします。この設定を使用する前に、少なくとも 150 GB の空きストレージを用意することをお勧めします。

config/variables.env

ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1,ghcr.io/ayaka-notes/texlive-full:2025.1,ghcr.io/ayaka-notes/texlive-full:2024.1,ghcr.io/ayaka-notes/texlive-full:2023.1,ghcr.io/ayaka-notes/texlive-full:2022.1,ghcr.io/ayaka-notes/texlive-full:2021.1,ghcr.io/ayaka-notes/texlive-full:2020.1
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026,Texlive 2025,Texlive 2024,Texlive 2023,Texlive 2022,Texlive 2021,Texlive 2020
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

少なくとも 2 つの texlive-full イメージを設定することを強く推奨します。詳しい理由は #known-issues を参照してください。

​

利用可能な TeX Live イメージ

以下は Overleaf 向けに特別に最適化された一連の TeX Live イメージで、TEX_LIVE_DOCKER_IMAGE および ALL_TEX_LIVE_DOCKER_IMAGES に追加できます。

• ghcr.io/ayaka-notes/texlive-full:2026.1(latest タグも同じ)
• ghcr.io/ayaka-notes/texlive-full:2025.1
• ghcr.io/ayaka-notes/texlive-full:2024.1
• ghcr.io/ayaka-notes/texlive-full:2023.1
• ghcr.io/ayaka-notes/texlive-full:2022.1
• ghcr.io/ayaka-notes/texlive-full:2021.1
• ghcr.io/ayaka-notes/texlive-full:2020.1

イメージのタグ付けには厳格なスキーマがあり、それに従う必要があります(正規表現 ^[0-9]+.[0-9]+ が適用され、最初の数字が TeX Live の年、2 番目の数字がパッチバージョンを表します)。

​

他のイメージレジストリを使用できますか

ghcr.io を別のミラーサイトに置き換えたり、texlive を Docker Hub の別のイメージに切り替えたりできるのか、と疑問に思う方もいるかもしれません。

設定が比較的複雑になるため、お勧めしません。ミラーサイトからダウンロードしている場合は、イメージの名前を ghcr.io/ayaka-notes/texlive-full に変更できます。

それでも独自のイメージレジストリを使用したい場合は、次を追加してください。

config/variables.env

IMAGE_ROOT=hub.your.com/your-repo

次に、すべての texlive イメージが your-repo に存在することを確認する必要があります。例えば:

• hub.your.com/your-repo/texlive-full:2025.1
• hub.your.com/your-repo/texlive-full:2024.1

詳細については、以下のソースコードを読んで、環境変数がどのように解析されるかを確認してください。

sandboxed-compiles/index.mjs

if (process.env.SANDBOXED_COMPILES === 'true') {
  // Set default image root if not provided
  let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes";
  // Export imageRoot to Settings
  Settings.imageRoot = imageRootPath

  // allowedImageNames should be:
  // [
  //  { imageName: "texlive-2023:latest", imageDesc: "TeX Live 2023" },
  //  { imageName: "texlive-2022:latest", imageDesc: "TeX Live 2022" },
  // ]
  Settings.allowedImageNames = parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGES)
    .map((texImage, index) => ({
      imageName: texImage.split("/")[texImage.split("/").length - 1],
      imageDesc: parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGE_NAMES)[index]
        || texImage.split(':')[1],
    }))
  
  // In the end, imageName will be put together with imageRoot to form the full image path
  // The full name will be like: ghcr.io/ayaka-notes/texlive-2023:latest

  // Set default image name if not provided
  if(!process.env.TEX_LIVE_DOCKER_IMAGE) {
    process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName
  }

  // Export currentImageName to Settings
  // This is the new created projects' image name
  Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE
}

​

TeX Live イメージの自動同期

毎回 bin/up で手動更新する手間を省くために、TeX Live イメージの更新を自動化できます。updating-tex-live-full-images-automatically.md を参照してください。

​

既知の問題

以下は Overleaf コミュニティで実際にあった事例です。

6.0.1-ext-v3.3 を使用しており、variables.env に次の設定をしています。

TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full
ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full

これは texlive/texlive:latest-full では問題なく動作します。しかし、別の texlive イメージ danteev/texlive:2025-10-15 を pull し、両方の変数を新しいイメージ名に変更したところ、動作しません。

TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15
ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15

ログには次のように表示されます。

{"name":"clsi","level":50,"err":{"message":"(HTTP code 404) no such container - No such image: texlive/texlive:latest-full ","name":"Error","stack":"Error: (HTTP code 404) no such container - No such image: texlive/texlive:latest-full ... 

variables.env の更新された設定が反映されていないようです。コンパイルは新しいイメージではなく、依然として texlive/texlive:latest-full イメージを実行しようとします。

再起動したり、コンテナを削除して再実行したりしましたが、同じ問題が発生します。

何か解決策はありますか?

技術的な制約により、texlive-fullA:latest のように Docker TeX Live イメージを 1 つだけ設定している場合、

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

しばらく Overleaf インスタンスを運用した後に、TeX Live イメージを texlive-fullB:latest に変更したくなるかもしれません。すると、ユーザーがすべてのプロジェクトをコンパイルできなくなることがわかります。

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

これは、各プロジェクトの TeX Live Full イメージ(サンドボックスコンパイル用)の名前がデータベースに永続化されているためです。ユーザーがプロジェクトの TeX Live バージョンを切り替えた場合(例えば 2024 から 2025 へ)にのみ、データベース内のイメージ名が変更されます。

CLSI はプロジェクトをコンパイルする際、データベースに記録されているコンテナイメージ名を使用して直接プロジェクトをコンパイルします。

Docker イメージを 1 つしか提供していない場合、ユーザーはプロジェクトのコンパイルに使用するイメージを変更できません。この場合、MongoDB 内のすべてのユーザープロジェクトの TeX Live イメージを手動で変更するスクリプトを作成する必要があります。

​

デバッグと報告

Toolkit から clsi のログを確認するには、次のコマンドを実行します。

bin/logs clsi

TeX Live イメージでのコンパイルで問題が発生した場合は、こちらから issue を送信してください。

https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml

問題の再現とトラブルシューティングのために、プロジェクトを Overleaf にアップロードするようお願いする場合があります。その後、私たちがプロジェクトを取得し、GitHub Action でコンパイルテストを実行します。