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.

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:

config/overleaf.rc

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

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.

Instalacja minimalna

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.

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

Instalacja pełna

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.

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

Zdecydowanie zalecamy ustawienie co najmniej 2 obrazów texlive-full. Szczegółowe uzasadnienie znajdziesz w #known-issues

​

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:

config/variables.env

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:

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
}

​

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.

​

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:

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:

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:

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

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.

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:

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

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.