> ## 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 oferuje możliwość uruchamiania kompilacji w zabezpieczonym środowisku piaskownicy (sandbox) na potrzeby bezpieczeństwa korporacyjnego. Odbywa się to poprzez uruchamianie każdego projektu w osobnym, zabezpieczonym środowisku Docker. ### Większe bezpieczeństwo Sandboxed Compiles to zalecane podejście w przypadku Ayakaleaf Pro, ponieważ wiele dokumentów LaTeX wymaga możliwości (lub ją posiada) wykonywania dowolnych poleceń powłoki w ramach procesu kompilacji PDF. Jeśli korzystasz z Sandboxed Compiles, każda kompilacja jest uruchamiana w osobnym kontenerze Docker z ograniczonymi uprawnieniami, który nie jest współdzielony z żadnym innym użytkownikiem ani projektem i nie ma dostępu do zasobów zewnętrznych, takich jak sieć hosta. Jeśli spróbujesz uruchomić Ayakaleaf Pro **bez** Sandboxed Compiles, kompilacja będzie działać równolegle z innymi kompilacjami wewnątrz głównego kontenera Docker, a użytkownicy podczas kompilacji LaTeX będą mieli pełny dostęp do odczytu i zapisu zasobów kontenera `sharelatex` (systemu plików, sieci i zmiennych środowiskowych). ### Ł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 Twojej własnej instalacji lokalnej. Obrazy TeX Live używane przez Sandboxed Compiles zawierają najpopularniejsze pakiety i czcionki przetestowane z szablonami z naszej galerii, co zapewnia maksymalną zgodność z projektami w instalacjach lokalnych. Włączenie Sandboxed Compiles pozwala skonfigurować, spośród których wersji TeX Live użytkownicy mogą wybierać w swoich projektach, a także ustawić domyślną wersję obrazu TeX Live dla nowych projektów. Jeśli spróbujesz uruchomić Ayakaleaf Pro bez Sandboxed Compiles, instancja domyślnie użyje do kompilacji wersji TeX Live z podstawowym schematem (basic scheme). Ta podstawowa wersja jest lekka i zawiera jedynie bardzo ograniczony podzbiór pakietów LaTeX, co najprawdopodobniej spowoduje u użytkowników błędy brakujących pakietów, zwłaszcza jeśli spróbują użyć gotowych szablonów. Ponieważ Ayakaleaf Pro został zaprojektowany do pracy w trybie offline, nie ma zautomatyzowanego sposobu integracji szablonów z galerii overleaf.com z instalacją lokalną; można to jednak zrobić ręcznie dla każdego szablonu z osobna. Więcej informacji o tym, jak to działa, znajdziesz w naszym przewodniku dotyczącym przenoszenia szablonów z overleaf.com: [#transferring-templates-from-overleaf.com](/pl/on-premises/configuration/overleaf-toolkit/templates#transferring-templates-from-overleaf.com "mention"). Sandboxed Compiles wymaga, aby kontener `sharelatex` miał dostęp do gniazda Docker na maszynie hosta (poprzez bind mount), dzięki czemu może zarządzać tymi równoległymi (sibling) kontenerami kompilacji. ## Jak to działa Gdy Sandboxed Compiles są włączone, gniazdo Docker zostaje zamontowane z maszyny hosta do kontenera `sharelatex`, dzięki czemu usługa kompilatora w kontenerze może tworzyć nowe kontenery Docker na hoście. Następnie przy każdym uruchomieniu kompilatora w każdym projekcie usługa kompilatora LaTeX (CLSI) wykonuje następujące czynności: * Zapisuje pliki projektu w lokalizacji wewnątrz `OVERLEAF_DATA_PATH`. * Używa zamontowanego gniazda Docker do utworzenia nowego kontenera `texlive` na potrzeby danej kompilacji. * Kontener `texlive` odczytuje dane projektu z lokalizacji w `OVERLEAF_DATA_PATH`. * Kompiluje projekt wewnątrz kontenera `texlive`. ### Włączanie Sandboxed Compiles #### Dla użytkowników Toolkit Aby włączyć Sandboxed Compiles (znane również jako kontenery Sibling), ustaw następujące opcje konfiguracyjne w pliku `overleaf-toolkit/config/overleaf.rc`: ```dotenv title="config/overleaf.rc" theme={null} SERVER_PRO=true SIBLING_CONTAINERS_ENABLED=true ``` #### Dla użytkowników Docker Compose Począwszy od Overleaf CE/Server Pro `5.0.3` nazwy zmiennych środowiskowych zostały zmienione z `SHARELATEX_*` na `OVERLEAF_*`. Jeśli używasz wersji `4.x` (lub wcześniejszej), upewnij się, że zmienne mają odpowiedni prefiks (np. `SHARELATEX_MONGO_URL` zamiast `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" #... #... ``` ### Konfiguracja obrazu TeX Live Użytkownicy z Chin kontynentalnych mogą zastąpić `ghcr.io` adresem `ghcr.nju.edu.cn`, aby przyspieszyć pobieranie. **NIE** używaj jednak `ghcr.nju.edu.cn` bezpośrednio w ustawieniach środowiska Toolkit. Jedyną wartością powinno pozostać `ghcr.io`. Ayakaleaf Pro używa trzech zmiennych środowiskowych do określenia, których obrazów TeX Live używać w Sandboxed Compiles: * `TEX_LIVE_DOCKER_IMAGE` (wymagana), domyślny obraz TeX Live używany do kompilowania nowych projektów. Ten obraz musi znajdować się w `ALL_TEX_LIVE_DOCKER_IMAGES`. * `ALL_TEX_LIVE_DOCKER_IMAGE_NAMES` (wymagana), lista przyjaznych nazw obrazów rozdzielonych przecinkami, używana w opcjach frontendu. * `ALL_TEX_LIVE_DOCKER_IMAGES` (wymagana), lista obrazów TeX Live do użycia, rozdzielonych 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 Ayakaleaf Pro za pomocą polecenia `bin/up` Toolkit automatycznie pobierze wszystkie obrazy wymienione w `ALL_TEX_LIVE_DOCKER_IMAGES`. Oto przykład, w którym domyślnie używamy TeX Live 2026 dla nowych projektów, a wersję 2025 zachowujemy dla starszych projektów. Poniższa konfiguracja instaluje wszystkie pełne obrazy Docker TeX Live z lat 2025–2026. Przed użyciem tej konfiguracji zalecamy zapewnienie co najmniej **64 GB** wolnego miejsca. ```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 ``` Poniższa konfiguracja instaluje wszystkie pełne obrazy Docker TeX Live z lat 2020–2026. Przed użyciem tej konfiguracji zalecamy zapewnienie co najmniej **150 GB** wolnego miejsca. ```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 ``` Zdecydowanie zalecamy ustawienie **co najmniej 2 obrazów texlive-full**. Szczegółowe uzasadnienie znajdziesz w [#known-issues](/pl/on-premises/configuration/overleaf-toolkit/sandboxed-compiles#known-issues "mention") ### Dostępne obrazy TeX Live Oto seria obrazów TeX Live specjalnie zoptymalizowanych pod kątem 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:2026.1` (również 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` Obowiązuje ścisły schemat określający, jak obrazy **muszą** być tagowane (stosowane jest wyrażenie regularne `^[0-9]+.[0-9]+`, w którym pierwsza liczba określa rok TeX Live, a druga wersję poprawki). ### Czy mogę używać innego rejestru obrazów? > Niektórzy mogą się zastanawiać, czy można zastąpić `ghcr.io` innym serwerem lustrzanym albo zamienić obraz texlive na inny obraz z Docker Hub? Nie, nie zalecamy tego, ponieważ konfiguracja jest stosunkowo skomplikowana. Jeśli pobierasz obrazy z serwera lustrzanego, możesz zmienić nazwę obrazu na `ghcr.io/ayaka-notes/texlive-full`. Jeśli jednak naprawdę chcesz używać własnego rejestru obrazów, dodaj: ```dotenv title="config/variables.env" wrap theme={null} IMAGE_ROOT=hub.your.com/your-repo ``` Następnie upewnij się, że wszystkie obrazy texlive znajdują się w `your-repo`, na przykład * `hub.your.com/your-repo/texlive-full:2025.1` * `hub.your.com/your-repo/texlive-full:2024.1` Aby uzyskać szczegółowe informacje, zapoznaj się z poniższym kodem źródłowym, aby zrozumieć, w jaki sposób przetwarzamy Twoje zmienne środowiskowe: ```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 } ``` ### Automatyczna synchronizacja obrazów TeX Live Aby uniknąć ręcznego aktualizowania instancji za pomocą `bin/up` za każdym razem, możesz zautomatyzować aktualizacje obrazu TeX Live. Zobacz [updating-tex-live-full-images-automatically.md](/pl/on-premises/maintenance/updating-tex-live-full-images-automatically "mention"). ### Znane problemy Oto prawdziwy przypadek ze społeczności Overleaf: > Używam `6.0.1-ext-v3.3` i mam w `variables.env` następujące ustawienia: > > ```dotenv theme={null} > TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full > ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full > ``` > > Działa to poprawnie z `texlive/texlive:latest-full`. Jednak pobrałem inny obraz texlive, `danteev/texlive:2025-10-15`, i zmieniłem obie te zmienne na nazwę nowego obrazu, ale to nie działa: > > ```dotenv theme={null} > TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15 > ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15 > ``` > > W logach widzę następujący komunikat: > > ```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 ... > ``` > > Wygląda na to, że zaktualizowane ustawienia w `variables.env` nie są uwzględniane. Kompilacja nadal próbuje uruchomić obraz `texlive/texlive:latest-full`, a nie nowy obraz. > > Próbowałem ponownie uruchomić system, usunąć kontenery i uruchomić je od nowa, ale problem nadal występuje. > > Czy są jakieś rozwiązania? Ze względu na pewne ograniczenia techniczne, jeśli skonfigurujesz tylko jeden obraz Docker TeXLive, na przykład `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 pewnym czasie działania instancji Overleaf zechcesz zmienić obraz TeXLive na `texlive-fullB:latest`, okaże się, że użytkownicy nie mogą skompilować żadnego projektu. ```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 ``` Dzieje się tak, ponieważ nazwa obrazu TeXLive-Full (dla kompilacji w piaskownicy) każdego projektu jest zapisywana w bazie danych. *Nazwa obrazu w bazie danych zmienia się tylko wtedy, gdy użytkownik przełączy wersję TeXLive swojego projektu, na przykład z 2024 na 2025*. Podczas kompilowania projektu CLSI używa nazwy obrazu kontenera znalezionej w bazie danych, aby bezpośrednio skompilować projekt. Jeśli udostępnisz tylko jeden obraz Docker, użytkownicy nie będą mogli zmienić obrazu używanego do kompilacji projektu. W takim przypadku musisz napisać skrypt, który **ręcznie zmodyfikuje** obraz TeXLive dla wszystkich projektów użytkowników w MongoDB. ### Debugowanie i zgłaszanie problemów Uruchom poniższe polecenie, aby sprawdzić logi clsi za pomocą Toolkit: ```bash wrap theme={null} bin/logs clsi ``` Jeśli napotkasz problemy z kompilacją przy użyciu obrazów TeX Live, zgłoś problem tutaj: [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) Aby pomóc nam odtworzyć i zdiagnozować problem, możemy poprosić Cię o przesłanie projektu do Overleaf. Następnie pobierzemy projekt i przeprowadzimy testy kompilacji za pomocą GitHub Action. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.