Sandboxed Compiles

Ayakaleaf Pro nabízí možnost spouštět kompilace v zabezpečeném izolovaném prostředí (sandboxu) pro podnikovou úroveň zabezpečení. Dosahuje toho tak, že každý projekt spouští ve vlastním zabezpečeném prostředí Dockeru.

​

Vyšší zabezpečení

Sandboxed Compiles jsou pro Ayakaleaf Pro doporučeným přístupem, protože mnoho dokumentů LaTeX vyžaduje (nebo má) možnost spouštět v rámci procesu kompilace PDF libovolné shellové příkazy. Pokud používáte Sandboxed Compiles, každá kompilace běží v samostatném Docker kontejneru s omezenými schopnostmi, který není sdílen s žádným jiným uživatelem ani projektem a nemá přístup k vnějším prostředkům, jako je síť hostitele.

Pokud se pokusíte provozovat Ayakaleaf Pro bez Sandboxed Compiles, kompilace běží spolu s ostatními souběžnými kompilacemi uvnitř hlavního Docker kontejneru a uživatelé mají při kompilaci LaTeXu plný přístup pro čtení i zápis k prostředkům kontejneru sharelatex (souborový systém, síť a proměnné prostředí).

​

Snadnější správa balíčků

Abyste nemuseli balíčky instalovat ručně, doporučujeme povolit Sandboxed Compiles. Jde o konfigurovatelné nastavení v Server Pro, které vašim uživatelům poskytne přístup ke stejnému prostředí TeX Live jako na overleaf.com, ale v rámci vaší vlastní on-premise instalace. Image TeX Live používané Sandboxed Compiles obsahují nejoblíbenější balíčky a fonty otestované proti šablonám z naší galerie, což zajišťuje maximální kompatibilitu s on-premise projekty.

Povolení Sandboxed Compiles vám umožní nakonfigurovat, ze kterých verzí TeX Live si uživatelé mohou v projektu vybírat, a nastavit výchozí verzi image TeX Live pro nové projekty.

Pokud se pokusíte provozovat Ayakaleaf Pro bez Sandboxed Compiles, vaše instance bude ve výchozím stavu ke kompilaci používat verzi TeX Live se schématem basic. Tato základní verze je odlehčená a obsahuje jen velmi omezenou podmnožinu balíčků LaTeX, což u vašich uživatelů nejspíše povede k chybám kvůli chybějícím balíčkům, zejména pokud se pokusí použít předpřipravené šablony.

Protože Ayakaleaf Pro je navržen tak, aby fungoval offline, neexistuje automatizovaný způsob, jak integrovat šablony z galerie overleaf.com do vaší on-premise instalace; je však možné to provést ručně pro každou šablonu zvlášť. Další informace o tom, jak to funguje, najdete v našem návodu na přenos šablon z overleaf.com: #transferring-templates-from-overleaf.com.

Sandboxed Compiles vyžadují, aby kontejner sharelatex měl přístup k Docker socketu na hostitelském stroji (přes bind mount), aby mohl spravovat tyto sourozenecké kompilační kontejnery.

​

Jak to funguje

Když jsou Sandboxed Compiles povoleny, Docker socket z hostitelského stroje se připojí do kontejneru sharelatex, takže kompilační služba v kontejneru může na hostiteli vytvářet nové Docker kontejnery. Poté při každém spuštění kompilátoru v každém projektu provede kompilační služba LaTeXu (CLSI) následující:

• Zapíše soubory projektu do umístění uvnitř OVERLEAF_DATA_PATH.
• Pomocí připojeného Docker socketu vytvoří pro daný běh kompilace nový kontejner texlive.
• Kontejner texlive načte data projektu z umístění pod OVERLEAF_DATA_PATH.
• Zkompiluje projekt uvnitř kontejneru texlive.

​

Povolení Sandboxed Compiles

​

Pro uživatele Toolkitu

Chcete-li povolit sandboxové kompilace (známé také jako sourozenecké kontejnery, Sibling containers), nastavte v overleaf-toolkit/config/overleaf.rc následující konfigurační volby:

config/overleaf.rc

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

Pro uživatele Docker Compose

Počínaje Overleaf CE/Server Pro 5.0.3 byly proměnné prostředí přejmenovány z SHARELATEX_* na OVERLEAF_*.

