How to Install CodiMD on Coolify

1. 개요 및 배경

과거 협업 및 개인 지식 관리용 마크다운 에디터로 널리 사용되던 HedgeDoc(구 CodiMD)의 설치 및 운영 환경을 재검토함. 과거 Synology NAS 환경에서 Docker를 통한 수동 배포 시 겪었던 복잡한 설정 과정(포트 포워딩, 역방향 프록시 설정 등)과 달리, 최근 주목받는 Self-hosted PaaS 솔루션인 Coolify를 통해 배포 효율성을 극대화할 수 있었음. 본 보고서에서는 Coolify를 이용한 CodiMD의 신속한 배포 과정, 필수 환경변수 설정, 그리고 보안 강화를 위한 후속 조치 방법을 상세히 기술함.

2. 솔루션 소개

2.1 CodiMD (HedgeDoc)

CodiMD는 실시간 협업이 가능한 웹 기반 마크다운 에디터임. HackMD의 오픈소스 버전에서 파생되었으며, 현재는 HedgeDoc이라는 명칭으로 프로젝트가 이관되었으나 여전히 CodiMD라는 명칭으로 널리 통용됨. 가볍고 빠르며, 수식 입력, 다이어그램(Mermaid), 프레젠테이션 모드 등을 지원하여 개발자 및 테크니컬 라이터에게 최적화된 도구임.

2.2 Coolify

'오픈소스 Vercel/Netlify'를 표방하는 Coolify는 복잡한 서버 관리 지식 없이도 Docker 컨테이너, 데이터베이스, 애플리케이션을 손쉽게 배포할 수 있게 해주는 도구임. SSL 인증서 자동 발급 및 리버스 프록시 설정이 자동화되어 있어 기존 NAS나 베어메탈 서버 관리의 난이도를 획기적으로 낮춤.

3. Coolify를 통한 설치 프로세스

Coolify 환경이 구축되어 있다는 전제하에 설치 과정은 매우 직관적임.

1. 서비스 검색 및 선택: Coolify 대시보드의 'Services' 탭에서 'Create New Service'를 선택 후 codimd를 검색함. 원클릭 설치 템플릿이 제공되므로 별도의 docker-compose.yml 작성 없이 진행 가능함.
2. 도메인 설정: 서비스가 배포될 서브도메인(예: md.example.com)을 입력함. Coolify는 설정된 도메인에 대해 자동으로 Let's Encrypt SSL 인증서를 요청하고 적용함.
3. 초기 배포 (Initial Deploy): 설정을 저장한 후 'Deploy' 버튼을 클릭함. 이 과정에서 필요한 Docker 이미지를 풀(Pull)하고, 데이터베이스(PostgreSQL 또는 MySQL) 컨테이너가 함께 생성됨.
4. 초기 구동 확인: 배포 로그에서 'Healthy' 상태가 확인되면 웹 브라우저를 통해 접속을 시도함.

4. 트러블 슈팅: 화면 깨짐 현상과 SSL 설정

설치 직후 웹페이지에 접속 시, CSS가 로드되지 않거나 화면 레이아웃이 깨지는 현상이 발생할 수 있음. 이는 리버스 프록시 환경에서 흔히 발생하는 'Mixed Content' 문제 혹은 애플리케이션이 자신이 SSL(HTTPS) 환경에서 구동되는지 인지하지 못해 발생하는 문제임.

4.1 원인 분석

Coolify는 앞단(Traefik 등)에서 HTTPS를 처리하고, 내부 컨테이너와는 HTTP로 통신함. CodiMD는 기본적으로 자신이 HTTP로 서빙된다고 판단하여 리소스 경로를 HTTP로 생성함. 브라우저는 보안상의 이유로 HTTPS 페이지 내의 HTTP 리소스 로딩을 차단하므로 화면이 깨지게 됨.

4.2 해결 방안 (환경변수 수정)

이를 해결하기 위해 애플리케이션에 강제로 SSL 사용을 명시해야 함.

