Hiekkalaatikkokäännökset

Ayakaleaf Prossa on mahdollisuus ajaa käännökset suojatussa hiekkalaatikkoympäristössä yritystason tietoturvan takaamiseksi. Tämä toteutetaan ajamalla jokainen projekti omassa suojatussa Docker-ympäristössään.

​

Parannettu tietoturva

Hiekkalaatikkokäännökset (Sandboxed Compiles) ovat suositeltu lähestymistapa Ayakaleaf Prossa, koska monet LaTeX-dokumentit vaativat tai mahdollistavat mielivaltaisten komentotulkkikomentojen suorittamisen osana PDF-käännösprosessia. Kun käytät hiekkalaatikkokäännöksiä, jokainen käännös ajetaan erillisessä Docker-kontissa rajoitetuin oikeuksin, joita ei jaeta muiden käyttäjien tai projektien kanssa, eikä kontilla ole pääsyä ulkoisiin resursseihin, kuten isäntäkoneen verkkoon.

Jos yrität ajaa Ayakaleaf Prota ilman hiekkalaatikkokäännöksiä, käännös ajetaan muiden samanaikaisten käännösten rinnalla pää-Docker-kontin sisällä, ja käyttäjillä on täydet luku- ja kirjoitusoikeudet sharelatex-kontin resursseihin (tiedostojärjestelmä, verkko ja ympäristömuuttujat) LaTeX-käännöksiä ajettaessa.

​

Helpompi pakettien hallinta

Pakettien manuaalisen asentamisen välttämiseksi suosittelemme hiekkalaatikkokäännösten käyttöönottoa. Tämä on Server Prossa määritettävä asetus, joka antaa käyttäjillesi pääsyn samaan TeX Live -ympäristöön kuin overleaf.comissa, mutta omassa paikallisessa asennuksessasi. Hiekkalaatikkokäännösten käyttämät TeX Live -imaget sisältävät suosituimmat paketit ja fontit, jotka on testattu galleriamme mallipohjia vasten, mikä varmistaa parhaan mahdollisen yhteensopivuuden paikallisten projektien kanssa.

Kun hiekkalaatikkokäännökset ovat käytössä, voit määrittää, mistä TeX Live -versioista käyttäjät voivat valita projektissaan, sekä asettaa uusille projekteille oletusarvoisen TeX Live -imagen version.

Jos yrität ajaa Ayakaleaf Prota ilman hiekkalaatikkokäännöksiä, instanssisi käyttää käännöksiin oletuksena TeX Liven perusskeemaversiota. Tämä perusversio on kevyt ja sisältää vain hyvin rajallisen osajoukon LaTeX-paketeista, mikä todennäköisesti aiheuttaa käyttäjillesi puuttuvien pakettien virheitä, erityisesti jos he yrittävät käyttää valmiita mallipohjia.

Koska Ayakaleaf Pro on suunniteltu toimimaan ilman verkkoyhteyttä, overleaf.comin gallerian mallipohjia ei voi integroida automaattisesti paikalliseen asennukseesi; se on kuitenkin mahdollista tehdä manuaalisesti mallipohja kerrallaan. Lisätietoja tämän toiminnasta on oppaassamme mallipohjien siirtämisestä overleaf.comista: #transferring-templates-from-overleaf.com.

Hiekkalaatikkokäännökset edellyttävät, että sharelatex-kontilla on pääsy isäntäkoneen Docker-sokettiin (bind-liitoksen kautta), jotta se voi hallita näitä rinnakkaisia käännöskontteja.

​

Miten se toimii

Kun hiekkalaatikkokäännökset ovat käytössä, Docker-soketti liitetään isäntäkoneelta sharelatex-konttiin, jotta kontin käännöspalvelu voi luoda uusia Docker-kontteja isäntäkoneelle. Tämän jälkeen jokaisella kääntäjän ajokerralla kussakin projektissa LaTeX-käännöspalvelu (CLSI) tekee seuraavat toimenpiteet:

