homelab

Hoste deine eigen Knowledge Base! | Outline

jusec

• 7 min read
Hoste deine eigen Knowledge Base! | Outline

Übersicht

Ich war lange Zeit ein großer Fan von dem Knowledge Base Tool Notion. Was mich allerdings immer gestört hat, war die nicht vorhandene Möglichkeit, Notion selber zu Hosten um die Daten kontrolliert selber zu Besitzen.

Langezeit habe ich nach einem Tool gesucht, was beides kombiniert. Die Funktionalität, Einfachheit und das Design von Notion zum Dokumentieren und die Möglichkeit das ganze selber Zuhause zu hosten.

Vor einer weile wurde ich fündig. Ich habe seit ca. 1 Jahr eine produktive Instanz von Outline laufen und dokumentiere dort alles für mein Homelab und co.

Mein Fazit nach einem Jahr? Ich bin super zufrieden und endlich glücklich, dass perfekte Tool gefunden zu haben, daher richten wir das ganze heute einmal gemeinsam ein!

Das passende Video wie immer hier: https://youtu.be/jTj5O0oeGow

Setup

Auch für Outline nutzen wir wieder Docker und integrieren das Tool in unser Homelab, indem wir es über unseren Nginx Proxy Manager erreichbar machen.

Docker Compose

Als erstes passen wir die Compose Datei für Outline auf unsere Bedürfnisse an. Dafür passen wir auch hier wieder einige Zeilen an. Wir entfernen die exposed Ports der einzelnen Container, vergeben Namen, fügen ein internes und das reverse-proxy Netzwerk hinzu und vergeben Logindaten für die Postgresdatenbank.

Ich empfehle dringend einen Tag für die PostgreSQL-Version zu nehmen, da dies bei einem Upgrade sonst zu Datenbankproblemen führen kann.

Wenn wir das gemacht haben, sieht unsere Compose ungefähr so aus:

services:
  outline:
    image: docker.getoutline.com/outlinewiki/outline:latest
    container_name: outline-main
    env_file: .env
    #ports:
    #  - "3000:3000"
    volumes:
      - storage-data:/var/lib/outline/data
    depends_on:
      - postgres
      - redis
    networks:
      - reverse-proxy
      - outline-internal
  redis:
    image: redis
    container_name: outline-redis
    env_file: .env
    #ports:
    #  - 6379:6379
    volumes:
      - ./redis.conf:/redis.conf
    command:
      - redis-server
      - /redis.conf
    healthcheck:
      test:
        - CMD
        - redis-cli
        - ping
      interval: 10s
      timeout: 30s
      retries: 3
    networks:
      - outline-internal
  postgres:
    image: postgres:16.4-bullseye
    container_name: outline-postgres
    env_file: .env
    #ports:
    #  - "5432:5432"
    volumes:
      - database-data:/var/lib/postgresql/data
    healthcheck:
      test:
        - CMD
        - pg_isready
        - -d
        - outline
        - -U
        - user
      interval: 30s
      timeout: 20s
      retries: 3
    environment:
      POSTGRES_USER: <username>
      POSTGRES_PASSWORD: <password> (nehmt am besten keine Sonderzeichen, dass kann zu problemen führen)
      POSTGRES_DB: outline
    networks:
      - outline-internal
volumes:
  https-portal-data: 
  storage-data: 
  database-data: 
networks:
  outline-internal:
  reverse-proxy:
    external: true

.env File

Die eigentliche Konfiguration nehmen wir in der .env Datei vor. Es sieht im ersten Moment recht viel aus, allerdings sind die anzupassenden Variablen relativ gering. eine genauere Erklärung erhaltet ihr im oben verlinkten Video. Ich habe alle Zeilen, welche änderungsbedarf haben gekennzeichnet (<>).

Was wir vor allem brauchen ist eine Authentifizierungsmethode. Leider funktioniert hier kein einfaches User erstellen. Wir benötigen einen Identity Provider. Diesen können wir ebenfalls selber Hosten, siehe Authentik.

Nun müssen wir, in meinem Fall in Authentik, eine entsprechende Anwendung für Outline konfigurieren, um die OIDC Daten eintragen und uns später darüber Authentifizieren zu können.

Authentik

In Authentik können wir über den Wizard im Reiter Anwendungen → Anwendungen eine Kombination aus Provider und Anwendung für Outline erstellen.