1. Coolify 해당 서비스의 Environment Variables (환경변수) 설정 메뉴로 진입.
2. PROTOCOL_USESSL 키를 찾음.
3. 기본값 false를 **true**로 변경.
4. 설정 저장 후, 변경 사항 적용을 위해 컨테이너를 Reset(재시작) 함.

이 설정을 통해 CodiMD는 모든 리소스 링크를 HTTPS 프로토콜로 생성하게 되며, 화면 깨짐 현상이 즉시 해결됨.

5. 보안 강화: 외부 사용자 등록 차단

CodiMD는 기본적으로 누구나 이메일을 통해 가입할 수 있도록 설정되어 있음. 개인용 혹은 사내 팀용으로 운영할 경우, 불특정 다수의 가입은 스팸 문서 생성 및 서버 리소스 낭비로 이어질 수 있음. 따라서 초기 관리자 계정 생성 후에는 신규 가입을 차단하는 것이 권장됨.

5.1 설정 변경 절차

1. 환경변수 설정 메뉴 재진입.
2. CMD_ALLOW_EMAIL_REGISTER 키를 검색.
3. 기본값 true를 **false**로 변경.
4. 설정 저장 후 컨테이너 Reset(재시작).

5.2 적용 결과

위 설정 적용 시 로그인 화면에서 'Register(회원가입)' 버튼이 비활성화되거나 사라짐. 기존에 생성된 계정으로만 로그인이 가능해지며, 이를 통해 폐쇄적이고 안전한 문서 관리 환경을 구축할 수 있음. 소규모 팀의 경우 필요할 때만 해당 옵션을 true로 잠시 변경하여 가입을 유도하고 다시 잠그는 방식으로 운용 가능함.

6. Synology NAS(Docker) vs Coolify 배포 비교

과거 Synology NAS에서 Docker GUI 혹은 Portainer를 통해 설치했을 때와 비교하여 Coolify의 장점은 명확함.

• Synology 환경: 이미지 다운로드, 포트 매핑 충돌 관리, 역방향 프록시 수동 설정, 인증서 갱신 스크립트 관리 등 번거로운 과정이 많았음. 특히 데이터베이스 컨테이너와의 링크 설정에서 초보자가 잦은 오류를 범함.
• Coolify 환경: 데이터베이스가 자동으로 프로비저닝 되고 연결(Link)됨. 도메인과 SSL 설정이 자동화되어 있어 '설치'보다는 '클릭' 몇 번으로 서비스 런칭이 완료됨. 시스템 엔지니어링 지식이 깊지 않아도 안정적인 서비스 운영이 가능해짐.

7. 활용 방안 및 결론

구축된 나만의 웹 마크다운 플랫폼은 다양한 용도로 활용 가능함.

• 기술 블로그 초안 작성: 마크다운 문법을 완벽히 지원하므로, 추후 Jekyll, Hugo, Gatsby 등의 정적 사이트 생성기(SSG)로 포팅하기 용이함.
• 지식 관리 (Second Brain): 어디서든 접속 가능한 메모장 역할을 수행하며, 태그 기능을 통해 정보를 구조화할 수 있음.
• 코드 스니펫 저장: 개발 중 자주 사용하는 코드 조각을 언어별 하이라이팅 기능과 함께 보관 가능함.

결론적으로, Coolify를 이용한 CodiMD 설치는 **'생산성 도구의 자체 호스팅(Self-hosting) 장벽을 허문 사례'**라 평가할 수 있음. 과거의 복잡한 서버 세팅 과정에 지쳐 포기했던 사용자라면, Coolify를 통해 다시 한번 개인화된 문서 협업 도구를 구축해 볼 것을 강력히 권장함.

이로써 데이터 주권을 확보함과 동시에, 상용 SaaS(Notion, Obsidian Sync 등)의 구독료 부담 없이 자유로운 지식 관리 환경을 누릴 수 있게 됨.