Outline Knowledgebase Wiki installeren op Ubuntu met Docker

Outline is een open-source, collaboratieve, kennisbank software. Je kunt het gebruiken om documentatie en fanpagina’s te hosten of zelfs om notities te delen. Het bevat een markdown editor en integreert met meerdere diensten zoals Slack, Figma, Airtable, Google Docs, Trello, Zapier, Codepen, Spotify, Youtube, enz. Het heeft beveiligingsfuncties zoals gebruikersgroepen met aparte lees- en schrijfrechten, staat openbaar delen toe en heeft RTL ondersteuning met vertalingen in 13 talen. Het is gebouwd met behulp van React en Node.js. Er zijn twee manieren om Outline te gebruiken. De ene is hun cloud-hosted versie, of je kunt het op je server hosten.

Deze zelfstudie leert je hoe je Outline Wiki op een Ubuntu-gebaseerde server kunt installeren met Docker.

Vereisten

  • Een server waarop Ubuntu 20.04 draait met minimaal 1 GB RAM.

  • Een niet-root gebruiker met sudo rechten.

  • Een domeinnaam die naar de server wijst. We zullen https://outline.example.com gebruiken voor onze zelfstudie.

  • Een paar essentiële apps om aan de slag te gaan.

    $ sudo apt install nano curl wget unzip gnupg
    

Stap 1 – Configureer Firewall

De eerste stap is het instellen van de firewall. Ubuntu wordt standaard geleverd met ufw (Uncomplicated Firewall).

Controleer of de firewall draait.

$ sudo ufw status

Je zou de volgende uitvoer moeten krijgen.

Status: inactive

Sta SSH poort toe, zodat de firewall de huidige verbinding niet verbreekt bij het inschakelen ervan.

$ sudo ufw allow OpenSSH

Sta ook HTTP en HTTPS poorten toe.

$ sudo ufw allow 80
$ sudo ufw allow 443

Schakel de firewall in.

$ sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

Controleer opnieuw de status van de firewall.

$ sudo ufw status

Je zou een gelijkaardige uitvoer moeten zien.

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80                         ALLOW       Anywhere
443                        ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
80 (v6)                    ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)

Stap 2 – Installeer Docker

We zullen Docker moeten installeren met behulp van zijn officiële repository. Voeg de officiële GPG sleutel van Docker toe.

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Voeg de Docker repository toe aan het systeem.

$ echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Werk de APT repository lijst bij en installeer Docker.

$ sudo apt update
$ sudo apt install docker-ce

Controleer of de Docker engine goed geïnstalleerd is.

$ docker --version
Docker version 20.10.14, build a224086

Voer de volgende commando’s uit, zodat je geen sudo hoeft te gebruiken om Docker commando’s uit te voeren.

$ sudo usermod -aG docker ${USER}
$ su - ${USER}

Stap 3 – Installeer Docker Compose

Voer het volgende commando uit om Docker compose te installeren. Docker Compose werd onlangs bijgewerkt naar v2.0, wat veel brekende veranderingen introduceerde. We zullen de laatste 1.x versie gebruiken die beschikbaar is op zijn Github releases pagina.

$ sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

Pas de executable toestemming toe op de Docker compose binary.

$ sudo chmod +x /usr/local/bin/docker-compose

Controleer of Docker Compose correct geïnstalleerd is.

$ docker-compose --version
docker-compose version 1.29.2, build 5becea4c

Installeer Command completion voor Docker compose.

$ sudo curl \
	-L https://raw.githubusercontent.com/docker/compose/1.29.2/contrib/completion/bash/docker-compose \
    -o /etc/bash_completion.d/docker-compose
$ source ~/.bashrc

Hiermee is het Docker en Docker compose installatie deel van de zelfstudie voltooid.

Stap 4 – Maak een omgevingsbestand voor Docker

Configureer Slack Authenticatie

Outline vereist dat je een authenticatie provider instelt. Voor onze zelfstudie zullen we inloggen op basis van Slack configureren.

Meld je aan met je Slack account en ga naar de API Apps pagina van Slack.

Slack API apps

Klik op de knop Create an App om verder te gaan. Klik op de link From Scratch om de app te maken.

Slack maak app popup

Kies een naam voor je app en kies de werkruimte waar je je app wilt laten verschijnen. Als je je app niet aan de bestaande werkruimte wilt koppelen, kun je een andere aanmaken en op deze stap terugkomen.

Slack App Naam Popup

Klik op de knop Create App als je klaar bent. Scroll vervolgens naar beneden tot onderaan de pagina en geef je app een beschrijving, een icoon, en een achtergrondkleur.

Slack Nieuwe app opties

