Dit artikel beschrijft de installatie van Gogs op een Qnap NAS, samen met Adminer en PostgreSQL. De reden voor het schrijven van dit artikel is dat het me veel tijd heeft gekost om alles werkend te krijgen. Hopelijk helpt het onderstaande de lezer wat tijd te besparen.

Projectoverzicht

Het doel van dit project is om een Git server te bouwen die draait in een Docker container. En we slaan de gegevens van Gogs op in een aparte PostgreSQL database. Optioneel kan de database beheerd worden via Adminer.

Dus we gaan elk git beheerd software project naar Gogs pushen over het eigen netwerk (dat is snel!). Op die manier maken we ook meteen een back-up.

Wat is git?

Git is het meest gebruikte versiebeheersysteem voor software. Git houdt alle wijzigingen in de software bij, zodat je altijd precies kunt zien wat er is doorgevoerd. Bovendien kun je teruggaan naar eerdere versies. Git maakt ook samenwerking makkelijker, door de wijzigingen van meerdere mensen samen te voegen tot één bron. Dus of je nu wel of niet in een team werkt, Git is nuttig voor alle softwareontwikkelaars.

Wat is Docker?

Er is niets mis met het installeren van een programma voor een specifiek doel op uw computer of NAS. Maar sommige programma’s zijn niet bedoeld om in uw besturingssysteem te draaien, bijvoorbeeld een Linux-programma in MS Windows. In zulke gevallen zijn containers erg handig. Een container bevat een toepassing die is afgeschermd van zijn omgeving, maar nog steeds gebruik maakt van het besturingssysteem waarin het draait. Je kunt de container starten, stoppen of gewoon weggooien; het besturingssysteem blijft gewoon schoon. Dit zijn belangrijke pluspunten voor een NAS, omdat je een dienst op deze manier snel kunt stoppen en starten. Het meest gebruikte platform voor het maken van containers is Docker en is standaard geïnstalleerd in NAS-apparaten van QNAP en Synology.

Wat is Gogs?

Gogs is de afkorting van ‘Go Git Service’ en is een zelf gehoste Git-dienst. Samenwerkende programmeurs zijn gewend om hun projecten te posten op GitHub of GitLab. En zolang die projecten niet te groot zijn, is dat prima, zeker als iedereen die projecten mag zien. Als je met grote bestanden werkt of als je niet wilt dat iedereen over je schouder meekijkt, kan het opzetten van je eigen Git-server een optie zijn.

Wat is PostgreSQL?

Om de git-data van dit project op te slaan gebruiken we een database. Gogs kan overweg met verschillende databases zoals MySql en SQLite3. Voor dit project is gekozen voor PostgreSQL omdat het snel, klein en open source is.

Wat is Adminer?

Adminer is een databasebeheerprogramma dat in een webbrowser draait. Het is een vervanging voor het bekende phpMyAdmin. Adminer is toegevoegd uit nieuwsgierigheid, hoe ziet de database er eigenlijk uit? Het kan worden weggelaten als u dat wenst.

Scope

In scope van dit project is de installatie en een voorbeeld van het project. Maar diepgaande informatie over git, Docker, Gogs, PostgreSQL en Adminer valt buiten de scope.

Installatie

De installation bestaat uit drie delen:

• Installeren van Container Station in de NAS.
• Maken van een gebruiker die in staat moet zijn om files in de NAS te schrijven. Dit is niet een gewone gebruiken die normaal inlogt op de NAS, maar wordt uitsluitend door de containers gebruikt.
• Bouwen van Docker containers in de NAS.

Container Station

Om containers op een QNAP NAS te draaien is Container Station nodig. Indien Container Station nog niet is geïnstalleerd in de NAS, kan dat via het App Center in het Dashboard worden gedaan:

Het maakt een locatie aan waar het zijn containers opslaat, onthoud deze locatie. Standaard heet het ‘Containers’ en u kunt het zien in QNAP File Station.

Aanmaken van een containergebruiker

Om iets te doen in een NAS, moet je inloggen. Hetzelfde geldt voor een container, dus we moeten een nieuwe gebruiker aanmaken die kan lezen en schrijven in de mappen waar de containers zich bevinden. In de documentatie staat hoe een nieuwe gebruiker gemaakt moet worden (Control Panel > Users). In dit project wordt de naam ‘gogs‘ gebruikt.

Elke gebruiker heeft een unieke UID en maakt deel uit van een groep met een GID. Om gemakkelijk te weten te komen welke ID’s bij uw gebruiker horen, kunt u het beste inloggen op de NAS via SSH. Om SSH in te schakelen op de NAS:

