소프트웨어

홈랩을 구성하는 소프트웨어, self-hosted 앱 및 설정

pocket-id
traefik
pangolin
Obsidian
uptime kuma

pocket-id

간단한 OIDC (open id connect) provider입니다. 가장 큰 특징은 passkey만 지원한다는 것인데, 이점이 약간의 호불호가 있긴 합니다.

site : https://pocket-id.org/
git : https://github.com/pocket-id/pocket-id

passkey에 관해서는 따로 이야기해야 할 정도이지만 쉽게 말하면 기존과 같은 패스워드 기반이 아니라, 특정 보안 하드웨어 또는 생체 인식 등으로 인증을 대신하는 것입니다.

저같은 경우 제 노트북과 데스크탑에 하드웨어 키, 그리고 vaultwarden에 패스키를 등록했고 이를 인증에 이용하도록 세팅했습니다.

install

기본적으로 docker compose 를 추천하고 있습니다.

# curl -o docker-compose.yml https://raw.githubusercontent.com/pocket-id/pocket-id/main/docker-compose.yml
# curl -o .env https://raw.githubusercontent.com/pocket-id/pocket-id/main/.env.example

curl 명령으로 기본적인 템플릿을 다운로드받아서, 자신의 환경에 맞게 수정해주면 됩니다.

services:
  pocket-id:
    image: ghcr.io/pocket-id/pocket-id:v1
    restart: unless-stopped
    env_file: .env
    ports:
      - 1411:1411
    volumes:
      - "./data:/app/data"
    # Optional healthcheck
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.pocket-id.rule=Host(`YOUR_OIDC_DOMAIN`)"
      - "traefik.http.routers.pocket-id.entrypoints=websecure"
      - "traefik.http.routers.pocket-id.tls=true"
      - "traefik.http.routers.pocket-id.tls.certresolver=letsencrypt"
      - "traefik.http.services.pocket-id.loadbalancer.server.port=1411"
    networks:
      - proxy
    healthcheck:
      test: [ "CMD", "/app/pocket-id", "healthcheck" ]
      interval: 1m30s
      timeout: 5s
      retries: 2
      start_period: 10s

networks:
  proxy:
    external: true

.env 파일도 자신의 환경에 맞게 수정하면 됩니다.

# See the documentation for more information: https://pocket-id.org/docs/configuration/environment-variables

# These variables must be configured for your deployment:
APP_URL=https://auth.your.domain

# Encryption key (choose one method):
# Method 1: Direct key (simple but less secure)
# Generate with: openssl rand -base64 32
ENCRYPTION_KEY=...
# Method 2: File-based key (recommended)
# Put the base64 key in a file and point to it here.
# ENCRYPTION_KEY_FILE=/path/to/encryption_key

# These variables are optional but recommended to review:
TRUST_PROXY=true
MAXMIND_LICENSE_KEY=...
PUID=1000
PGID=1000

TRUST_PROXY 옵션은 해당 docker가 리버스프록시 뒤에 있을 경우 설정해주면 됩니다. MAXMIND_LICENSE_KEY 는 audit log에서 접속된 IP의 지리적 정보를 취득하는데 이용합니다. 만약 키가 없을 경우 ip의 위치는 알수 없음으로 표시됩니다.

개별 서비스에 pocket-id를 OIDC로 등록하는 방법은 어느정도 공통적인 매뉴얼이 있으나, pocket-id docs에서 잘 알려진 앱들의 개별적인 세팅 방법도 소개하고 있다. https://pocket-id.org/docs/client-examples

traefik

간단히 "리버스 프록시"인데, 정말 많은 기능을 가지고 있습니다. 그만큼 쓰기는 좀 어렵긴 하네요.

docker, k8s 등의 컨테이너 환경과 연동해서 서비스를 자동으로 도메인과 연결해서 외부에 노출시켜 줍니다.
1. docker 를 사용할 경우 설정에서 label을 붙이면 traefik이 자동으로 인식하여 라우팅해줍니다.
자동으로 letsencrypt의 인증서 발급 및 갱신 (with CloudFlare)
로드밸런싱 및 부하 분산
여러 미들웨어를 지원

가장 큰 장점이라면 해당 서버의 docker, k8s 의 컨테이너에서 label을 인식해서 자동으로 해당 도메인으로 라우팅해준다는 점인데, 제가 마지막으로 찾아본 바로는 같은 서버에서만 적용됩니다. 다른 서버로 라우팅하려면 dynamic config를 사용해야 하는데, 이건 별도의 yml 파일을 만들어줘야 해서 오히려 좀 불편한 부분이었네요.

회사는 프랑스 회사이고, 이름도 영어의 traffic을 프랑스식으로 적은 것이라고 합니다. (근데 프랑스어로 교통량은 다른 단어입니다 ㅎㅎ)

pangolin

