Versie beheer werkt door middel van ‘Git’. De site is gehost op Gitlab en na iedere commit wordt er automatisch een nieuwe versie gemaakt en gedeployed met ‘Netlify’. Deze pagina geeft meer informatie over hoe je deze services het beste kan gebruiken in combinatie met de Fablab Website.

Virtual Environment #

Het is een ‘best practice’ om development te doen in een virtuele environment om zo geen conflicten te krijgen met bestaande packages en om je computer schoon te houden. Er zijn diverse manieren (en software) om dit te doen, maar ik gebruik graag ‘conda’. Van conda zijn er verschillende varianten beschikbaar waaronder ‘anaconda’ dat veel gebruikt wordt door datascientist. Dit installeert echter een complete GUI met diverse data science packages wat voor veel mensen niet relevant is. ‘Miniconda’ is daarom een fijne minimale versie van conda met alles wat je nodig hebt om virtuele python environments te maken.

• Miniconda installers

Nadat je conda hebt geinstalleerd kun je eenvoudig een virtuele environment voor de Fablab website aanmaken via de terminal:

1. maak een nieuwe environment met een naam naar keuze:

conda create --name fablab-website 

2. type Y en bevestig met ⏎ Enter als conda vraagt om door te gaan:

proceed ([y]/n)?

3. Activeer je nieuwe environment.

conda activate fablab-website

4. Als alles goed is gegaan zie je afhankelijk van je besturingssysteem op iedere terminal regel nu (fablab-website) staan. Het laaste wat we moeten doen is 2 packages installeren die noodzakelijk zijn voor de website:

conda install -c conda-forge nodejs=22
npm install hugo-extended

Een overzicht van alle environments (waarbij base de standaard is) vind je als volgt:

conda env list

Is er iets fout gegaan of wil je de omgeving verwijderen?:

conda deactivate
conda remove -n fablab-website --all

Setup #

Je kunt altijd inloggen op Gitlab en daar wijzigingen maken, maar ik raad aan om een lokale kopie te maken van onze repository. Maak eerst een nieuwe folder waar je in gaat werken, navigeer naar deze folder via je terminal, en clone dan de repository. Als je in de root van de repository bent, kun je alle node packages lokaal installeren met ’npm install’. Het beste doe je dit in een virutal environment zoals hierboven is uitgelegd. Setup voorbeeld:

cd base directory
git clone https://gitlab.com/fablabarnhem/fablab-website.git
cd fablab-website # root 
conda activate fablab-website # optional virtual environment
npm install # Install packages locally (may take several minutes)

Er wordt vanuit gegaan dat je toegang hebt tot deze repository via Gitlab credentials of een SSH key.

Wijziging maken #

Het kan zijn dat iemand in de tussentijd wijzigingen gemaakt heeft en daarom is het een goed idee om altijd de laatste updates uit de repository door te voeren voordat je zelf wijzigingen maakt.

1. Controleer of je ‘working tree’ schoon is:

git status

2. Als hier niks staat kun je simpelweg de laatste updates binnenhalen met een pull request. Echter zul je in sommige gevallen bijvoorbeeld al wijzigingen zien in ‘hugo-stats.json’ en ‘package-lock.json’ doordat je een keer ’npm run dev’ hebt gedraaid. Dit is geen probleem, maar zorgt er wel voor dat een simpele ‘git pull’ conflicten oplevert. Het kan ook zo zijn dat je al een week werkt aan een specifieke post of bent vergeten te ‘pullen’ en dat hier dus nog markdown wijzigingen van jezelf staan. In beide gevallen moet je eerst deze wijzigingen ‘stagen’ en daarna ‘committen’.

git add . # stage all changes
git commit -m "description of changes" 

Het is ook mogelijk om simpelweg al je eigen wijzigingen weg te gooien (in bijvoorbeeld de hugo-stats en package-lock) files.

git restore . # remove all changes

3. De lokale wijzigingen zijn nu verwijdert of opgeslagen in een commit en daardoor is het mogelijk om de laatste updates uit de repository binnen te halen zonder conflicten. Dit doen we door middel van een ‘pull’ met eventueel ‘rebase’. Rebase haalt de laatste updates binnen en zorgt ervoor dat jouw eerder gemaakte commit in de tijd wordt geplaatst na de ‘pull’ die je zojuist hebt gedaan. Je eventuele wijzigingen zijn dus niet verloren gegaan.

git pull --rebase # if you changed / committed things
git pull # if you restored / changed nothing

