Joplin Server Docker 설치 가이드: E2E 암호화 노트 앱 자체 호스팅 ⋆ Blog * JackerLab

Joplin은 Evernote의 강력한 오픈소스 대안입니다. E2E(종단간) 암호화를 지원하여 노트 데이터의 완전한 프라이버시를 보장합니다. Windows, macOS, Linux, Android, iOS 모든 플랫폼을 지원하며, Joplin Server를 자체 호스팅하면 여러 기기 간 안전한 동기화가 가능합니다. 마크다운 기반으로 노트를 작성하고, 할 일 관리, 태그, 노트북 구조까지 제공합니다.

Joplin 주요 특징

Joplin은 프라이버시와 사용성을 모두 갖춘 노트 앱입니다.

핵심 기능

E2E 암호화: AES-256 암호화로 노트 보호
마크다운 편집기: WYSIWYG 및 마크다운 뷰어
노트북/태그: 계층 구조와 태그로 체계적 정리
할 일 관리: 체크박스, 알람 기능
웹 클리퍼: 브라우저 확장으로 웹 페이지 저장
첨부 파일: 이미지, PDF, 오디오 등 첨부

Joplin Server 장점

셀프호스팅으로 데이터 완전 소유
다중 사용자 지원
공유 노트북 기능
빠른 동기화 속도
REST API 제공

사전 요구 사항

Docker 및 Docker Compose 설치
최소 1GB RAM
5GB 이상 저장 공간
도메인 (외부 접근 시)

Docker Compose로 Joplin Server 설치

기본 설치

