> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/on-premises/pl/konfiguracja/overleaf-toolkit/kompilacjami-w-piaskownicy.md). # Kompilacjami w piaskownicy Overleaf Pro oferuje opcję uruchamiania kompilacji w zabezpieczonym środowisku piaskownicy dla bezpieczeństwa klasy enterprise. Osiąga to, uruchamiając każdy projekt w jego własnym, zabezpieczonym środowisku Docker. ### Lepsze bezpieczeństwo Sandboxed Compiles są zalecanym podejściem dla Server Pro, ponieważ wiele dokumentów LaTeX wymaga lub ma możliwość wykonywania dowolnych poleceń powłoki jako część procesu kompilacji PDF. Jeśli używasz Sandboxed Compiles, każda kompilacja działa w oddzielnym kontenerze Docker z ograniczonymi możliwościami, które nie są współdzielone z żadnym innym użytkownikiem ani projektem i nie ma dostępu do zasobów zewnętrznych, takich jak sieć hosta. {% hint style="warning" %} Jeśli spróbujesz uruchomić Overleaf Pro **bez** Sandboxed Compiles, kompilacja jest uruchamiana obok innych równoległych kompilacji wewnątrz głównego kontenera Docker, a użytkownicy mają pełny dostęp do odczytu i zapisu do `sharelatex` zasobów kontenera (systemu plików, sieci i zmiennych środowiskowych) podczas uruchamiania kompilacji LaTeX. {% endhint %} ### Łatwiejsze zarządzanie pakietami Aby uniknąć ręcznego instalowania pakietów, zalecamy włączenie Sandboxed Compiles. Jest to konfigurowalne ustawienie w Server Pro, które zapewni użytkownikom dostęp do tego samego środowiska TeX Live co na overleaf.com, ale w ramach własnej instalacji on-premise. Obrazy TeX Live używane przez Sandboxed Compiles zawierają najpopularniejsze pakiety i czcionki przetestowane z naszymi szablonami galerii, zapewniając maksymalną zgodność z projektami on-premise. Włączenie Sandboxed Compiles pozwala skonfigurować, które wersje TeX Live użytkownicy mogą wybierać w swoich projektach, a także ustawić domyślną wersję obrazu TeX Live dla nowych projektów. {% hint style="info" %} Jeśli spróbujesz uruchomić Overleaf Pro bez Sandboxed Compiles, twoja instancja domyślnie będzie używać podstawowej wersji schematu TeX Live do kompilacji. Ta podstawowa wersja jest lekka i zawiera tylko bardzo ograniczony podzbiór pakietów LaTeX, co najprawdopodobniej spowoduje błędy brakujących pakietów u twoich użytkowników, szczególnie jeśli spróbują użyć gotowych szablonów. {% endhint %} Ponieważ Overleaf Pro został zaprojektowany do pracy offline, nie ma automatycznego sposobu integrowania szablonów galerii overleaf.com z twoją instalacją on-premise; możliwe jest jednak zrobienie tego ręcznie dla każdego szablonu osobno. Aby uzyskać więcej informacji o tym, jak to działa, zapoznaj się z naszym przewodnikiem dotyczącym przenoszenia szablonów z overleaf.com: [/pages/2c0168fc587979d26089be16b70c42839b424b06#transferring-templates-from-overleaf.com](https://overleaf-pro.ayaka.space/on-premises/pl/konfiguracja/overleaf-toolkit/pages/2c0168fc587979d26089be16b70c42839b424b06#transferring-templates-from-overleaf.com "mention"). {% hint style="info" %} Sandboxed Compiles wymaga, aby `sharelatex` kontener miał dostęp do gniazda Docker na maszynie hosta (za pomocą montowania wiązanego), aby mógł zarządzać tymi sąsiednimi kontenerami kompilacji. {% endhint %} ## Jak to działa Po włączeniu Sandboxed Compiles gniazdo Docker zostanie zamontowane z maszyny hosta do `sharelatex` kontenera, aby usługa kompilatora w kontenerze mogła tworzyć nowe kontenery Docker na hoście. Następnie dla każdego uruchomienia kompilatora w każdym projekcie usługa kompilatora LaTeX (CLSI) wykona następujące czynności: * Zapisze pliki projektu w lokalizacji wewnątrz `OVERLEAF_DATA_PATH`. * Użyje zamontowanego gniazda Docker, aby utworzyć nowy `texlive` kontener do uruchomienia kompilacji. * Spowoduje, że `texlive` kontener odczyta dane projektu z lokalizacji pod `OVERLEAF_DATA_PATH`. * Skompiluje projekt wewnątrz `texlive` kontenerze. ### Włączanie Sandboxed Compiles #### Dla użytkownika Toolkit Aby włączyć sandboxed compiles (znane również jako kontenery rodzeństwa), ustaw następujące opcje konfiguracji w `overleaf-toolkit/config/overleaf.rc`: {% code title="config/overleaf.rc" %} ```dotenv SERVER_PRO=true SIBLING_CONTAINERS_ENABLED=true ``` {% endcode %} #### Dla użytkownika Docker Compose {% hint style="danger" %} Począwszy od Overleaf CE/Server Pro `5.0.3` zmieniono oznaczenie zmiennych środowiskowych z `SHARELATEX_*` na `OVERLEAF_*`. {% endhint %} Jeśli używasz `4.x` wersji (lub wcześniejszej) upewnij się, że zmienne mają odpowiedni prefiks (np. `SHARELATEX_MONGO_URL` zamiast `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"
            #...
        #...
