Siirry pääsisältöön

Esivaatimukset

Overleaf on tyypillinen mikropalveluarkkitehtuuriin perustuva avoimen lähdekoodin projekti, jonka kaikki palvelut ajetaan Dockerissa. Overleaf-kehitysympäristön määrittämiseen tarvitset tehokkaan palvelimen; suosittelemme vähintään 8 ydintä ja 16 Gt RAM-muistia, koska sinun on ajettava yli 20 konttia samanaikaisesti.
Koska palvelimet, joissa on vähintään 8 suoritinydintä, ovat yleensä kalliita, suosittelemme vahvasti kehittämään omalla paikallisella tietokoneellasi.
Oletamme lisäksi, että kehittäjänä tunnet jo Dockerin asennuksen. Suosittelemme vahvasti käyttämään kehitykseen tuoretta ja vakaata Ubuntu LTS -versiota (esim. Ubuntu 24.04 vuosina 2025–2026) ja uusinta Dockeria, sillä tämä vähentää odottamattomien virheiden todennäköisyyttä. Yhteenvetona tarvitset:
  • Tehokkaan palvelimen tai työaseman kehitykseen
  • Tuoreen ja vakaan Ubuntu LTS -version (esim. Ubuntu 24.04)
  • Docker- ja Git-ympäristön

Määritysopas

Tässä näytämme Ayakaleaf Pron avulla, miten Overleafin kehitysympäristö otetaan käyttöön. Kaikki alla olevat komennot suoritetaan hakemistossa develop, ellei toisin mainita.
1

Hae lähdekoodi

Kloonataan ensin repositorio:
bash
2

Synkronoi yarn.lock

Repositorio käyttää Yarn 4:ää (packageManager juuren package.json-tiedostossa), ja sen yarn.lock voi olla epäsynkronissa package.json-tiedostojen kanssa. Synkronoi se ensimmäisen kloonauksen jälkeen ja aina, kun jokin package.json muuttuu:
bash
bin/sync suorittaa yarn install --mode=update-lockfile -komennon node:24.18.1-kontissa, joten et tarvitse Node.js:ää isäntäkoneelle. Älä commitoi muuttunutta yarn.lock-tiedostoa.
3

Rakenna kehitysimage

Rakenna palvelut:
bash
Jos Dockerilta loppuu RAM-muisti palveluiden rinnakkaisen rakentamisen aikana, luo tähän hakemistoon .env-tiedosto, joka sisältää rivin COMPOSE_PARALLEL_LIMIT=1.
4

Käännösten käyttöönotto

Ayakaleaf Pron moduulit säilyttävät käännöksensä hakemistossa services/web/locales/locales_patches/, jota commitoidut kielitiedostot eivät sisällä. Ota ne käyttöön kerran ennen ensimmäistä käynnistystä, muuten näiden moduulien sivuilla näkyy tekstin sijaan avaimia, kuten about_to_permanently_delete_accounts:
bash
Se tarvitsee isäntäkoneelle jq:n. Suorita se uudelleen, kun olet lisännyt käännöksen tai vaihtanut haaraa, katso i18n-käännösten päivittäminen.
5

Käynnistä kaikki mikropalvelut

Käynnistä sitten palvelut:
bash
Kun palvelut ovat käynnissä, avaa http://localhost/launchpad ja luo ensimmäinen ylläpitäjätili. Lisää portti, jos olet muuttanut OVERLEAF_PORT-arvoa (katso alla).
LDAP on oletuksena käytössä (LDAP_ENABLED=true tiedostossa dev.rc). Launchpad näyttää silloin LDAP-ylläpitäjän lomakkeen: se kysyy vain sähköpostiosoitetta, ja ylläpitäjä kirjautuu sen jälkeen LDAP:n kautta, esimerkiksi tunnuksilla professor / professor (professor@planetexpress.com). Testikäyttäjät on lueteltu tiedostossa develop/authentication/README.md. Aseta LDAP_ENABLED=false ja SAML_ENABLED=false, jos haluat sen sijaan luoda paikallisen ylläpitäjän salasanalla.
develop/dev.env asettaa jo ADMIN_PRIVILEGE_AVAILABLE=true, joten ylläpitäjät voivat avata hallintapaneelin ilman lisäasetuksia.