Klik op de Save Changes knop als je klaar bent. Kies de optie OAuth and Permissions uit de linker zijbalk.

Slack OAuth menu

Voeg de omleidings-URL https://outline.example.com/auth/slack.callback toe in het daarvoor bestemde vak en klik op de knop Toevoegen.

Slack doorverwijzings URL

Klik op de Bewaar URL’s knop om verder te gaan. Scroll naar beneden naar het onderdeel User Token Scopes van de pagina en kies de volgende scopes uit het dropdown menu.

  • identity.avatar
  • identity.basic
  • identity.email
  • identity.team

Slack Token Scopes

Ga terug naar de Basisinformatie pagina uit de linker zijbalk. Kopieer de waarden Client ID en Client Secret uit hun vakjes onder App Credentials.

Credentials voor de Slack App

Configureer Slack integratie

Bezoek de optie Slash Commands uit de linker zijbalk.

Slash commando's pagina

Klik op de resulterende pagina op de knop New Command. Voer /outline in als het commando. Voer https://outline.example.com/api/hooks.slack in als de Request URL. Voer een beschrijving voor je commando in en een woord als hint. Klik op de knop Opslaan onderaan als je klaar bent.

Schets Wiki Maak Slack Commando

Open het menu Functies >> Interactiviteit en Snelkoppelingen in de linker zijbalk. Schakel Interactiviteit in door de toggle knop om te zetten en plak https://outline.example.com/api/hooks.interactive als de Verzoek URL. Klik op de knop Wijzigingen opslaan om klaar te zijn.

Schets Wiki Slack Interactiviteit

Open de Instellingen >> App installeren pagina uit de linker zijbalk en klik op de knop Install to WorkSpace om de App voor je Slack werkruimte te installeren.

Schets Wiki Slack App Installeren

Bezoek de Basisinformatie pagina uit de linker zijbalk en kopieer App ID en Verificatie Token waarden voor de slack app integratie.

Maak S3 geloofsbrieven aan

Maak een S3 emmer voor je Outline installatie op AWS of een andere S3 compatibele dienst. Voeg na het aanmaken van de emmer de volgende policy JSON toe om Cross-origin resource sharing (CORS) in te stellen. Vervang de waarde van AllowedOrigins door je Outline URL.

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "PUT",
            "POST"
        ],
        "AllowedOrigins": [
            "https://docs.mycompany.com"
        ],
        "ExposeHeaders": []
    },
    {
        "AllowedHeaders": [],
        "AllowedMethods": [
            "GET"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": []
    }
]

Maak een IAM gebruiker aan met het volgende beleid. Vervang de my-bucket-name door de werkelijke naam van je Outline S3 emmer.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor",
            "Effect": "Allow",
            "Action": [
                "s3:GetObjectAcl",
                "s3:DeleteObject",
                "s3:PutObject",
                "s3:GetObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::my-bucket-name/*"
        }
    ]
}

Nu je je IAM gebruiker hebt aangemaakt genereer je een toegangssleutel en geheim voor je emmer gebruiker.

Geheime sleutels maken

Het omgevingsbestand vereist een geheime sleutel en een utiliteitsgeheim. Voer tweemaal het volgende commando uit om beide sleutels te genereren.

$ openssl rand -hex 32

Kopieer deze waarden en bewaar ze.

Maak en bewerk het omgevingsbestand

Maak een map voor de docker instellingen voor Outline.

$ mkdir ~/outline

Ga naar de directory.

$ cd ~/outline

Maak het docker.env bestand aan en open het om te bewerken. In dit bestand worden alle omgevingsvariabelen opgeslagen die nodig zijn voor de installatie.

$ nano docker.env

Plak er de volgende code in. Voer de eerder gemaakte geheime sleutel en utils secret in. Kopieer de eerder gemaakte Slack credentials voor de authenticatie en app integratie. Voer je Amazon S3 credentials in zoals hieronder aangegeven.

Als je Google Analytics wilt gebruiken om de statistieken van je Outline applicatie bij te houden, voer dan je Analytics ID in het onderstaande veld in. Voorlopig ondersteunt Outline geen GA4 tags, dus je zult je oude tracking ID moeten invoeren.

Deel voor de variabele WEB_CONCURRENCY je systeem ram door 512 en voer de waarde bij benadering in. De variabele FORCE_HTTPS is op false gezet omdat we Nginx als proxy server gebruiken.

# –––––––––––––––– REQUIRED ––––––––––––––––
SECRET_KEY=generate_a_new_key
UTILS_SECRET=generate_a_new_key

