Hvernig ég gerði einfalda heimasíðu með Zola og Git

Inngangur

(Ef þú ert nú þegar Ul7r4 1337 H4xxx0r sem veit allt um netið þá viltu líklega fara beint í hasarinn)

Að vera með heimasíðu

Ég held að nú á dögum þyki frekar gamaldags að eiga sér heimasíðu. Enda til hvers að vera með slíkt þegar við höfum alla þessa félagsmiðla? Nú er hægt að setja starfsferilinn sinn á LinkedIn, ef maður vill blogga getur maður bara notað Medium eða þess vegna Facebook ef maður er ekki að skrifa neinar ritgerðir. Svo getur maður myndabloggað á Instagram, myndbandsbloggað á YouTube og sýnt list sína á ArtStation, Soundcloud o.s.frv..

Hinsvegar býður enginn þessara miðla upp á að setja allt þetta saman í einn pakka, með viðmóti og skipulagi eins og manni þykir best. Svo hefur maður á flestum þessara síðna mjög takmarkaða stjórn á því hvað annað birtist við hliðina á þvi sem maður setur þar inn. Svo ekki sé talað um njósnirnar og afskiptasemina sem sumir þessara miðla stunda, t.a.m. hvernig Facebook lætur ekki einu sinni alla þá sem læka síðu vita af innleggjum á henni nema maður borgi fyrir það og svo ritskoðun þeirra á vinstrisinnuðum hópum og innleggjum 1 2.

En kannski er ég líka frekar gamaldags að ýmsu leiti. Og svo er ekki eins og ég sé saklaus um að taka þátt í neinum af þessum miðlum. Og ég játa að mér þykir skemmtilegra að grúska í svona tæknilegu veseni heldur en að allt sé gert fyrir mig, og að það hafa í rauninni fæstir samsetninguna af tíma, orku og þekkingu til að standa í slíku.

Hvað er eiginlega Zola?

Émile Édouard Charles Antoine Zola var franskur rithöfundur og blaðamaður sem er einna frægastur fyrir að koma upp um Dreyfus málið. Seint árið 1894 var Alfred Dreyfus fangelsaður í frönsku Guiana fyrir að uppljóstra leyndarmálum franska hersins til þjóðverjanna. Hinsvegar voru engin sönnunargögn sem bentu frekar á Dreyfus en neinn annan, heldur lá hann undir grun vegna gyðingahaturs yfirmanna sinna. Það sem var þó hneykslanlegast af öllu var að eftir að raunverulegi sökudólgurinn var fundinn var hylmt yfir málinu, njósnarinn var látinn laus ganga og Dreyfus fékk ekki aflausn. Þökk sé Zola fékk alþjóð að vita af þessu hneyksli og Dreyfus var að lokum látinn laus.

Zola er líka kerfi sem gerir manni kleyft að vefa statíska vefi.

Hvað er eiginlega statískur vefur?

Til að útskýra almennilega hvað statískur vefur er, er best að byrja frá byrjuninni.

Þegar maður fer á einhverja slóð á vafranum (bláa e-ið með gula hringnum 🙃) sínum sendir tölvan manns (notandinn) skilaboð (sem kallast http beyðni) til tölvunnar sem lénið bendir á (þjónninn). (Hvernig það er komist að því hvert lénið bendir og hvernig skilaboðin komast þangað er svo önnur saga.) Þegar skilaboðin komast á leiðarenda fara þau í móttakara í þjóninum í gegnum nettengingu þjónsins. Ef allt er í orden þá er forrit í gangi á þjóninum (slíkt forrit er yfirleitt líka kallað þjónn) sem er að hlusta á móttakarann og fær skilaboðin, annars falla þau á dauf eyru og ekkert gerist. Ef allt er svo í orden með skilaboðin og forritið þá mun það jafnvel vita hvað það á að gera með skilaboðin.