또다른 리버스 프록시인 pangolin 입니다. 리버스 프록시이면서 newt라는 wireguard 기반의 VPN 클라이언트가 포함되어 있어서 마치 cloudflare 의 터널 서비스를 연상하게 합니다. 내부적으로는 pangolin UI + traefik + newt 로 구성되어 있습니다.

리버스 프록시와 VPN의 결합 솔루션
기본적인 SSO 기능이 내장되어 있으며, 별도의 OIDC provider 등을 추가하여 인증할 수도 있다.
CrowdSec 연동

pangolin 내부에 traefik 이 내장되어 있기 때문에 엄밀하게 말하면 pangolin은 traefik의 wrapper라고 해도 과언은 아니고, 더 가볍게 쓰고 싶다면 traefik을 쓰는게 정답일 수도 있습니다. traefik + authentic 등으로 구현한다면 거의 같은 기능을 구현할 수도 있을것 같습니다. 하지만 편리하게 쓸 수 있는 UI 가 큰 장점인 것 같습니다.

다만, Traefik과 몇가지 다른점이 있습니다.

traefik의 경우 k8s, docker의 label 기반으로 자동으로 도메인으로 연결해주는 특징이 있어서 같은 서버에 있는 컨테이너를 도메인과 연결하기 쉽지만 다른 서버의 컨테이너는 따로 dynamic config 파일을 작성해야 하기 때문에 (file provider) 불편함이 있다.
pangolin은 내부/외부 구분없이 config 추가해야 하지만, (traefik의 dynamic config 같은) 텍스트 파일 직접 편집이 아닌 UI로 해결이 가능하다.

개인적으로는 외부 VM에 리버스 프록시가 있고 여기에서 집의 로컬 네트워크 내의 서버로 연결해야 하기 때문에 거의 dynamic config를 작성해야 했기 때문에 이를 UI에서 처리할 수 있다면 더 편리한 것이 됩니다.

추가로 newt 가 vpn이므로 tailscale 이 필요 없습니다. ㅎ

현재는 해당 프로젝트도 유료 기능을 준비하고 있습니다. 기업용 기능으로 지원되는 기능은 다음과 같습니다.

티켓 기반 지원
자동 IdP 사용자 프로비저닝
자동화를 위한 강력한 통합 API

하지만 위의 기능은 일반적인 homelab에서는 크게 필요하지 않고 여전히 커뮤니티 에디션으로도 개발이 잘 되고 있는 중입니다. 지금은 유료 기능과 별도로 supporter key 라는 기능이 있어서 기부를 받는 기능 정도만 있습니다.

사람에 따라서는 이러한 유료 기능, 기부 기능 추가가 반갑게 보이지 않겠지만, 글쎄요... pangolin은 아주 좋은 소프트웨어임엔 틀림없는 것 같고, 이제까지 오픈소스가 번아웃으로 없어지거나 수익이 안되서 개발 중단되거나 하는 걸 너무 많이 보고 오픈소스의 연속성에 관해 논의가 많이 되는 시점인데 이런 얘기도 못하게 하면... 글쎄요...

https://www.reddit.com/r/selfhosted/comments/1ke5jhy/too_soon_to_make_it_paid_pangolin/?tl=ko

몇가지 운영 매뉴얼

newt를 업데이트할 때 docker로 설치했을때와 service(binary)로 설치했을 때 방법이 다름.

docker - 간단하게 docker compose pull 만 하면 됨
service (binary) - cli에서 curl -fsSL https://static.pangolin.net/get-newt.sh | bash 명령어로 재설치하는 형식으로 진행. 이후에는 systemctl restart newt.service 사용하여 활성화

Obsidian

옵시디안은 markdown 문법으로 작성할 수 있는 크로스 플랫폼 노트 앱입니다. 즉 표준인 마크다운 문법으로 거의 웬만한 플랫폼에 앱이 있는 아주 범용성 있는 노트입니다.

여러 노트 앱들과 차별화되는 높은 범용성 - markdown, cross platform
무료 (유료 기능으로 sync, publish가 있다)
제텔카스텐 시스템 - 노션 및 롬리서치와 비슷한 메모 시스템
다양한 플러그인
완전히 로컬에만 저장 가능 (월 4$에 동기화 지원)

여타 앱과 다른 특이사항으로 완전히 로컬에만 파일을 저장한다는 부분이 있는데, 장점이라고도 볼수 있지만 요즘 같은 시대엔 단점일 수밖에 없다.

하지만 이 동기화도 self-hosted로 해결할 수 있는 방법이 있다. 플러그인 중 self-hosted livesync 를 설치하고 db를 apache couchDB를 운영하면 된다.

준비사항

couchDB LXC 설치 (on proxmox). proxmox script로 couchDB LXC 설치 (설치 주소는 127.0.0.1:5984)