• Kirjoittaa projektin tiedostot sijaintiin OVERLEAF_DATA_PATH-polun sisällä.
• Käyttää liitettyä Docker-sokettia luodakseen käännösajoa varten uuden texlive-kontin.
• Antaa texlive-kontin lukea projektin datan OVERLEAF_DATA_PATH-polun alla olevasta sijainnista.
• Kääntää projektin texlive-kontin sisällä.

​

Hiekkalaatikkokäännösten käyttöönotto

​

Toolkitin käyttäjille

Ota hiekkalaatikkokäännökset (tunnetaan myös nimellä Sibling containers) käyttöön asettamalla seuraavat konfiguraatioasetukset tiedostoon overleaf-toolkit/config/overleaf.rc:

config/overleaf.rc

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

Docker Composen käyttäjille

Overleaf CE/Server Pro -versiosta 5.0.3 alkaen ympäristömuuttujat on nimetty uudelleen muodosta SHARELATEX_* muotoon OVERLEAF_*.

Jos käytät versiota 4.x (tai vanhempaa), varmista, että muuttujilla on vastaava etuliite (esim. SHARELATEX_MONGO_URL eikä 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"
            #...
        #...

​

TeX Live -imagen määrittäminen

Manner-Kiinan käyttäjät voivat korvata ghcr.io:n osoitteella ghcr.nju.edu.cn latauksen nopeuttamiseksi. ÄLÄ kuitenkaan käytä ghcr.nju.edu.cn-osoitetta suoraan Toolkitin ympäristöasetuksissa. Sinun tulee pitää ghcr.io ainoana vaihtoehtona.

Ayakaleaf Pro käyttää kolmea ympäristömuuttujaa määrittääkseen, mitä TeX Live -imageja hiekkalaatikkokäännöksissä käytetään:

• TEX_LIVE_DOCKER_IMAGE (pakollinen), Oletusarvoinen TeX Live -image, jota käytetään uusien projektien kääntämiseen. Tämän imagen on sisällyttävä muuttujaan ALL_TEX_LIVE_DOCKER_IMAGES.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (pakollinen), Pilkuin eroteltu luettelo imagejen helppolukuisista nimistä, joita käytetään käyttöliittymän valinnoissa.
• ALL_TEX_LIVE_DOCKER_IMAGES (pakollinen), Pilkuin eroteltu luettelo käytettävistä TeX Live -imageista. Jos käyttöönotossa käytetään Overleaf Toolkitia, nämä imaget ladataan tai päivitetään. Voit ohittaa latauksen asettamalla SIBLING_CONTAINERS_PULL=false tiedostoon config/overleaf.rc.

Kun käynnistät Ayakaleaf Pro -instanssin komennolla bin/up, Toolkit hakee automaattisesti kaikki muuttujassa ALL_TEX_LIVE_DOCKER_IMAGES luetellut imaget.

Tässä esimerkissä uusien projektien oletuksena on TeX Live 2026, ja vanhoissa projekteissa käytetään edelleen versiota 2025.

Minimiasennus

Seuraava konfiguraatio asentaa kaikki täydet TeX Live Docker -imaget vuosilta 2025–2026. Suosittelemme, että käytettävissä on vähintään 64 Gt tallennustilaa ennen tämän konfiguraation käyttöä.

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

Täysi asennus

Seuraava konfiguraatio asentaa kaikki täydet TeX Live Docker -imaget vuosilta 2020–2026. Suosittelemme, että käytettävissä on vähintään 150 Gt tallennustilaa ennen tämän konfiguraation käyttöä.

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

On erittäin suositeltavaa määrittää vähintään 2 texlive-full-imagea. Yksityiskohtainen syy on kerrottu kohdassa #known-issues

​

Saatavilla olevat TeX Live -imaget

Nämä ovat Overleafia varten erityisesti optimoituja TeX Live -imageja, jotka voidaan lisätä myös muuttujiin TEX_LIVE_DOCKER_IMAGE ja ALL_TEX_LIVE_DOCKER_IMAGES:

• ghcr.io/ayaka-notes/texlive-full:2026.1 (myös tagi 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

Imagejen tagien muodolle on tiukka skeema, jota on noudatettava (käytetään säännöllistä lauseketta ^[0-9]+.[0-9]+, jossa ensimmäinen numero määrittää TeX Liven vuoden ja toinen korjausversion).

​

Voinko käyttää muuta image-rekisteriä

Jotkut saattavat miettiä, voiko ghcr.io:n korvata toisella peilisivustolla tai vaihtaa texliven toiseen Docker Hubin imageen?

Ei, emme suosittele sitä, koska konfigurointi on melko monimutkaista. Jos lataat peilisivustolta, voit nimetä imagesi uudelleen muotoon ghcr.io/ayaka-notes/texlive-full.

Jos kuitenkin todella haluat käyttää omaa image-rekisteriäsi, lisää:

config/variables.env

IMAGE_ROOT=hub.your.com/your-repo

Sen jälkeen sinun on varmistettava, että kaikki texlive-imaget ovat repositoriossa your-repo, esimerkiksi

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

Lisätietoja saat lukemalla alla olevan lähdekoodin, josta näet, miten ympäristömuuttujasi jäsennetään:

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
}

​

TeX Live -imagen automaattinen synkronointi

Jotta sinun ei tarvitsisi joka kerta päivittää instanssiasi manuaalisesti komennolla bin/up, voit automatisoida TeX Live -imagen päivitykset. Katso updating-tex-live-full-images-automatically.md.

​

Tunnetut ongelmat

Tämä on todellinen tapaus Overleaf-yhteisöstä:

Käytän versiota 6.0.1-ext-v3.3, ja minulla on nämä asetukset tiedostossa variables.env:

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

Tämä toimii hyvin imagella texlive/texlive:latest-full. Hain kuitenkin toisen texlive-imagen danteev/texlive:2025-10-15 ja vaihdoin molempiin muuttujiin uuden imagen nimen, mutta se ei toimi:

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

Lokeissa näen seuraavaa:

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

Vaikuttaa siltä, että tiedoston variables.env päivitetyt asetukset eivät tule voimaan. Käännös yrittää edelleen ajaa imagea texlive/texlive:latest-full eikä uutta imagea.

Kokeilin uudelleenkäynnistystä sekä konttien poistamista ja uudelleenajoa, mutta ongelma on edelleen sama.

Onko ratkaisuja?

Teknisten rajoitusten vuoksi, jos määrität vain yhden Docker TeXLive -imagen, kuten 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

ja haluat jonkin aikaa Overleaf-instanssin ajamisen jälkeen vaihtaa TeXLive-imagen imageen texlive-fullB:latest, huomaat, etteivät käyttäjäsi pysty kääntämään yhtään projektia.

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

Tämä johtuu siitä, että kunkin projektin TeXLive-Full-imagen nimi (hiekkalaatikkokäännöstä varten) tallennetaan pysyvästi tietokantaan. Imagen nimi muuttuu tietokannassa vain, kun käyttäjä vaihtaa projektinsa TeXLive-versiota, esimerkiksi versiosta 2024 versioon 2025.

Kun CLSI kääntää projektin, se käyttää tietokannasta löytyvää konttiimagen nimeä projektin kääntämiseen suoraan.

Jos tarjoat vain yhden Docker-imagen, käyttäjät eivät voi muuttaa projektin kääntämiseen käytettävää imagea. Tällöin sinun on kirjoitettava skripti, joka muuttaa manuaalisesti kaikkien käyttäjäprojektien TeXLive-imagen MongoDB:ssä.

​

Virheenjäljitys ja raportointi

Tarkista CLSI:n loki Toolkitin kautta suorittamalla seuraava komento:

bin/logs clsi

Jos kohtaat ongelmia kääntäessäsi TeX Live -imageilla, lähetä issue täällä:

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

Ongelman toistamiseksi ja selvittämiseksi sinua saatetaan pyytää lataamaan projektisi Overleafiin. Haemme sen jälkeen projektin ja ajamme käännöstestit GitHub Actionin avulla.