1. Log in op de NAS als beheerder.
2. Ga naar Configuratiescherm > Netwerk & Bestandsservices > Telnet / SSH.
3. Selecteer SSH-verbinding toestaan (Alleen beheerders kunnen op afstand inloggen.).
4. Optioneel: Wijzig het poortnummer (22) niet, aangezien het project een andere (222) zal gebruiken.
   Klik op Apply (Toepassen).

Vanaf uw apparaat zou u moeten kunnen inloggen op uw NAS via een terminal in Linux of in Windows (typ bij zoeken ‘cmd’ en druk op enter). Maak nu verbinding met de NAS (waarbij gebruiker de gebruikte beheerdersnaam is):

Wanneer u ingelogd bent, typ dan:

Dit toont de UID en de GID die u later nodig hebt:

Map aanmaken

Gogs en de database hebben opslagruimte nodig. Zoek en selecteer in QNAP File Station de map Container. Maak vervolgens twee nieuwe mappen aan door op de ‘+’-knop te drukken:

In dit project zijn de namen ‘gogs-postgres‘ en ‘gogs-server‘ gemaakt. Het resultaat ziet er zo uit:

Na het aanmaken van beide mappen moet u uw gebruiker toegang geven tot deze mappen. Zoek uw gebruiker en klik op de knop ‘Machtigingen voor gedeelde mappen bewerken’:

Check de ‘RW’ box van ‘Container’.

Creëren van containers

Meerdere containers die met elkaar communiceren wordt in Docker Compose een applicatie genoemd. Een Docker-applicatie wordt gebouwd met een Compose-configuratiebestand. Dit is een YAML-bestand dat diensten, netwerken en volumes definieert.

In Container Station kan ook een Docker-applicatie worden gemaakt. Er zijn twee versies van Container Station:

• QNAP Container Station 2: selecteer in het menu ‘Create’, klik daarna op ‘Create Application’.
• QNAP Container Station 3: selecteer in het menu ‘Applications’, klik daarna op ‘Create’.

Geef de applicatie een naam, bijvoorbeeld ‘Gogs’. Er is een standaard yaml sjabloon, verwijder alle regels:

Kopieer/plak onderstaande Docker Compose code in het lege sjabloon:

version: "3"

networks:
  gogs:
    external: false

services:
  server:
    image: gogs/gogs:latest
    container_name: gogs
    environment:
      - USER_UID=1004
      - USER_GID=100
      - GOGS__database__DB_TYPE=postgres
      - GOGS__database__HOST=db:5432
      - GOGS__database__NAME=gogs
      - GOGS__database__USER=gogs
      - GOGS__database__PASSWD=gogs
    restart: always
    networks:
      - gogs
    volumes:
      - /share/Container/gogs-server:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      # 222 outgoing used because of qnaps ssh server on port 22
      - "222:22" 
    depends_on:
      - db

  adminer:
    image: adminer:latest
    restart: always
    networks:
      - gogs
    ports:
      - "5000:8080"
    depends_on:
      - db
    environment:
      ADMINER_DEFAULT_SERVER: postgresql
      ADMINER_DEFAULT_DB_HOST: db
      ADMINER_DEFAULT_DB_NAME: gogs
      ADMINER_PASSWORD: gogs
      ADMINER_DESIGN: rmsoft

  db:
    image: postgres
    restart: always
    environment:
      - POSTGRES_USER=gogs
      - POSTGRES_PASSWORD=gogs
      - POSTGRES_DB=gogs
    networks:
      - gogs
    ports:
      - "5432:5432"
    volumes:
      - /share/Container/gogs-postgres:/var/lib/postgresql/data

Als u Adminer niet geïnstalleerd wilt hebben, kopieer/plak dan onderstaande code die alleen Gogs en database containers aanmaakt:

version: "3"

networks:
  gogs:
    external: false

services:
  server:
    image: gogs/gogs:latest
    container_name: gogs
    environment:
      - USER_UID=1004
      - USER_GID=100
      - GOGS__database__DB_TYPE=postgres
      - GOGS__database__HOST=db:5432
      - GOGS__database__NAME=gogs
      - GOGS__database__USER=gogs
      - GOGS__database__PASSWD=gogs
    restart: always
    networks:
      - gogs
    volumes:
      - /share/Container/gogs-server:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      # 222 outgoing used because of qnaps ssh server on port 22
      - "222:22" 
    depends_on:
      - db

  db:
    image: postgres
    restart: always
    environment:
      - POSTGRES_USER=gogs
      - POSTGRES_PASSWORD=gogs
      - POSTGRES_DB=gogs
    networks:
      - gogs
    ports:
      - "5432:5432"
    volumes:
      - /share/Container/gogs-postgres:/var/lib/postgresql/data