pangolin에서 reverse proxy로 도메인으로 연결 ( https://couchdb-sample.your.domain -> 127.0.0.1:5984)

해당 서비스는 인증을 해야 이용할 수 있기 때문에 기본 상태확인 url을 아무것도 설정하지 않으면 비정상이 뜨면서 서비스가 연결되지 않는다. 그래서 기본적으로 상태 확인을 끄거나 healthcheck url 경로를 /_up 을 사용해야 한다.

다만 이후 설정할 livesync plugin 을 위한 DB 설정에서 require_valid_user: true 속성을 추가해야 하는데 healthcheck url까지 인증이 걸려 사이트가 뜨지 않는 문제가 발생할 수 있다. health check에 사용하는 url에는 인증을 제외하는 require_valid_user_except_for_up: true 옵션을 추가하면 된다.

준비한 도메인으로 접속할 때 json 응답 또는 http login dialog가 뜨면 성공.

이후엔 https://www.reddit.com/r/selfhosted/comments/1eo7knj/guide_obsidian_with_free_selfhosted_instant_sync/?tl=ko 이 문서를 따라서 db를 세팅하고 obsidian app과 연결하면 끝

uptime kuma

간단한 시스템 모니터링 소프트웨어. 보통 모니터링으로 유명한 건 prometheus + grafana 조합으로 어느정도 표준화되어 있지만, 간단하게 시스템 상황만 모니터링하고 알림을 받기에는 uptime kuma도 꽤 괜찮은 솔루션이다.

https://github.com/louislam/uptime-kuma

쉬운 설치 및 사용: 복잡한 설정 없이 빠르게 구축하고 직관적인 대시보드에서 모니터링할 수 있습니다.
다양한 모니터링 방식: HTTP/HTTPS, TCP, Ping, DNS, Keyword 등 여러 프로토콜로 서비스 상태를 점검합니다.
알림 연동: 서비스 장애 시 슬랙(Slack), 디스코드(Discord), 텔레그램(Telegram), 이메일 등으로 즉시 알림을 받을 수 있습니다.
SSL 인증서 관리: SSL 인증서 만료일을 미리 알려주어 보안 관리를 돕습니다.
자체 호스팅 (Self-Hosted): 직접 서버에 설치하여 운영하므로 데이터 프라이버시를 지키며 무료로 사용할 수 있습니다.
간편한 대시보드: 깔끔하고 사용자 친화적인 UI로 서비스 상태를 한눈에 파악할 수 있습니다.
모바일 앱 지원: Uptime Kuma Manager 앱 등을 통해 스마트폰에서도 쉽게 모니터링할 수 있습니다.

간단하게 docker compose를 다음과 같이 작성하면 된다. (주석 부분은 traefik을 사용했을때 쓰는 부분)

services:
  uptime-kuma:
    container_name: uptime-kuma
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      - "3001:3001"
    environment:
      - PUID=1000
      - PGID=1000
    #labels:
    #  - "traefik.enable=true"
    #  - "traefik.http.routers.uptimekuma.rule=Host(`monitor.neue.nz`)"
    #  - "traefik.http.routers.uptimekuma.entrypoints=websecure"
    #  - "traefik.http.routers.uptimekuma.tls=true"
    #  - "traefik.http.routers.uptimekuma.tls.certresolver=letsencrypt"
    #  - "traefik.http.services.uptimekuma.loadbalancer.server.port=3001"
    #networks:
    #  - proxy

#networks:
#  proxy:
#    external: true

대부분의 사이트 추가, 알림 설정은 앱을 구동하고 적용하면 된다.

기본적으로 admin 은 로그인 후 대시보드에서 사이트 추가, 설정 작업을 할 수 있고,

매번 로그인하는 것도 귀찮기 때문에 (보통은 로그인을 아예 비활성화하고 traefik에서 OIDC middleware를 사용하여 공통으로 로그인하게 구현) 로그인하지 않은 상태에서 status 페이지를 볼 수 있게 설정할 수도 있다.

간단한 모니터링 소프트웨어라고 했지만, 굉장히 많은 설정으로 사이트의 상태 체크가 가능하다. login 하지 않으면 볼 수 없는 사이트 등도 인증 설정을 해서 로그인 후의 사이트 모니터링도 가능

공통 알림도 설정할 수 있다. 여기서는 현재 사용하는 gotify만 설정했지만 꽤 다양한 옵션이 있다.

대시보드 디자인이 개인 취향에 맞는다.
터미널에서 일일히 docker compose, config 파일 등을 편집하는 것은 싫고 웹에서 설정하는 게 취향이다.
각 서버마다 prometheus exporter 등을 설치해서 관리하는 것, 복잡한 grafana 대시보드 등의 설정이 크게 필요하지 않다.

이정도라면 uptime kuma는 기본적인 홈랩 모니터링 소프트웨어로 충분하다.