### Zmiana obrazu TexLive {% hint style="info" %} Dla użytkowników z Chin kontynentalnych możesz użyć `ghcr.nju.edu.cn` aby przyspieszyć pobieranie. {% endhint %} Overleaf Pro używa trzech zmiennych środowiskowych, aby określić, których obrazów TeX Live użyć dla Sandboxed Compiles: * `TEX_LIVE_DOCKER_IMAGE` **(wymagane),** Domyślny obraz TeX Live używany do kompilowania nowych projektów. Ten obraz musi być uwzględniony w `ALL_TEX_LIVE_DOCKER_IMAGES`. * `ALL_TEX_LIVE_DOCKER_IMAGE_NAMES` **(wymagane),** Lista przyjaznych nazw obrazów, rozdzielona przecinkami, używana dla opcji interfejsu. * `ALL_TEX_LIVE_DOCKER_IMAGES` **(wymagane),** Lista obrazów TeX Live do użycia, rozdzielona przecinkami. Jeśli do wdrożenia używany jest Overleaf Toolkit, obrazy te zostaną pobrane lub zaktualizowane. Aby pominąć pobieranie, ustaw `SIBLING_CONTAINERS_PULL=false` w `config/overleaf.rc`. Podczas uruchamiania instancji Overleaf Pro za pomocą `bin/up` polecenia Toolkit automatycznie pobierze wszystkie obrazy wymienione w `ALL_TEX_LIVE_DOCKER_IMAGES`. Oto przykład, w którym domyślnie używamy TeX Live 2025 dla nowych projektów, a 2024 pozostaje w użyciu dla istniejących projektów. {% code title="config/variables.env" overflow="wrap" %} ```dotenv ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2025.1, ghcr.io/ayaka-notes/texlive-full:2024.1 ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2025, Texlive 2024 TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2025.1 ``` {% endcode %} {% hint style="danger" %} Zdecydowanie zaleca się ustawienie **co najmniej 2 obrazów texlive-full**. Aby poznać szczegółowe powody, zobacz [#known-issues](#known-issues "mention") {% endhint %} ### Dostępne obrazy TeX Live To seria obrazów TeX Live specjalnie zoptymalizowanych dla Overleaf, które można również dodać do `TEX_LIVE_DOCKER_IMAGE` i `ALL_TEX_LIVE_DOCKER_IMAGES`: * `ghcr.io/ayaka-notes/texlive-full:2025.1` (Także `latest` tag) * `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` {% hint style="warning" %} Istnieje ścisły schemat dotyczący tego, jak obrazy **muszą** być oznaczone (obowiązuje następujące wyrażenie regularne `^[0-9]+.[0-9]+`, w którym pierwsza liczba określa rok TeX Live, a druga wersję poprawki). {% endhint %} ### Czy mogę użyć innego rejestru obrazów > Niektórzy mogą się zastanawiać, czy mogę zastąpić `ghcr.io` inną witryną lustrzaną albo przełączyć texlive na inny obraz z Docker Hub? Nie, nie zalecamy tego, ponieważ konfiguracja jest dość skomplikowana. Jeśli pobierasz z witryny lustrzanej, możesz zmienić nazwę swojego obrazu na `ghcr.io/ayaka-notes/texlive-full`. Ale jeśli naprawdę chcesz użyć własnego rejestru obrazów, dodaj: {% code title="config/variables.env" overflow="wrap" %} ```dotenv IMAGE_ROOT=hub.your.com/your-repo ``` {% endcode %} Następnie musisz upewnić się, że wszystkie obrazy texlive znajdują się w `your-repo`, takie jak * `hub.your.com/your-repo/texlive-full:2025.1` * `hub.your.com/your-repo/texlive-full:2024.1` Aby uzyskać szczegółowe informacje, przeczytaj poniższy kod źródłowy, aby zrozumieć, jak analizujemy twoją zmienną środowiskową: {% code title="sandboxed-compiles/index.mjs" overflow="wrap" expandable="true" %} ```mjs if (process.env.SANDBOXED_COMPILES === 'true') { // Ustaw domyślny katalog obrazu, jeśli nie został podany let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes"; // Wyeksportuj imageRoot do Settings Settings.imageRoot = imageRootPath // allowedImageNames powinny mieć postać: // [ // { 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], })) // Ostatecznie imageName zostanie połączony z imageRoot, aby utworzyć pełną ścieżkę obrazu // Pełna nazwa będzie wyglądać tak: ghcr.io/ayaka-notes/texlive-2023:latest // Ustaw domyślną nazwę obrazu, jeśli nie została podana if(!process.env.TEX_LIVE_DOCKER_IMAGE) { process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName } // Wyeksportuj currentImageName do Settings // To jest nazwa obrazu dla nowo utworzonych projektów Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE } ``` {% endcode %} ### Znane problemy > Używając `6.0.1-ext-v3.3`, mam następujące ustawienia w `variables.env`: > > ```dotenv > TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full > ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full > ``` > > To działa poprawnie z `texlive/texlive:latest-full`. Jednak pobrałem inny obraz texlive `danteev/texlive:2025-10-15` i zmieniłem obie te zmienne na nową nazwę obrazu, ale to nie działa: > > ```dotenv > TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15 > ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15 > ``` > > W logach widzę następujące informacje: > > {% code overflow="wrap" %} > > ``` > {"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 ... > ``` > > {% endcode %} > > Wygląda na to, że zaktualizowane ustawienia w `variables.env` nie są uwzględniane. Kompilacja nadal próbuje uruchomić `texlive/texlive:latest-full` obraz, a nie nowy obraz. > > Próbowałem zrestartować, usunąć kontenery i uruchomić ponownie, ale problem nadal występuje. > > Jakieś rozwiązania? Z powodu pewnych ograniczeń technicznych, jeśli skonfigurujesz tylko jeden obraz Docker TeXLive, taki jak `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 pewnym czasie działania twojej instancji Overleaf możesz chcieć zmodyfikować obraz TeXLive na `texlive-fullB:latest`. Wtedy zauważysz, że twoi użytkownicy nie mogą kompilować wszystkich projektów. ``` ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full ``` Dzieje się tak, ponieważ nazwa obrazu TeXLive-Full (dla kompilacji w piaskownicy) w każdym projekcie jest przechowywana w bazie danych. *Tylko gdy użytkownik przełączy wersję TeXLive swojego projektu, na przykład z 2024 na 2025, nazwa obrazu zostanie zmieniona w bazie danych*. Gdy CLSI kompiluje projekt, używa nazwy obrazu kontenera znalezionej w bazie danych do bezpośredniej kompilacji projektu. Jeśli udostępnisz tylko jeden obraz Docker, użytkownicy nie będą mogli zmodyfikować obrazu używanego do kompilacji projektu. W takim przypadku musisz napisać skrypt, aby **ręcznie zmodyfikować** obraz TeXLive dla wszystkich projektów użytkowników w mongoDB. ### Debugowanie Uruchom następujące polecenie, aby sprawdzić logi clsi z toolkitu: {% code overflow="wrap" %} ```bash bin/logs clsi ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/on-premises/pl/konfiguracja/overleaf-toolkit/kompilacjami-w-piaskownicy.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.