Verklaring van de code

Het configuratiebestand bestaat uit twee delen, netwerken en diensten. Het dienstengedeelte bestaat uit drie containers:

• server, dit is de Gogs container.
• adminer, een container voor database administration (optioneel).
• db, de container met een PostgreSQL database.

Kijk naar de server omgevingsregels en verander de USER_UID en de USER_GID in de nummers van uw gebruiker. Als je andere mapnamen hebt gebruikt moet je die ook veranderen in de volumes sectie van server en db.

Klik op Valideer YAML om te controleren of de code correct is. Druk op de knop ‘Create’. Container Station zal de Docker Containers downloaden van Docker Hub (waar veel pre-build containers op staan) en creëert een applicatie.

Als u klaar bent ziet u een nieuwe App in het Container Station overzicht:

Als u op de ‘⏵’ klikt, gaan de drie containers van de app open:

De ‘⏹’ aan het eind van elke regel betekent dat de containers draaien. Omdat ze grijs zijn, kunt u ze stoppen door de app te selecteren:

Nu kunt u de app stoppen en starten met de knoppen boven het app-overzicht:

Configureren van Gogs

Als de containers draaien, kun je op twee manieren verbinding maken met Gogs:

• In een browser door http://<ip-of-your-NAS>:3000 in te voeren.
• Klikken op ‘🔗’ in het container overzicht zal een niewe tab in de browser openen.

Tijden het openen van Gogs voor de eerste keer verschijnt een instelscherm. Sommige velden zijn al ingevuld, maar niet allemaal correct. Host moet worden gewijzigd omdat we Gogs draaien in een Docker container (waar we de database db hebben genoemd, zie Docker compose code hierboven). En domein is niet localhost maar IP van uw NAS. Controleer de volgende voorbeeldlijst zorgvuldig:

Item	Value
Database-type	PostgreSQL
Host	db:5432
Username	gogs
Password	gogs
Database name	gogs
Schema	public
SSL modus	Disable
Application name	Gogs
Repositories base directory	/data/git/gitstore
Executive username	git
Domain	<your NAS address> for example: 192.168.178.200
SSH port	222 (as 22 is used already by NAS)
HTTP port	3000
Application URL	<http://<NAS address>:3000/> for example: http://192.168.178.200:3000/
Log path	/app/gogs/log
Default Branch	Master
Optional:
SMTP host	for example Gmail: smtp.gmail.com:587
Receiver	<you>@gmail.com
Receiver email	<you>@gmail.com
Password	<secret>
Admin account:	<admin name> (not your NAS admin!)
Password	<secret>
Verify password	<secret>
Admin email	<you>@gmail.com

Als de lijst is ingevuld, drukt u op de knop ‘Gogs installeren’.

Nieuwe gebruiker creëren

Maak een apart account aan voor elke Gogs gebruiker. Klik op de dropdown knop naast je login icoon en kies ‘Admin panel’:

In ‘Admin panel’ kies ‘Gebruikers’:

Maak hier een nieuwe gebruiker aan met de knop ‘Create new account’ (Nederlandse afbeelding wordt getoond):

Elke gebruiker heeft een uniek e-mailadres nodig, omdat dit wordt gebruikt om gebruikers te identificeren via SSH, zie het hoofdstuk hieronder.

Configureren van SSH

Hoewel het mogelijk is om Gogs te gebruiken met http, is het veiliger om verbinding te maken met de NAS en met de containers binnenin via ssh. Dit protocol werkt met een private sleutel (opgeslagen in uw pc of laptop) en een publieke sleutel (opgeslagen in de NAS Container directory). Dus, elke keer dat u verbinding maakt met Gogs worden uw ssh-sleutels gecontroleerd:

Maak een SSH sleutelpaar aan in uw terminal (op windows moet u wellicht eerst git for windows installeren en git bash openen):

$ ssh-keygen -t ed25519 -C "you@gmail.com"

De ‘ed25519’ optie is op dit moment het meest algemeen gebruikte encryptie protocol en veiliger dan RSA. Het is belangrijk dat u hetzelfde e-mailadres invult als bij het inloggen.

Tijdens het genereren van de sleutel worden enkele vragen gesteld. Wanneer u wordt gevraagd “Voer een bestand in waarin u de sleutel wilt opslaan”, kunt u op Enter drukken om de standaard bestandslocatie te accepteren. En optioneel kunt u een wachtwoordzin invoeren en ergens opslaan. Als u die aanmaakt wordt er tijdens het werken met git om gevraagd. Maak dus een eenvoudig te onthouden en niet te lange zin.

