HedgeDoc 설치기: 마크다운 문서, 이제 어디서든 열린다

안녕하세요, Mark입니다.

오늘은 제가 꽤 오랫동안 고민하던 문제를 해결해준 프로그램을 소개합니다. 거창한 문제가 아니라, 아주 현실적인 문제였어요.

“회사에서 쓰던 문서 초안, 집에서 이어서 쓰고 싶다.”

📝 마크다운 편집기, 이미 두 개나 쓰고 있는데요?

사실 저는 마크다운 편집기를 이미 두 개나 쓰고 있습니다.

옵시디언(Obsidian)과 Joplin이에요.

옵시디언은 원래 무료로 싱크하려고 원드라이브, 구글 드라이브 등 여러 가지를 시도해봤는데, 속도도 느리고 데이터가 꼬이는 문제가 자꾸 생겼어요. 결국 유료 싱크로 갈아탔습니다. 깔끔하게 해결되긴 했는데, 앱 자체가 기능이 워낙 많아서 “간단하게 문서 하나 쓰고 싶다”는 용도에는 좀 과한 느낌이에요.

Joplin은 드롭박스로 싱크해서 잘 쓰고 있고, 가볍고 좋아요. 그런데 두 도구 모두 결정적인 단점이 하나 있습니다.

공유와 협업이 안 됩니다. 😅

🚪 현실적인 문제: 회사 문서가 집에서 안 열려요

제가 HedgeDoc를 찾게 된 직접적인 계기가 있어요.

회사에서 작업하던 문서 초안을 집에서 이어서 써야 할 때가 종종 있거든요. 그런데 회사 문서들은 보안 때문에 암호가 걸려있어서 집에 가져가면 안 열립니다. ㅎㅎ

그래서 초안 정도는 따로 관리할 공간이 필요했어요. 나중에는 팀원들이랑 같은 문서를 같이 편집하는 협업도 해볼 수 있고요.

이 조건을 정리하면 이렇습니다:

HedgeDoc이 딱 빈자리를 채워주는 느낌이었어요.

🧭 HedgeDoc이 뭔가요?

HedgeDoc은 웹 기반 마크다운 편집기입니다. 브라우저에서 열어서 바로 문서를 쓸 수 있어요.

가장 큰 특징은 실시간 협업이에요. 구글 독스처럼 여러 명이 같은 문서를 동시에 편집할 수 있습니다. 마크다운으로요.

그리고 링크 하나만 공유하면 상대방이 계정 없이도 문서를 볼 수 있어요. 팀원한테 “이 링크 열어봐”만 해도 되는 거죠.

📦 포테이너 스택으로 설치하기

HedgeDoc은 데이터베이스(PostgreSQL)와 앱, 두 개의 컨테이너로 구성됩니다.

포테이너 → Stacks → Add Stack에서 아래 내용을 붙여넣으세요.

version: '3'

services:
  database:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=hedgedoc
      - POSTGRES_PASSWORD=비밀번호
      - POSTGRES_DB=hedgedoc
    volumes:
      - hedgedoc_db:/var/lib/postgresql/data
    restart: always
  app:
    image: quay.io/hedgedoc/hedgedoc:1.10.8
    environment:
      - CMD_DB_URL=postgres://hedgedoc:비밀번호@database:5432/hedgedoc
      - CMD_DOMAIN=내도메인.duckdns.org
      - CMD_URL_ADDPORT=false
      - CMD_PROTOCOL_USESSL=true
      - CMD_ALLOW_ANONYMOUS=true
      - CMD_ALLOW_FREEURL=true
      - CMD_DEFAULT_PERMISSION=private
      - CMD_SESSION_SECRET=랜덤_문자열_입력
    volumes:
      - hedgedoc_uploads:/hedgedoc/public/uploads
    ports:
      - "3100:3000"
    depends_on:
      - database
    restart: always
volumes:
  hedgedoc_db:
  hedgedoc_uploads:

version: '3'

services:
  database:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=hedgedoc
      - POSTGRES_PASSWORD=비밀번호
      - POSTGRES_DB=hedgedoc
    volumes:
      - hedgedoc_db:/var/lib/postgresql/data
    restart: always
  app:
    image: quay.io/hedgedoc/hedgedoc:1.10.8
    environment:
      - CMD_DB_URL=postgres://hedgedoc:비밀번호@database:5432/hedgedoc
      - CMD_DOMAIN=내도메인.duckdns.org
      - CMD_URL_ADDPORT=false
      - CMD_PROTOCOL_USESSL=true
      - CMD_ALLOW_ANONYMOUS=true
      - CMD_ALLOW_FREEURL=true
      - CMD_DEFAULT_PERMISSION=private
      - CMD_SESSION_SECRET=랜덤_문자열_입력
    volumes:
      - hedgedoc_uploads:/hedgedoc/public/uploads
    ports:
      - "3100:3000"
    depends_on:
      - database
    restart: always
volumes:
  hedgedoc_db:
  hedgedoc_uploads:

주요 환경변수 설명:

💡 포트 번호가 3100인 이유: 기본값은 3000번인데, 제 서버에서 3000번은 Homepage 대시보드가 이미 쓰고 있거든요. 이렇게 포트 충돌이 나면 왼쪽 숫자(호스트 포트)만 바꿔주면 됩니다. 오른쪽(컨테이너 포트)은 그대로 3000이에요.

🔒 DuckDNS + NPM으로 도메인 연결하기

설치 후 IP:3100으로 접속하면 되긴 하는데, 그냥 쓰기엔 찜찜하죠. 도메인이랑 HTTPS를 붙여봅시다.

1단계: DuckDNS에서 서브도메인 생성

duckdns.org에 접속해서 원하는 이름으로 서브도메인을 하나 만들고, 서버 IP를 등록합니다.

2단계: NPM에서 프록시 호스트 추가

NPM(Nginx Proxy Manager) → Proxy Hosts → Add Proxy Host

SSL 탭에서 Let’s Encrypt 인증서를 발급받으면 HTTPS까지 한 번에 해결됩니다. 3편에서 설치한 NPM이 여기서 또 활약하네요 ㅎㅎ

🗺️ 실제로 어떻게 쓰나요?

지금은 주로 회사에서 작업하다 집에서 이어서 써야 하는 문서 초안 용도로 활용하고 있어요. 브라우저에서 바로 열리고, 마크다운으로 깔끔하게 작성되니까 딱 맞습니다.

나중에 팀원들이랑 같은 문서를 함께 편집할 일이 생기면, 링크 하나 공유하는 것만으로 바로 협업이 가능해요. 팀원이 따로 계정을 만들거나 프로그램을 설치할 필요가 없다는 게 가장 큰 장점이에요.

✅ 핵심 요약

마치며

옵시디언, Joplin, HedgeDoc — 세 도구가 이제 각자 역할을 나눠 갖게 됐어요.

• 옵시디언: 개인 지식 관리, 정리된 노트
• Joplin: 가벼운 메모, 드롭박스 싱크
• HedgeDoc: 문서 초안, 팀 협업

도구가 많아 보이지만 쓰임새가 다 다르다 보니 겹치는 느낌이 없어요. 이게 셀프호스팅의 묘미인 것 같습니다. 필요한 걸 골라서 올리면 되니까요 ㅎㅎ

Mark의 한마디: “회사 문서는 암호 걸려서 집에서 못 열고, 개인 편집기는 공유가 안 되고… 그 사이 어딘가에 딱 HedgeDoc이 있었습니다.”