Määritykset (dev.rc)

develop/dev.rc tiedoston dev.env vieressä sisältää kehitysympäristön kytkimet, kuten overleaf.rc Overleaf Toolkitissa. Muuta arvoa ja suorita bin/dev uudelleen ottaaksesi sen käyttöön; pois päältä kytketty ominaisuus pysäyttää myös konttinsa. Jokainen ominaisuus pitää docker-compose.yml-tiedostonsa ja muut tiedostonsa omassa kansiossaan: authentication/ldap, authentication/saml, mail, s3, hoppscotch ja grafana. Ominaisuus, joka tarvitsee web-asetuksen ilman ympäristömuuttujaa, liittää tiedoston hakemistoon /etc/overleaf/settings.d/, ja develop/settings.dev-env.cjs yhdistää ne kaikki. Kaikki bin/*-skriptit kulkevat bin/docker-compose-skriptin kautta, joka lisää päällä olevien ominaisuuksien tiedostot. Käytä bin/docker-compose-komentoa docker compose -komennon sijaan, kun tarvitset itse compose-komentoa.
Paikalliset volyymit ja RustFS ovat erillisiä tallennustiloja: projektilla, joka on luotu asetuksella S3_ENABLED=true, ei ole historiaa eikä binääritiedostoja vaihdon jälkeen arvoon false, ja päinvastoin. Kopioidaksesi RustFS:ään sellaisen ympäristön tiedostot, joka oli käytössä ennen kuin S3_ENABLED oli olemassa, noudata ohjetta ”Moving existing data into RustFS” tiedostossa develop/README.md.

Portit

Sivusto, RustFS-konsoli ja Hoppscotch kuuntelevat isäntäkoneen osoitetta 127.0.0.1; etäkoneella ohjaa ensin niiden portit eteenpäin, esimerkiksi ssh -L 9001:localhost:9001 <host>. Sivusto käyttää dev.rc:n OVERLEAF_PORT-arvoa, joten lisää portti alla oleviin osoitteisiin, jos olet muuttanut sitä. Sivusto tarjoaa Mailpitin, Grafanan, Mongo Expressin ja RedisInsightin omissa poluissaan webpack-dev-serverin kautta, joten ne eivät tarvitse omia portteja. Kun olet kirjautunut, sivuston navigointipalkin Dev tools -valikko linkittää niihin; sivu, jonka ominaisuus on kytketty pois dev.rc:ssä, jätetään pois. Kehitystyökalujen käyttöönotto kertoo, mitä kukin niistä tekee. S3-API (portti 9000) ja SMTP (portti 1025) ovat tavoitettavissa vain Docker-verkon sisällä. Mongo (27017), Redis (6379), Mongo Express (8081), RedisInsight (5540) ja git-bridge (8000) julkaistaan vain isäntäkoneen osoitteessa 127.0.0.1.

TeX Live

Hiekkalaatikkokäännökset ovat oletuksena käytössä: develop/dev.env asettaa SANDBOXED_COMPILES=true sekä imaget ghcr.io/ayaka-notes/texlive-full:2026.1 ja ghcr.io/ayaka-notes/texlive-full:2025.1. clsi ei hae imageja itse, joten hae ne kerran:
Katso lisätiedot sivulta Sandbox Compiles -toiminnon määrittäminen.
Projektilla, joka luotiin, kun SANDBOXED_COMPILES oli pois päältä, ei ole TeX Live -imagea. Se kääntyy edelleen oletusimagella, mutta siirtyminen koodin ja PDF:n välillä epäonnistuu virheellä ”That didn’t work. Recompile and try again.” Anna tällaisille projekteille kerran TEX_LIVE_DOCKER_IMAGE-image; ilman --commit-valitsinta skripti vain näyttää, mitä se muuttaisi:
dev.env ottaa myös Pandoc-muunnokset käyttöön asetuksella PANDOC_IMAGE=overleaf-pandoc:local. Rakenna tämä image kerran repositorion juuresta:
Kääntääksesi macOS-isäntäkoneella sinun on ehkä ohitettava Docker-socketin polku luomalla hakemistoon develop .env-tiedosto, joka sisältää DOCKER_SOCKET_PATH=/var/run/docker.sock.raw

Kehitys

Jotta sinun ei tarvitse ajaa bin/build && bin/up jokaisen koodimuutoksen jälkeen, voit ajaa Overleaf Community Editionia kehitystilassa, jolloin palvelut päivittyvät automaattisesti koodimuutosten myötä. Käytä tähän mukana tulevaa bin/dev-skriptiä:
Tämä käynnistää kaikki palvelut komennolla node --watch, joka valvoo koodia automaattisesti ja käynnistää palvelut tarvittaessa uudelleen. Suorita se uudelleen, kun olet muuttanut dev.rc:tä. Suorituskyvyn parantamiseksi voit käynnistää kehitystilassa vain osan palveluista antamalla bin/dev-skriptille välilyönnein erotellun luettelon:
Kun web-palvelu käynnistetään kehitystilassa, vain web-palvelu päivittyy taustajärjestelmän koodin muuttuessa. Jotta myös käyttöliittymäkoodi päivittyisi automaattisesti, käynnistä myös webpack-palvelu kehitystilassa.
Jos palveluita ei nimetä, kaikki palvelut käynnistyvät kehitystilassa. Kun olet lisännyt käännöksen tai vaihtanut haaraa, suorita bin/i18n, katso i18n-käännösten päivittäminen.

Virheenjäljitys

Kehitystilassa useimmat palvelut tarjoavat virheenkorjausportin, johon voit liittää virheenkorjaimen, kuten Chromen Dev Toolsin tarkastimen tai IDE:hen integroidun virheenkorjaimen. Seuraava taulukko näyttää kunkin palvelun portin, joka on avattu isäntäkoneen osoitteeseen 127.0.0.1: Liittyäksesi palveluun Chromen etävirheenjäljityksellä siirry osoitteeseen chrome://inspect/ ja varmista, että Discover network targets on valittuna. Napsauta seuraavaksi Configure… ja lisää merkintä localhost:[service port] jokaiselle palvelulle, johon haluat liittää virheenjäljittimen. Merkinnän lisäämisen jälkeen palvelu näkyy Remote Target -kohteena, jota voit tarkastella ja jäljittää.

Lokit

Skripti bin/logs seuraa lokeja ja muotoilee ne bunyan-työkalulla. Se tarvitsee myös ggrep:n, joka on GNU grepin nimi, kun se asennetaan Homebrew’lla macOS:ään; Ubuntussa ei ole ggrep-komentoa.
Vaihtoehtoisesti voit ajaa suoraan:
Käytä bin/docker-compose-komentoa docker compose -komennon sijaan, jotta myös dev.rc:n ominaisuuksien palvelut (mailpit, rustfs, ldap, saml, hoppscotch ja grafana Prometheuksen, Lokin ja exporterien kanssa) löytyvät. Kun GRAFANA_ENABLED=true, jokaisen kontin lokit ovat myös Grafanassa, jossa niitä voi suodattaa palvelun, tason ja tekstin mukaan, katso Kehitystyökalujen käyttöönotto.

Muut työkalut

Kun olet tehnyt kaiken tämän, voit katsoa seuraavasta osiosta, miten lisäät Overleaf-kehitykseesi virheenjäljitystyökaluja.
Viimeksi muokattu 20. marraskuuta 2026