Nu is het tijd om de publieke sleutel in Gogs in te voeren. Log in op Gogs (uw NAS admin account is voldoende) en zoek uw profiel in de rechterbovenhoek van het scherm:

Klik erop en kies ‘Uw instellingen’. Links in de instellingen kiest u SSH-keys en klikt u op ‘Sleutel toevoegen’. Geef het dezelfde naam als uw publieke sleutel en plak de inhoud van de publieke sleutel. Als u klaar bent, drukt u op ‘Sleutel toevoegen’ en uw sleutel is toegevoegd (de Nederlandse versie wordt hier getoond):

Creëer een niewe repository

We hebben tot nu toe veel tijd besteed aan het configureren van Gogs. Nu is het tijd om Gogs daadwerkelijk te gebruiken! Voor zover ik weet is het niet mogelijk om een nieuwe repository in Gogs aan te maken via git, je kunt alleen verbinden met een bestaande.

Om als gebruiker een nieuwe repository aan te maken, log je in op Gogs en verschijnt het dashboard. Hier kan een nieuwe repository worden aangemaakt door op de ‘+’ knop te klikken:

Als beheerder kun je ook repositories van gebruikers verwijderen door op het emmer-icoontje te klikken:

Klik op de ‘+’-knop zoals hierboven beschreven of klik op de ‘+’-knop naast uw naam:

Maak een nieuwe directory aan, bijvoorbeeld met de naam ’test’:

Na het klikken op de create knop wordt een nieuw venster met een standaard boodschap getoond. De sectie ‘Maak een nieuwe repository aan vanuit de console’ beschrijft alle noodzakelijke stappen die je nodig hebt om deze repository met git te gebruiken.

Werken met git

Open op uw MS Windows (in Git for Windows) of Linux computer open een terminal ergens in uw home directory. Maak een niewe directory:

Daarin voeren we de stappen uit die in het standaard Gogs bericht staan. Met ’touch README.md’ wordt een leeg markdown bestand aangemaakt. En ‘git init’ is het eerste commando om git te starten met versiebeheer in deze map:

Check met ‘ls -la’ wat er tot nu toe is gecreëerd:

Een verborgen directory .git wordt aangemaakt en het lege README bestand. Als je de .git directory opent (cd .git) zie je een aantal bestanden en directories:

Aangezien git deze directory zelf zal onderhouden hoef hier niets gedaan te worden. Met ‘cd ..’ kan naar de bovenliggende map terug gegaan worden. Open het README.md bestand met een willekeurige tekstverwerker, bijvoorbeeld Notepad in Windows. In Linux volstaat elke tekstverwerker, ik werk meestal met ReText dat in veel Linux-distributies beschikbaar is. Kopieer/plak het volgende voorbeeld:

## Project Test

#### Author: Me, myself and I

#### Aim: demonstrate markdown language

Create a list:

 1. Project one
 2. Project two

### Create a new repository from console:

    touch README.md
    git init
    git add README.md
    git commit -m "first commit"
    git remote add origin ssh://git@192.168.178.200:222/Jan/test.git
    git push -u origin master

### Push an existing repository from console:

    git remote add origin ssh://git@192.168.178.200:222/Jan/test.git
    git push -u origin master

Kijk in dit spiekbriefje hoe de markdown-structuur in elkaar steekt. Als u klaar bent slaat u het bestand op en opent u uw terminal.

Oeps, ik heb een fout gemaakt. Ik probeerde mijn wijziging vast te leggen zonder eerst het nieuwe bestand toe te voegen. Met ‘git status’ zie je dat er geen commits gedaan zijn. Dus:

Dit ziet er beter uit, we zijn nu klaar om het nieuwe bestand naar onze Gogs repository te pushen. Hiervoor moeten we eerst git vertellen waar deze repository bestaat. In dit voorbeeld moet je het IP vervangen door het IP van uw NAS en ‘USER’ door uw gebruikersnaam die u in hoofdstuk ‘Nieuwe gebruiker creëren‘ hebt gemaakt:

U kunt controleren of dit commando succesvol was:

En tenslotte kunnen we ons bestand uploaden:

Als dat nog niet gebeurd is, log dan in op Gogs en het nieuwe bestand wordt getoond:

Gereed!

Als u hier bent aangekomen, heeft u hopelijk een werkende Gogs applicatie draaien in QNAP NAS.