Pokud používáte verzi 4.x (nebo starší), ujistěte se, že proměnné mají odpovídající předponu (např. SHARELATEX_MONGO_URL místo OVERLEAF_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"
            #...
        #...

​

Nastavení image TeX Live

Uživatelé z pevninské Číny mohou pro zrychlení stahování nahradit ghcr.io adresou ghcr.nju.edu.cn. NEPOUŽÍVEJTE však ghcr.nju.edu.cn přímo v nastavení prostředí toolkitu. Jedinou volbou by mělo zůstat ghcr.io.

Ayakaleaf Pro používá tři proměnné prostředí k určení, které image TeX Live se mají pro Sandboxed Compiles použít:

• TEX_LIVE_DOCKER_IMAGE (povinné): Výchozí image TeX Live používaný ke kompilaci nových projektů. Tento image musí být uveden v ALL_TEX_LIVE_DOCKER_IMAGES.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (povinné): Čárkami oddělený seznam srozumitelných názvů image, používaných pro volby ve frontendu.
• ALL_TEX_LIVE_DOCKER_IMAGES (povinné): Čárkami oddělený seznam image TeX Live, které se mají použít. Pokud se k nasazení používá Overleaf Toolkit, tyto image budou staženy nebo aktualizovány. Chcete-li stahování přeskočit, nastavte v config/overleaf.rc hodnotu SIBLING_CONTAINERS_PULL=false.

Při spouštění instance Ayakaleaf Pro příkazem bin/up Toolkit automaticky stáhne všechny image uvedené v ALL_TEX_LIVE_DOCKER_IMAGES.

Zde je příklad, kde je pro nové projekty výchozí TeX Live 2026 a pro staré projekty se nadále používá verze 2025.

Minimální instalace

Následující konfigurace nainstaluje všechny úplné Docker image TeX Live od roku 2025 do roku 2026. Před použitím této konfigurace doporučujeme mít k dispozici alespoň 64 GB volného úložiště.

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

Úplná instalace

Následující konfigurace nainstaluje všechny úplné Docker image TeX Live od roku 2020 do roku 2026. Před použitím této konfigurace doporučujeme mít k dispozici alespoň 150 GB volného úložiště.

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

Důrazně doporučujeme nastavit alespoň 2 image texlive-full. Podrobné zdůvodnění najdete v #known-issues

​

Dostupné image TeX Live

Toto je řada image TeX Live speciálně optimalizovaných pro Overleaf, které lze také přidat do TEX_LIVE_DOCKER_IMAGE a ALL_TEX_LIVE_DOCKER_IMAGES:

• ghcr.io/ayaka-notes/texlive-full:2026.1 (také tag 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

Pro označování image tagy platí přísné schéma, které musí být dodrženo (uplatňuje se regulární výraz ^[0-9]+.[0-9]+, kde první číslo určuje rok TeX Live a druhé verzi opravy).

​

Mohu použít jiný registr image?

Někteří se mohou ptát, zda lze nahradit ghcr.io jiným zrcadlem nebo přepnout texlive na jiný image z Docker Hubu.

Ne, nedoporučujeme to, protože konfigurace je poměrně složitá. Pokud stahujete ze zrcadla, můžete svůj image přejmenovat na ghcr.io/ayaka-notes/texlive-full.

Pokud ale opravdu chcete používat vlastní registr image, přidejte:

config/variables.env

IMAGE_ROOT=hub.your.com/your-repo

Poté se musíte ujistit, že všechny image texlive jsou v your-repo, například

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

Podrobné informace získáte, když si přečtete níže uvedený zdrojový kód a pochopíte, jak se vaše proměnné prostředí zpracovávají:

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
}

​

Automatická synchronizace image TeX Live

Abyste nemuseli instanci pokaždé ručně aktualizovat pomocí bin/up, můžete aktualizace image TeX Live automatizovat. Viz updating-tex-live-full-images-automatically.md.

​

Známé problémy

Toto je skutečný případ z komunity Overleafu:

Používám 6.0.1-ext-v3.3 a v variables.env mám tato nastavení:

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

S texlive/texlive:latest-full to funguje dobře. Stáhl jsem si však jiný image texlive danteev/texlive:2025-10-15 a obě tyto proměnné jsem změnil na název nového image, ale nefunguje to:

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

V logech vidím následující:

{"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 ... 

Zdá se, že aktualizovaná nastavení ve variables.env se neprojevují. Kompilace se stále pokouší spustit image texlive/texlive:latest-full, nikoli nový image.

Zkoušel jsem restartovat, smazat kontejnery a znovu je spustit, ale problém přetrvává.

Máte nějaké řešení?

Kvůli určitým technickým omezením: pokud nastavíte pouze jeden Docker image TeXLive, například texlive-fullA: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

a po nějaké době provozu instance Overleafu budete chtít změnit image TeXLive na texlive-fullB:latest, zjistíte, že vaši uživatelé nemohou zkompilovat žádné projekty.

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

Je to proto, že název image TeXLive-Full (pro sandboxovou kompilaci) je u každého projektu uložen v databázi. Název image se v databázi změní pouze tehdy, když uživatel přepne verzi TeXLive svého projektu, například z 2024 na 2025.

Když CLSI kompiluje projekt, použije ke kompilaci přímo název image kontejneru nalezený v databázi.

Pokud poskytnete pouze jeden Docker image, uživatelé nebudou moci změnit image používaný ke kompilaci projektu. V takovém případě musíte napsat skript, který v MongoDB ručně změní image TeXLive u všech uživatelských projektů.

​

Ladění a hlášení problémů

Spusťte následující příkaz pro kontrolu logu clsi z toolkitu:

bin/logs clsi

Pokud narazíte na jakékoli problémy s kompilací pomocí image TeX Live, nahlaste je prosím zde:

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

Abychom mohli problém reprodukovat a vyřešit, můžeme vás požádat o nahrání projektu do Overleafu. Projekt si pak stáhneme a spustíme testy kompilace pomocí GitHub Action.