> ## 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. # 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](/fi/on-premises/configuration/overleaf-toolkit/templates#transferring-templates-from-overleaf.com "mention"). 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`: ```dotenv title="config/overleaf.rc" theme={null} 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`). ```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" #... #... ``` ### 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. 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öä. ```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 ``` 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öä. ```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 ``` On erittäin suositeltavaa määrittää **vähintään 2 texlive-full-imagea**. Yksityiskohtainen syy on kerrottu kohdassa [#known-issues](/fi/on-premises/configuration/overleaf-toolkit/sandboxed-compiles#known-issues "mention") ### 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ää: ```dotenv title="config/variables.env" wrap theme={null} 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: ```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 } ``` ### 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](/fi/on-premises/maintenance/updating-tex-live-full-images-automatically "mention"). ### 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`: > > ```dotenv theme={null} > 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: > > ```dotenv theme={null} > TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15 > ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15 > ``` > > Lokeissa näen seuraavaa: > > ```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 ... > ``` > > 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` ```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 ``` 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. ```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 ``` 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: ```bash wrap theme={null} 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](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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.