Þá er vefur safn allra mögulegra svara sem slíkur þjónn getur gefið notendanum, sem tilheyra ákveðnu léni. Venjulega eru slík svör HTML skjal, CSS skrár og Javascript kóði sem mynda í sameiningu vefsíðu. Svörin geta líka verið hvaða skrá sem er, eins og pdf, csv og myndir.

Þessar skrár hlutu þó að koma einhvers staðar að, og þar liggur munurinn á statískum og dýnamískum vef. Þegar þjóninn er búinn að fá skilaboðin þá gæti hann náð í umbeðin skjöl sem eru nú þegar til á tölvunni. Hann gæti líka handlangað skilaboðinu áfram til forrits sem býr til viðeigandi skjöl „on the fly,“ svo að segja, og sendir til þjónsins sem sendir þau síðan til notandans. Þegar vefurinn samanstendur algjörlega af fyrri tegundinni af svörum kallast vefurinn statískur, en dýnamískur ef hann samanstendur af svörum af seinni gerðinni.

Nú er svo háttað að allir vefir innihalda einhvern statískan þátt, t.d. eru CSS skrár, Javascript kóði og myndir yfirleitt ekki búnar til „on the fly,“ heldur eru það yfirleitt bara HTML skrárnar. Jafnvel geta margar HTML skrárnar verið statískar ef vitað er að þær koma til með að vera óbreyttar á vefnum um ókomna tíð.

Nú er statískum vefjum greinilega miklar skorður settar. Það er t.d. engin leið til að setja neinskonar sjálfvirk athugasemdakerfi á þær, og það er engin leið til að breyta vefnum nema með því beinlínis að grúska í skrám á þjóninum þar sem vefurinn er hýstur.

Kostirnir felast þó í þessum skorðum. Eins og má giska útfrá lýsingunni á statískum vefjum miðað við dýnamíska þá eru þeir eins skilvirkir, þ.e. hraðvirkir, og vefir geta orðið. Og vegna þess að þeir samanstanda bara af stökum skrám þá eru þeir líka eins öruggir og vefir geta orðið. Vegna þess að það þarf enga forritun til að búa þá til er líka afskaplega einfalt að búa þá til og halda utan um þá.

Hinsvegar verður það manni fljótt ofvaxið og leiðingjarnt að halda utan um fleiri, fleiri HTML skjöl sem eiga öll marga hluti sameiginlega. Þar koma inn statískir vefarar (e. static site-builder). Ég veit ekki til þess að það sé til almennt viðtekið íslenskt nafn yfir þessi forrit svo ég ætla að veita sjálfum mér það bessaleyfi að skálda skapandi nafn.

Bíddu, halló, ætlaðirðu ekki að útskýra hvað Zola er eða ...???

Zola er nefnilega statískur vefari. Það eru jafnvel til margir slíkir vefarar og er Jekyll vinsælastur þeirra, Hugo á eftir honum og svo hugsanlega Pelican þar á eftir.

Hvers vegna nota ég þá ekki einhvern af þeim ef þeir eru svo miklu vinsælli og þar af leiðandi betri en Zola? Ein ástæða fyrir því er vegna þess að Zola er bara mjög fínn. Hann býður upp á flest það sem Jekyll og Hugo bjóða upp á en það sem þeir hafa sem mig langar helst til að Zola bjóði upp á er almennilegt kerfi fyrir fjöltyngda vefi. Önnur ástæða er að Zola er nokkuð lofandi, t.a.m. er slíkt kerfi í vinnslu. Að lokum er Zola einn hraðasti vefarinn sem fyrirfinnst þar sem hann er þýddur (e. compiled) og skrifaður í forritunarmálinu Rust af (að því er virðist) hæfum forriturum. Einn notandi sem skipti yfir frá Jekyll mældi stærðargráðu mun á hraða vefaranna. Tölurnar sem hann mældi gefa í skyn rúmlega fjörutíufalt hraðari vefun, en það kemur ekki fram hvort vefirnir hafi verið fullkomlega sambærilegir.

En hvað er eiginlega þetta Git drasl sem þú talaðir um í titlinum?