POSTGRES_USER=outlinepg
POSTGRES_PASSWORD=yourpassword
POSTGRES_DB=outline
DATABASE_URL=postgres://outlinepg:[email protected]:5432/outline
DATABASE_URL_TEST=postgres://outlinepg:[email protected]:5432/outline-test
PGSSLMODE=disable
REDIS_URL=redis://localhost:6379

URL=https://docs.example.com
PORT=3000

AWS_ACCESS_KEY_ID=get_a_key_from_aws
AWS_SECRET_ACCESS_KEY=get_the_secret_of_above_key
AWS_REGION=us-east-2
AWS_S3_UPLOAD_BUCKET_URL=https://my-bucket-name.s3.us-east-2.amazonaws.com
AWS_S3_UPLOAD_BUCKET_NAME=my-bucket-name
AWS_S3_UPLOAD_MAX_SIZE=26214400
AWS_S3_FORCE_PATH_STYLE=true

# –––––––––––––– AUTHENTICATION ––––––––––––––
SLACK_KEY=<slackclientid>
SLACK_SECRET=<slackclientsecret>

# –––––––––––––––– OPTIONAL ––––––––––––––––
GOOGLE_ANALYTICS_ID=UA-XXXXXXX-1

SLACK_VERIFICATION_TOKEN=your_token
SLACK_APP_ID=A0XXXXXXX
SLACK_MESSAGE_ACTIONS=true

FORCE_HTTPS=false
ENABLE_UPDATES=true
WEB_CONCURRENCY=2

Het bovenstaande bestand is gebaseerd op het voorbeeldbestand uit Outline’s Github repository. Als je extra instellingen moet instellen, kun je ze daaruit naar je bestand kopiëren.

Sla het bestand op door op Ctrl + X te drukken en Y in te voeren als daarom gevraagd wordt.

Stap 5 – Maak een Docker Compose bestand voor Outline

Maak het docker-compose.yml bestand en open het om het te bewerken.

$ nano docker-compose.yml

Plak er de volgende code in.

version: "3"
services:

  outline:
    image: outlinewiki/outline:latest
    restart: always
    command: sh -c "yarn sequelize:migrate --env=production-ssl-disabled && yarn start --env=production-ssl-disabled"
    env_file: ./docker.env
    ports:
      - "3000:3000"
    depends_on:
      - postgres
      - redis

  redis:
    image: redis
    restart: always
    env_file: ./docker.env
    ports:
      - "6379:6379"
    volumes:
      - ./redis.conf:/redis.conf
    command: ["redis-server", "/redis.conf"]

  postgres:
    image: postgres
    restart: always
    env_file: ./docker.env
    ports:
      - "5432:5432"
    volumes:
      - database-data:/var/lib/postgresql/data

volumes:
  database-data:

Sla het bestand op door op Ctrl + X te drukken en Y in te voeren als daarom gevraagd wordt.

Stap 6 – Installeer Outline

Installeer Outline door de containers te starten.

$ docker-compose up -d

Controleer de status van de containers.

$ docker ps

Stap 7 – Installeer SSL

Om een SSL certificaat te installeren met Let’s Encrypt, moeten we het Certbot gereedschap downloaden. We zullen daarvoor het Snapd package installer gebruiken.

Installeer het Snapd installatieprogramma.

$ sudo apt install snapd

Zorg ervoor dat je versie van Snapd up to date is.

$ sudo snap install core && sudo snap refresh core

Installeer Certbot.

$ sudo snap install --classic certbot

Gebruik het volgende commando om ervoor te zorgen dat het Certbot commando kan worden uitgevoerd door een symbolische link te maken naar de /usr/bin directory.

$ sudo ln -s /snap/bin/certbot /usr/bin/certbot

Genereer een SSL certificaat.

$ sudo certbot certonly --standalone --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m [email protected] -d outline.example.com

Het bovenstaande commando downloadt een certificaat naar de /etc/letsencrypt/live/outline.example.com directory op je server.

Genereer een Diffie-Hellman groepscertificaat.

$ sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

Maak een uitdagende webroot directory voor Let’s Encrypt auto-renewal.

$ sudo mkdir -p /var/lib/letsencrypt

Maak een Cron Job om de SSL te vernieuwen. Deze zal elke dag lopen om het certificaat te controleren en zo nodig te vernieuwen. Maak daarvoor eerst het bestand /etc/cron.daily/certbot-renew en open het om te bewerken.

$ sudo nano /etc/cron.daily/certbot-renew

Plak er de volgende code in.

#!/bin/sh
certbot renew --cert-name outline.example.com --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"

Sla het bestand op door op Ctrl + X te drukken en Y in te voeren als daarom gevraagd wordt.

Verander de permissies op het taakbestand om het uitvoerbaar te maken.