wizard
wizard
  1. Als erstes vergeben wir einen Namen für die Anwendung und hinterlegen die URL, die wir später für Outline nutzen wollen.
create Application
create application
  1. Als nächstes wählen wir OAuth2/OIDC als Anbietertyp aus.
provider
provider
  1. Jetzt wählen wir den Authentifizierungs- und Autorisierungsablauf, tragen die Redirect URI ein und notieren uns die Client-ID und das Secret für die ersten beiden Variablen.
create
create
redirect uri
redirect uri
  1. Wenn wir jetzt im Tab Anwendung → Anbieter auf den neu erstellten Anbieter gehen, sehen wir Rechts alle restlichen URLs, die wir für das .env File brauchen.
URLs for env
URLs for env

Fertig. Damit ist für die Authentifizierung gesorgt. Wir haben nun alles nötige im .env File angepasst und können fortfahren. Unten findet Ihr nochmal das fertige File. Alle Einträge mit <> müsst ihr entsprechend anpassen.

Fertige .env zum anpassen

# –––––––––––––––– REQUIRED ––––––––––––––––
NODE_ENV=production

# Generate a hex-encoded 32-byte random key. You should use `openssl rand -hex 32`
# in your terminal to generate a random value.
SECRET_KEY=<Key mit befehl oben generieren>

# Generate a unique random key. The format is not important but you could still use
# `openssl rand -hex 32` in your terminal to produce this.
UTILS_SECRET=<Key mit befehl oben generieren>

# For production point these at your databases, in development the default
# should work out of the box.
DATABASE_URL=postgres://<user-von-compose>:<pass-von-compose>@outline-postgres:5432/outline
DATABASE_CONNECTION_POOL_MIN=
DATABASE_CONNECTION_POOL_MAX=
# Uncomment this to disable SSL for connecting to Postgres
PGSSLMODE=disable

# For redis you can either specify an ioredis compatible url like this
REDIS_URL=redis://outline-redis:6379
# or alternatively, if you would like to provide additional connection options,
# use a base64 encoded JSON connection option object. Refer to the ioredis documentation
# for a list of available options.
# Example: Use Redis Sentinel for high availability
# {"sentinels":[{"host":"sentinel-0","port":26379},{"host":"sentinel-1","port":26379}],"name":"mymaster"}
# REDIS_URL=ioredis://eyJzZW50aW5lbHMiOlt7Imhvc3QiOiJzZW50aW5lbC0wIiwicG9ydCI6MjYzNzl9LHsiaG9zdCI6InNlbnRpbmVsLTEiLCJwb3J0IjoyNjM3OX1dLCJuYW1lIjoibXltYXN0ZXIifQ==

# URL should point to the fully qualified, publicly accessible URL. If using a
# proxy the port in URL and PORT may be different.
URL=https://<wiki.example.com>
PORT=3000

# See [documentation](docs/SERVICES.md) on running a separate collaboration
# server, for normal operation this does not need to be set.
COLLABORATION_URL=

# Specify what storage system to use. Possible value is one of "s3" or "local".
# For "local", the avatar images and document attachments will be saved on local disk. 
FILE_STORAGE=local

# If "local" is configured for FILE_STORAGE above, then this sets the parent directory under
# which all attachments/images go. Make sure that the process has permissions to create
# this path and also to write files to it.
FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data

# Maximum allowed size for the uploaded attachment.
FILE_STORAGE_UPLOAD_MAX_SIZE=262144000

# Override the maximum size of document imports, generally this should be lower
# than the document attachment maximum size.
FILE_STORAGE_IMPORT_MAX_SIZE=

# Override the maximum size of workspace imports, these can be especially large
# and the files are temporary being automatically deleted after a period of time.
FILE_STORAGE_WORKSPACE_IMPORT_MAX_SIZE=


# –––––––––––––– AUTHENTICATION ––––––––––––––

# Third party signin credentials, at least ONE OF EITHER Google, Slack,
# or Microsoft is required for a working installation or you'll have no sign-in
# options.

# To configure generic OIDC auth, you'll need some kind of identity provider.
# See documentation for whichever IdP you use to acquire the following info:
# Redirect URI is https://<URL>/auth/oidc.callback
OIDC_CLIENT_ID=<Authentik Sektion>
OIDC_CLIENT_SECRET=<Authentik Sektion>
OIDC_AUTH_URI=<Authentik Sektion>
OIDC_TOKEN_URI=<Authentik Sektion>
OIDC_USERINFO_URI=<Authentik Sektion>
OIDC_LOGOUT_URI=<Authentik Sektion>

