> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  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í).
</Warning>

### 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.

<Info>
  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.
</Info>

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](/cs/on-premises/configuration/overleaf-toolkit/templates#transferring-templates-from-overleaf.com "mention").

<Info>
  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.
</Info>

## 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:

```dotenv title="config/overleaf.rc" theme={null}
SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true
```

#### Pro uživatele Docker Compose

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

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`).

```yml theme={null}
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

<Info>
  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`.
</Info>

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` <strong>(povinné)</strong>: 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` <strong>(povinné)</strong>: Čárkami oddělený seznam srozumitelných názvů image, používaných pro volby ve frontendu.
* `ALL_TEX_LIVE_DOCKER_IMAGES` <strong>(povinné)</strong>: Čá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.

<Tabs>
  <Tab title="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ě.

    ```dotenv title="config/variables.env" wrap theme={null}
    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
    ```
  </Tab>

  <Tab title="Ú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ě.

    ```dotenv title="config/variables.env" wrap theme={null}
    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
    ```
  </Tab>
</Tabs>

<Danger>
  Důrazně doporučujeme nastavit **alespoň 2 image texlive-full**. Podrobné zdůvodnění najdete v [#known-issues](/cs/on-premises/configuration/overleaf-toolkit/sandboxed-compiles#known-issues "mention")
</Danger>

### 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`

<Warning>
  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).
</Warning>

### 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:

```dotenv title="config/variables.env" wrap theme={null}
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í:

```mjs title="sandboxed-compiles/index.mjs" wrap expandable theme={null}
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](/cs/on-premises/maintenance/updating-tex-live-full-images-automatically "mention").

### 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í:
>
> ```dotenv theme={null}
> 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:
>
> ```dotenv theme={null}
> 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í:
>
> ```text wrap theme={null}
> {"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`

```text theme={null}
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.

```text theme={null}
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:

```bash wrap theme={null}
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](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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.