$ sudo chmod +x /etc/cron.daily/certbot-renew

Stap 8 – Installeer Nginx

Ubuntu wordt geleverd met een oudere versie van Nginx. Je moet de officiële Nginx repository downloaden om de nieuwste versie te installeren.

Importeer de ondertekeningssleutel van Nginx.

$ curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
	| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

Voeg de repository voor de stabiele versie van Nginx toe.

$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \
http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list

Werk de systeem repositories bij.

$ sudo apt update

Installeer Nginx.

$ sudo apt install nginx

Verifieer de installatie.

$ nginx -v
nginx version: nginx/1.20.2

Schakel de Nginx dienst in.

$ sudo systemctl enable nginx

Stap 9 – Configureer Nginx

Tot nu toe draait Shlink op het lokale systeem via poort 8080. We zullen Nginx gebruiken om als een omgekeerde proxy op zijn domein te draaien.

Maak een configuratiebestand voor de Shlink server in de map /etc/nginx/conf.d.

$ sudo nano /etc/nginx/conf.d/outline.conf

Plak er de volgende code in.

server {
        server_name outline.example.com;

        listen 443 ssl http2;
        listen [::]:443 ssl http2;

        access_log /var/log/nginx/outline.access.log;
        error_log /var/log/nginx/outline.error.log;

        ssl_certificate /etc/letsencrypt/live/outline.example.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/outline.example.com/privkey.pem;
        ssl_trusted_certificate /etc/letsencrypt/live/outline.example.com/chain.pem;
        ssl_session_timeout 1d;
        ssl_session_cache shared:MozSSL:10m;
        ssl_session_tickets off;

        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;

        ssl_stapling on;
        ssl_stapling_verify on;
        ssl_dhparam /etc/ssl/certs/dhparam.pem;
 
        location / {
                proxy_pass http://localhost:3000;
                
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "Upgrade";
                proxy_set_header Host $host;
        
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header Host $host;
                proxy_set_header Host $http_host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Scheme $scheme;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_redirect off;
        }
}

## HTTPS Redirect
server {
        listen 80; 
        listen [::]:80;
        server_name outline.example.com;
        return 301 https://$host$request_uri;
}

Als je klaar bent, sla je het bestand op door op Ctrl + X te drukken en Y in te voeren als daarom gevraagd wordt.

Open het bestand /etc/nginx/nginx.conf om het te bewerken.

$ sudo nano /etc/nginx/nginx.conf

Voeg de volgende regel toe vóór de regel include /etc/nginx/conf.d/*.conf;.

server_names_hash_bucket_size  64;

Sla het bestand op door op Ctrl + X te drukken en Y in te voeren als daarom wordt gevraagd. Valideer Nginx opnieuw.

Controleer de syntaxis van het Nginx configuratiebestand.

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Start de Nginx server.

$ sudo systemctl start nginx

Stap 10 – Toegangsschema

Start het domein https://outline.example.com in je browser, en je wordt begroet met de volgende pagina.

Outline Wiki login pagina

Klik op de knop Doorgaan met Slack om in te loggen met Slack en je werkruimte te verbinden.

Schets Wiki Slack Autorisatie

Eenmaal ingelogd opent de Outline homepage, en kun je ermee aan de slag.

Outline Wiki Home

Met de Outline App voor Slack kun je de link naar elk document zoeken en plakken vanuit je werkruimte. Open daartoe je slack werkruimte en typ /outline <searchterm> in de berichten en plaats ze.

Schets Wiki Slack App bericht

De app zoekt automatisch het document dat met de zoekterm te maken heeft en post het in je berichten.

Schets Wiki Slack App Demo

Stap 11 – Outline bijwerken

Om de Outline wiki bij te werken, voer je de volgende commando’s uit. Het eerste commando sluit af en verwijdert de containers. Het tweede trekt de nieuwste versie van Docker images voor Outline en andere hulpmiddelen. Je kunt dezelfde commando’s uitvoeren als je wijzigingen moet aanbrengen in het Docker compose bestand of het environment bestand.

$ docker-compose down --remove-orphans
$ docker-compose pull 

Voer het volgende commando uit om de database te upgraden.

$ docker-compose run --rm outline yarn db:migrate --env=production-ssl-disabled

Start de nieuwe container met verse images terwijl je gegevens intact blijven.

$ docker-compose up -d

Conclusie

Dit beëindigt onze zelfstudie over het installeren van Outline Knowledgebase Wiki op een Ubuntu 20.04 server met Docker. Als je meer wilt leren over Outline, kun je de officiële documentatie volgen. Als je vragen hebt, stel ze dan in de opmerkingen hieronder.