# Specify which claims to derive user information from
# Supports any valid JSON path with the JWT payload
OIDC_USERNAME_CLAIM=preferred_username

# Display name for OIDC authentication
OIDC_DISPLAY_NAME=Authentik

# Space separated auth scopes.
OIDC_SCOPES=openid profile email

# –––––––––––––––– OPTIONAL ––––––––––––––––

# Auto-redirect to https in production. The default is true but you may set to
# false if you can be sure that SSL is terminated at an external loadbalancer.
FORCE_HTTPS=false

# Have the installation check for updates by sending anonymized statistics to
# the maintainers
ENABLE_UPDATES=true

# How many processes should be spawned. As a reasonable rule divide your servers
# available memory by 512 for a rough estimate
WEB_CONCURRENCY=1

# You can remove this line if your reverse proxy already logs incoming http
# requests and this ends up being duplicative
DEBUG=http

# Configure lowest severity level for server logs. Should be one of
# error, warn, info, http, verbose, debug and silly
LOG_LEVEL=info

# To support sending outgoing transactional emails such as "document updated" or
# "you've been invited" you'll need to provide authentication for an SMTP server
# Kann bei bedarf eingerichtet werden.
SMTP_HOST=
SMTP_PORT=
SMTP_USERNAME=
SMTP_PASSWORD=
SMTP_FROM_EMAIL=
SMTP_REPLY_EMAIL=
SMTP_TLS_CIPHERS=
SMTP_SECURE=true

# The default interface language. See translate.getoutline.com for a list of
# available language codes and their rough percentage translated.
DEFAULT_LANGUAGE=de_DE

# Optionally enable rate limiter at application web server
RATE_LIMITER_ENABLED=true

# Configure default throttling parameters for rate limiter
RATE_LIMITER_REQUESTS=1000
RATE_LIMITER_DURATION_WINDOW=60

SSL Zertifikat und URL - Nginx Proxy Manager

Die Container sind gestartet und initialisieren sich. Nutzen wir den Moment um die URL für Outline im Nginx Proxy Manager zu hinterlegen. Wir erstellen einen neuen Host und nehmen hier den Namen vom “main” Container und den Port 3000

Jetzt wählen wir noch unser SSL Zertifikat und speichern das ganze.

Outline

Das war auch schon alles. Wir können uns jetzt über die ausgesuchte URL bei Outline anmelden und loslegen.

Outline

Tipps & Tricks

Wir haben nun eine funktionierende Instanz von Outline und können starten. Ich habe hier noch ein paar Tipps und Tricks zusammen geschrieben, was ich in meinem Outline konfiguriert habe und wie ich es nutze.

Benutzen von Outline

Outline hat super viele coole Funktionen. Eine komplette Übersicht findet Ihr hier.

Die meisten Funktionen erhaltet ihr aber auch, wenn ihr in einem neuen Dokument das Symbol / verwendet.

/
the / command

Sortierung

Ich mag die Möglichkeiten von Outline zur Sortierung sehr. Ich habe gerne alles Ästhetisch geordnet und diese Freiheit gibt Outline mir. Größere Überthemen sortiere ich in Collectionen in einer Collection können weitere Unterreiter erstellt werden.

Mein Highlight sind die Emojis und co. die genutzt werden können um das ganze ansehnlich zu gestalten. Hier ein Beispiel für meine Sektion zu den letzten Posts:

sortierung
Sortierung

Bearbeiten

Einer der ersten Haken die ich gesetzt habe, war unter Funktionen die “Getrennte Bearbeitung”. Das sorgt dafür, dass vor dem Bearbeiten eines Beitrags erst aktiv “Bearbeiten” geklickt werden muss. Das bewahrt mich davor, beim durchscrollen aus versehen etwas zu verändern. Für manche ist es eventuell aber auch einfach nur umständlicher.

getrenntes Bearbeiten
getrennte Bearbeitung

Design und Aussehen

Unter dem Reiter Details könnt ihr eure Outline Instanz einen ganz eigenen Look verpassen, mit eigenem Logo, Namen und Design.

Design
Design