# docker-compose.yml
services:
  db:
    image: postgres:16
    container_name: joplin-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: joplin
      POSTGRES_USER: joplin
      POSTGRES_PASSWORD: ${DB_PASSWORD:-joplin_secure_password}
    volumes:
      - joplin-db:/var/lib/postgresql/data
    networks:
      - joplin-net

  joplin:
    image: joplin/server:latest
    container_name: joplin-server
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "22300:22300"
    environment:
      - APP_PORT=22300
      - APP_BASE_URL=${APP_BASE_URL:-http://localhost:22300}
      - DB_CLIENT=pg
      - POSTGRES_HOST=db
      - POSTGRES_PORT=5432
      - POSTGRES_DATABASE=joplin
      - POSTGRES_USER=joplin
      - POSTGRES_PASSWORD=${DB_PASSWORD:-joplin_secure_password}
    networks:
      - joplin-net

volumes:
  joplin-db:

networks:
  joplin-net:
    driver: bridge

환경 변수 파일

# .env
DB_PASSWORD=your_secure_db_password
APP_BASE_URL=https://joplin.yourdomain.com

설치 및 실행

# 디렉토리 생성 및 이동
mkdir joplin-server && cd joplin-server

# docker-compose.yml 및 .env 파일 생성

# 컨테이너 실행
docker compose up -d

# 로그 확인
docker compose logs -f joplin

# 브라우저에서 접속
# http://localhost:22300
# 기본 로그인: admin@localhost / admin

초기 설정

1. 관리자 비밀번호 변경

http://localhost:22300 접속
admin@localhost / admin 으로 로그인
우측 상단 프로필 → Change Password
새 비밀번호 설정

2. 일반 사용자 생성

Admin → Users 이동
“Add user” 클릭
이메일, 이름, 비밀번호 입력
동기화용 계정으로 사용

Joplin 클라이언트 연결

데스크톱/모바일 앱 설정

Joplin 앱 설치 (Windows/macOS/Linux/Android/iOS)
도구 → 옵션 → 동기화 이동
동기화 대상: Joplin Server 선택
설정:
- Joplin Server URL: https://joplin.yourdomain.com
- 이메일: 생성한 사용자 이메일
- 비밀번호: 사용자 비밀번호
“동기화 대상 확인” 클릭

E2E 암호화 활성화

도구 → 옵션 → 암호화 이동
“암호화 활성화” 클릭
마스터 비밀번호 설정 (분실 시 복구 불가!)
모든 기기에서 동일한 마스터 비밀번호 사용

고급 설정

프로덕션 환경 (HTTPS + 리버스 프록시)

# docker-compose.prod.yml
services:
  db:
    image: postgres:16
    container_name: joplin-db
    restart: always
    environment:
      POSTGRES_DB: joplin
      POSTGRES_USER: joplin
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - joplin-db:/var/lib/postgresql/data
    networks:
      - joplin-net

  joplin:
    image: joplin/server:latest
    container_name: joplin-server
    restart: always
    depends_on:
      - db
    expose:
      - "22300"
    environment:
      - APP_PORT=22300
      - APP_BASE_URL=${APP_BASE_URL}
      - DB_CLIENT=pg
      - POSTGRES_HOST=db
      - POSTGRES_PORT=5432
      - POSTGRES_DATABASE=joplin
      - POSTGRES_USER=joplin
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      # 메일 설정 (선택)
      - MAILER_ENABLED=1
      - MAILER_HOST=${MAIL_HOST}
      - MAILER_PORT=587
      - MAILER_SECURITY=starttls
      - MAILER_AUTH_USER=${MAIL_USER}
      - MAILER_AUTH_PASSWORD=${MAIL_PASSWORD}
      - MAILER_NOREPLY_NAME=Joplin
      - MAILER_NOREPLY_EMAIL=noreply@yourdomain.com
    networks:
      - joplin-net
      - traefik-public
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.joplin.rule=Host(`joplin.yourdomain.com`)"
      - "traefik.http.routers.joplin.entrypoints=websecure"
      - "traefik.http.routers.joplin.tls.certresolver=letsencrypt"
      - "traefik.http.services.joplin.loadbalancer.server.port=22300"

volumes:
  joplin-db:

networks:
  joplin-net:
    driver: bridge
  traefik-public:
    external: true

Nginx 리버스 프록시 설정

# /etc/nginx/conf.d/joplin.conf
server {
    listen 80;
    server_name joplin.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name joplin.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/joplin.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/joplin.yourdomain.com/privkey.pem;

    client_max_body_size 200M;

    location / {
        proxy_pass http://localhost:22300;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

파일시스템 스토리지 설정

대용량 첨부파일을 데이터베이스 외부에 저장:

# docker-compose.yml (joplin 서비스에 추가)
services:
  joplin:
    environment:
      - STORAGE_DRIVER=Type=Filesystem; Path=/data/joplin-storage
    volumes:
      - joplin-storage:/data/joplin-storage

volumes:
  joplin-storage:

관리 명령어

# 로그 확인
docker compose logs -f joplin

# 데이터베이스 백업
docker compose exec db pg_dump -U joplin joplin > backup_$(date +%Y%m%d).sql

# 데이터베이스 복원
docker compose exec -T db psql -U joplin joplin < backup.sql

# 컨테이너 재시작
docker compose restart joplin

# 업데이트
docker compose pull
docker compose up -d

환경 변수 전체 목록

변수	설명	기본값
APP_PORT	서버 포트	22300
APP_BASE_URL	외부 접근 URL	–
DB_CLIENT	DB 타입 (pg/sqlite)	sqlite
POSTGRES_HOST	PostgreSQL 호스트	–
POSTGRES_PORT	PostgreSQL 포트	5432
POSTGRES_DATABASE	DB 이름	–
POSTGRES_USER	DB 사용자	–
POSTGRES_PASSWORD	DB 비밀번호	–
STORAGE_DRIVER	스토리지 드라이버	Database
MAILER_ENABLED	메일 활성화	0
MAILER_HOST	SMTP 호스트	–

문제 해결

“Not a valid URL” 오류

Joplin 앱에서 연결 시 URL 앞에 https://를 포함해야 합니다.

동기화 실패

APP_BASE_URL이 실제 접근 URL과 일치하는지 확인
방화벽에서 포트 22300 허용 확인
리버스 프록시 설정 확인

권한 오류

# 볼륨 권한 확인
docker compose exec joplin ls -la /data

마무리

Joplin Server를 자체 호스팅하면 Evernote나 Notion 같은 상용 서비스 없이도 완전한 노트 동기화 환경을 구축할 수 있습니다. E2E 암호화로 프라이버시를 보장하고, 마크다운 기반으로 이식성 높은 노트를 관리할 수 있습니다. Docker를 통해 쉽게 배포하고, 서버가 오프라인이 되더라도 로컬에 저장된 노트는 계속 사용 가능합니다.

참고 링크

공식 사이트: https://joplinapp.org
GitHub: https://github.com/laurent22/joplin
Docker Hub: https://hub.docker.com/r/joplin/server
문서: https://joplinapp.org/help