Hugsaðu þér að þú sért að skrifa bók (eða eins og tilfellin sem git var hannað fyrir, forrit) og ekki nóg með það heldur ertu að skrifa hana með mörgum samstarfsmönnum. Hvernig ætlarðu að deila því sem þú ert búinn að skrifa með samstarfsmönnum þínum, og sækja það sem samstarfsmenn þínir eru búnir að skrifa? Þið gætuð hugsanlega sent þetta allt ykkar á milli þvers og kruss í tölvupósti o.s.frv. og munað að merkja öll skjölin með viðeigandi hætti og setja það allt einhvernveginn saman í lokin án þess að yfirsjást eitthvað. Eða þið gætuð notað Git.

Git er öflugt tæki til að auðvelda samvinnu í hópum og til að halda utan um útgáfur af ýmsum skjölum. Það gerir manni kleift að hverfa aftur til eldri útgáfna af verkefninu, og auðveldar manni að sameina breytingar sem maður er búinn að gera á verkefninu við breytingar annarra. Það er svo mikið til í Git að það þyrfti helst heila bók um það, en við skulum halda áfram og ég geng að því vísu að þú sért búin/n/ð að setja upp Git á þinni tölvu.

Hasarinn

Að búa til statískan vef með Zola

Almennar leiðbeiningar á Zola er að finna á heimasíðu verkefnisins en hér ætla ég að fara í gegnum hvernig ég setti þessa síðu upp.

Það byrjar allt á því að opna terminal (ég nota Alacritty um þessar mundir). Þar skrifar maður (eftir að maður er búinn að setja upp Zola!):

zola init eitthvað-skemmtilegt-nafn

og ýtir á enter til að staðfesta. Þá mun Zola spyrja mann hvert fyrirhugað lén vefsins sé, hvort maður vilji virkja eitthvað sem kallast Sass þýðingu, hvort maður vilji litakóðun fyrir forritunarbúta og hvort maður vilji búa til leitarvísi. Ef þú ert með eitthvað lén sem þú ætlar að hýsa síðuna þína á slærðu það bara inn og svo er fínt að virkja Sass þýðinguna og allt hitt. Í versta falli liggur það bara ónotað.

Ef þú ferð síðan í eitthvað-skemmtilegt-nafn geturðu framkvæmt

zola serve

og þá ætti heldur ómerkileg síða að blasa við ef þú ferð á localhost:1111 í vafra. Hún er hinsvegar nógu hjálpleg til að segja þér hver næstu skref þín ættu að vera. Vegna þess að við erum afskaplega löt og betri vefhönnuðir en við eru þegar búnir að leggja inn vinnuna ætlum við einfaldlega að setja upp þema. Sjálfur hallast ég að Hyde, en hægt er að finna lista af þemum fyrir Zola á heimasíðu verkefnisins.

Nú ætlum við ekki að fylgja leiðbeiningunum á heimasíðunni nákvæmlega heldur ætlum við að gera möppuna sem við erum í að Git lind með því að framkvæma

git init .

Til að ná í þemað ætlum við síðan að framkvæma

git submodule add https://github.com/getzola/hyde.git

Loks til að nota þemað ætlum við að opna skrána config.toml með einhverjum ritli (um þessar mundir nota ég Neovim) og bæta við á undan [extra] kaflanum:

title = "Einhver góður titill" # ég set þetta beint fyrir neðan „base_url“)
description = "Einhver lýsing ef þú vilt"
... # fleiri stillingar, ég set þemað bara rétt fyrir ofan „[extra]“
theme = "hyde" # eða hvaða þema sem þú valdir að sjálfsögðu

Núna ættirðu að fá aðeins skrautlegri síðu þegar þú ferð á localhost:1111 (með zola serve ennþá í gangi auðvitað). Það er sameiginlegt flestum þemunum að maður getur búið til stiku með því að setja inn stillingu í [extra] kaflanum. Það lítur þá einhvernveginn svona út:

[extra]
hyde_links = [
	{url = "/einhver/slóð", name = "E-ð sem ég vil hafa í stikunni"},
]

Mismunandi þemu bjóða upp á mismunandi möguleika í þessum tenglum og fleiru.

Nú skulum við prófa að bæta við síðu á vefinn okkar. Farðu í content möppuna og byrjaðu að skrifa Markdown skrá, t.d. bloggfærsla.md. Nú geturðu skrifað af hjartans lyst, en efst í skránni verður bútur á þessu formi að koma fyrir:

+++
title = "Einhver titill"
date = "2019-08-10" # Einhver dagsetning, óþarfi í sumum þemum
# og hvaða aðrar upplýsingar sem eru viðeigandi (höfundur, lýsing o.s.frv.)
+++

Skráin mun þá í heildina lýta einhvernveginn svona út:

+++
title = "Einhver titill"
date = "42010-08-10" 
+++
## Tvo myllumerki merkja kafla, h2 tög í htmlinu {#kafli1}
### Þrjú myllumerki merkja undirkafla, h3 tög í htmlinu
#### Fjögur merkja undirundirkafla, h4 tög í htmlinu
##### Einföld lýsing
###### Hægt er að halda áfram alveg niður í 6 myllumerki, h6 tag í htmlinu
# Ég mæli samt með að nota ekki eitt myllumerki
Það er vegna þess að það verður að h1 tagi í htmlinu sem á að vera titill á
síðu eða hugsanlega grein og getur verið ruglandi fyrir fólk sem notar
skjálesanda að hafa þau þar sem þau eiga ekki við.
Hér er svo efni sem verður að efnisgrein
Ef textinn er bara í næstu línu heldur efnisgreinin áfram óbrotin