4. Het is nu mogelijk om zonder problemen wijzigingen te maken op basis van de meest recente versie van de website. Maak bijvoorbeeld nieuwe markdown files / wijzig posts en upload afbeeldingen. Zorg ervoor dat je altijd de wijzigingen test voordat je ze doorvoert.

npm run dev # test changes locally

5. Ben je tevreden met de wijzigingen? Vergeet dan niet opnieuw te stagen / committen. Hierna kun je de wijzigingen uploaden naar de website door middel van een ‘push’.

git add .
git commit -m "New changes"
git push

Na het pushen van jouw commit gaat Netlify de website opnieuw opbouwen. Dit kost gemiddeld 3 minuten.

Visual Studio Code #

Bovenstaande informatie laat zien hoe we wijzigingen doorvoeren door middel van de ’terminal’. Het is goed om te begrijpen wat er gebeurd, maar het is echter ook mogelijk om dit direct te doen met Visual studio code. In principe is de werking exact hetzelfde, maar in plaats van commando’s doorvoeren met de terminal, doen we dit nu met source control in VSC.

1. Kijk of de working tree clean is:

Kijk of er in je ‘source control’ geen wijzigingen (changes) staan. Source control herken je aan het ‘git’ symbool.

2. Eventueel: Stage en commit changes

Stage en commit lokale wijzigingen indien je working tree niet clean is (als er dus changes zijn in source control).

3. Pull met rebase

Dit zorgt ervoor dat jouw niet gepushte commit geplaatst wordt na de ‘pull’.

4. Commit & Push changes

Nadat je de website hebt gewijzigd en alle verandering zijn getest, is het tijd om ze daadwerkelijk door te voeren. Dit doe je door alle nieuwe wijzigingen te committen en daarna te pushen.

Lokaal testen #

Er zijn twee manieren om een lokale kopie van de website te draaien voor development doeleinden nadat je de setup hebt uitgevoerd.

1. Dev

Dit is de gemakkelijkste en meest gebruikte manier. Hiermee host je lokaal een development server. Iedere keer als je een wijziging opslaat zal de server de website binnen enkele milliseconden opnieuw opbouwen zodat je direct de verandering ziet. Om te starten open je een terminal met de juiste virtuele environment. Navigeer vervolgens naar de root directory (fablab-website) en start de development server.

cd fablab-website
conda activate fablab-website # Optional virtual environment
npm run dev

De website is vervolgens via de browser bereikbaar op: http://localhost:1313/

De eerste keer zal het iets langer duren om de website op te bouwen. Alle vervolg builds maken gebruik van caching en zijn dus erg snel.

2. Production

In plaats van ’npm run dev’ kun je ook een ‘production build’ lokaal hosten. Dit is een exacte kopie van hoe de website eruit gaat zien nadat het gedeployed is via Netlify. Wat is het verschil? Het kan bijvoorbeeld soms zijn dat er dingen mis gaan met hoe de code automatisch wordt opgeschoond en samengevoegd. Voor de meeste mensen is dit niet relevant, tenzij je echt onderdelen van de website opnieuw aan het bouwen bent. Het voordeel van deze versie is echter wel dat er lokaal een server gehost wordt die bijvoorbeeld ook bereikbaar is met je telefoon (vite). De production build laat wijzigingen niet direct zien.

npm run build -- --baseURL=/ && npm run preview -- --host

Nu kun je op je eigen computer via http://localhost:4173/ de productie website bekijken. De terminal laat ook een ’network’ ip adres zien waarmee de website bereikbaar is met andere devices.

Automatische Deploys #

We gebruiken Netlify Functions om de website automatisch opnieuw op te bouwen op ingeplande momenten. Dit is een stukje custom code dat nu gebruikt wordt om onder andere op maandag en woensdag avond de website te rebuilden zodat de workshops altijd actueel zijn. In het mapje functions vind je bijvoorbeeld scheduled-rebuild.mts. Deze code gebruikt een Netlify Webhook, een soort URL, die op basis van een post request de rebuild triggered. Voor veiligheidsredenen refereren we naar deze webhook via een ’environment variable’. Verwijder de functie simpelweg als deze niet meer relevant is. Wil je de geplande momenten aanpassen? Dat doe je door de cron syntax in de code te wijzigen:

* * * * *
| | | | |
| | | | |____ Day of the week (0-6) (Sunday to Saturday)
| | | |______ Month (1-12)
| | |________ Day of the month (1-31)
| |__________ Hour (0-23)
|____________ Minute (0-59)

// Netlify scheduled function cron syntax
// Run every Monday and Wednesday at 23:55
export const config: Config = {
    schedule: '55 23 * * 1,3'
};