Hinsvegar ef það kemur línubil verður til önnur efnisgrein. Svo er hægt að vísa
í kafla, undirkafla o.s.frv. [bæði án afskipta](#einfold-lysing) og með því að
merkja kaflann [eins og að ofan](#kafli1). Til að vísa í aðra skrá útfrá
staðsetningu þessarar skrár er hægt að [nota @
ritháttinn](@/mappa/sem/er/yfir/þessari/möppu/skrá.pdf). Til að vísa í skrá
útfrá grunnléninu er hægt að [byrja tilvísunina á /](/flokkur). Svo er hægt að
vísa í [utanaðkomandi
slóð](https://með-því-að-byrja-tilvísunina-á-https-eða-slíku.is)

Svo er auðvitað hægt að *skáletra*, **feitletra** og ***skáfeitletra***.
Því miður er ekki hægt að ~útstrika~ með algengum rithætti en það er hægt að
gera það með því að setja <s>útstrikunartagið</s> beint inn. Einnig er hægt að
setja inn myndir á einfaldan hátt,
![lýsing](/mynd-sem-býr-í-static-möppunni.jpg), eða á flóknari en öflugri hátt
með „asset colocation“ og/eða „resize_image“ fallinu, sjá heimasíðu Zola fyrir
meiri uplýsingar.

Nú erum við búin að kynnast Zola temmilega, og búin að vefa vef með einni síðu að heimasíðunni frátaldri. Nú skulum við skoða hvernig við getum sett hann í loftið með Git.

Að gefa vefinn út með Git

Áður en við höldum áfram skulum við ganga úr skugga um að þú hafir einhvern stað þar sem þú getur gefið út vefinn þinn. Til eru þjónustur eins og Netlify o.fl. sem bjóða upp á einfalda hýsingu og kerfi til að gefa út statískar vefsíður. Ég ætla í restina að ganga út frá því að þú sért að hýsa vefinn á þjóni sem þú getur SSH-að þig inná og er með Zola og Git.

Á þjóninum, í möppu að þínu vali, segjum /home/notandanafn, býrðu til svokallaða bera Git lind, með eftirfarandi hætti:

git init gott-nafn-fyrir-bera-lind --bare

Síðan býrðu til möppur fyrir óvaranlegar skrár, segjum tmp, og fyrir síðuna, segjum /var/www/síða. Þú þarft líka að búa til svokallaðan post-receive krók með einhverjum ritli:

ritill gott-nafn-fyrir-bera-lind/hooks/post-receive

Þar skrifarðu eitthvað eins og eftirfarandi kóða

#!/bin/bash -l
#$HOME er breyta sem stendur fyrir /home/notandanafn
GIT_REPO=$HOME/gott-nafn-fyrir-bera-lind 
TMP_GIT_CLONE=$HOME/tmp/síða
PUBLIC_WWW=/var/www/síða

# Vegna þess að bera lindin er ekki með neinar skrár sem er hægt að vinna beint í þarf að klóna í tímabundna möppu
git clone $GIT_REPO $TMP_GIT_CLONE 
# Zola býður ekki upp á að builda í öðrum möppum en „working directory“
cd $TMP_GIT_CLONE 
# Vefur vefinn og setur hann í „public“ möppuna
zola build 
# Færir vefinn úr tímabundnu möppunni í möppunna sem þjónninn mun sækja hann úr
cp -r public/* $PUBLIC_WWW 
# Við viljum ekki eyða geymsluplássi og ef það eru skrár til staðar í möppunni þá er ekki hægt að klóna í hana
rm -rf $TMP_GIT_CLONE 
exit

Taktu eftir að við vefum vefinn á þjóninum svo þú þarft ekki og ættir ekki að vefa hann á þinni tölvu áður en þú setur í loftið.

Nú geturðu bætt beru lindinni við sem remote á þinni tölvu:

git remote add deploy ssh://notandanafn@lén-eða-ip-tala:gott-nafn-fyrir-bera-lind

Núna ættirðu að vera tilbúin/n/ð til að setja það sem þú ert komin með í loftið. Þá þarf að „add“-a skránum

git add .

„commit“-a breytingarnar

git commit

og þá ættirðu að vera tilbúin/n/ð til að „push“-a því sem þú ert með yfir á þjóninn

git push --set-upstream deploy master

Ef allt hefur gengið vel ætti vefurinn að vera kominn, ofinn, í /var/www/síða möppuna á þjóninum. Héreftir geturðu svo einfaldlega notað

git push

til að setja nýjar breytingar í loftið (eftir að þú ert búin/n/ð að adda og committa þeim, auðvitað). Þar sem þú átt eftir að nota þessar skipanir í röð mjög oft er sniðugt að gera Git alias (viðurnefni) fyrir þær:

git config --global alias.dep 'git add . && git commit && git push'

Jei, ég er búin/n/ð!

Bíddu nú aðeins með veisluna. Já, ef þú ert t.d. að setja þetta upp á HÍ léninu þínu eða slíku (en þá hefurðu væntanlega þurft að fara eitthvað út fyrir þessar leiðbeiningar) þá er þetta allt og sumt. Ef ekki, þá eru tveir hlutir enn sem þarf að ganga frá. Fyrst er það að setja upp DNS til að lénið þitt bendi á þjóninn, og hinsvegar er það að stilla þjónahugbúnaðinn á þjóninum svo fólk geti raunverulega skoðað fínu flottu síðuna þína. Ég ætla ekki að fara yfir DNSið, en ég skal fara stuttlega yfir þjónahlutann.

Fyrst þarftu hugbúnaðinn, þ.e. http þjón. Það eru til ýmsir slíkir þjónar. Um þessar mundir er Nginx mest notaði http þjónninn, enda er hann einn hraðvirkasti þjónninn sem fyrirfinnst og býður upp á margar öflugar öryggis- og skilvirknistillingar, en hann er kannski frekar gamaldags og ekki sérlega notendavænn. Síðan eru til nútímalegri þjónar eins og Armor sem býður upp á sjálfvirkt TLS (græni lásinn og https sem birtist í stikunni á vafranum), hraðvirkir þjónar með einfaldari stillingar eins og lighttpd, og svo öryggismiðaðir þjónar eins og Hiawatha.

Við skulum setja vefinn upp temmilega vel með Nginx. Eftir að þú ert búin/n/ð að ná í Nginx skulum við byrja að stilla það. Í skránni /etc/nginx/nginx.conf skaltu ganga úr skugga um að eftirfarandi komi fram:

http {
... # Einhverjar stillingar, skiptir ekki öllu máli
  # innlimar stillingar úr sites-enabled
  include /etc/nginx/sites-enabled/*; 
  charset utf-8; # Bara almenn skynsemi
  # Nokkrar öryggisstillingar
  add_header X-Frame-Options "SAMEORIGIN"; 
  add_header X-Content-Type-Options "nosniff";
  add_header X-XSS-Protection "1; mode=block";
  add_header Referrer-Policy "no-referrer-when-downgrade" always;
  add_header Strict-Transport-Security "max-age=32536000; includeSubDomains; preload" always;
...
}

Allt annað er alveg örugglega í lagi og stillt nógu vel. Skrifaðu síðan skrá í /etc/nginx/sites-available, t.d. site (búðu möppuna til ef hún er ekki þegar til), sem inniheldur:

server {
  listen 80;
  root /var/www/síða;
  server_name lénið-þitt.lénsendingin www.lénið-þitt.lénsendingin;
}

Búðu svo til „symbolic link“ að skránni í sites-enabled

sudo ln -s /etc/nginx/sites-available/site /etc/nginx/sites-enabled/

Núna ættirðu að ganga úr skugga um að stillingarnar standist með því að keyra

sudo nginx -t

Þá geturðu sett Nginx í gang og látið það ræsast með þjóninum þegar hann er endurræstur:

sudo systemctl start nginx.service
sudo systemctl enable nginx.service

Við erum þó ekki búin enn því við eigum eftir að ganga frá einu mikilvægu öryggisatriði, TLS. Ef þér finnst TLS vera óþarfa punt fyrir statískan vef hvet ég þig til að láta hr. Troy Hunt útskýra fyrir þér hvers vegna þú ættir alltaf að nota TLS, m.a.s. fyrir statíska vefi. Náðu í Certbot samkvæmt leiðbeiningum á heimasíðu verkefnisins. Nú fylgirðu leiðbeiningum þeirra og lætur Certbot endilega endurbeina http traffík í https. Þá mun Certbot sjá um að stilla Nginx með viðeigandi hætti. Nú mun TLS skírteinið sem þú fékkst ekki endast að eilífu, heldur þarftu að endurnýja það reglulega. Fínt er að búa til Systemd þjónustu sem endurnýjar það með viku millibili, en ítarlegri umfjöllun má finna á Arch Wiki. Þá býrðu til skránna /etc/systemd/system/certbot.service sem inniheldur eftirfarandi:

[Unit]
Description=Let's Encrypt renewal

[Service]
Type=oneshot
ExecStart=/usr/bin/certbot renew --quiet --agree-tos

Svo býrðu til skránna /etc/systemd/system/certbot.timer sem inniheldur:

[Unit]
Description=Vikuleg endurnýjun á Let's Encrypt skírteinum

[Timer]
OnCalendar=weekly
RandomizedDelaySec=1h
Persistent=true

[Install]
WantedBy=timers.target

og virkjar timerinn:

sudo systemctl start certbot.timer
sudo systemctl enable certbot.timer

Og þá ætti allt að vera tilbúið á enda þjónsins.

Hvert liggur þín leið?

Nú erum við komin með nokkuð skilvirkan og fínan vef en það er ýmislegt sem enn er hægt að fikta við. Til dæmis að for-þjappa vefinn, en þá er hægt að nota eins öfluga þjöppun og maður vill án þess að eyða tíma þegar skrárnar eru framreiddar til notandans. Eða þá að láta vafrann cacha skrám, sem hraðar ennþá meira á vefnum. Svo ekki sé minnst á öryggisatriðin sem enn er hægt að huga að.