MkDocs를 Coolify와 Gitea로 배포하는 완벽 가이드

필자 팁: 이 가이드는 MkDocs를 사용해 문서 사이트를 만들고, Gitea와 Coolify를 통해 자동 배포하는 전체 과정을 다룹니다. 각 단계를 차근차근 따라하면 누구나 성공할 수 있습니다.

---

광고

🤖 Claude AI 학습 도우미

우리 아이의 든든한 AI 학습 파트너

🎁 무료 체험 가능

👆 Claude AI 체험하기

---

📚 왜 Claude인가요?

숙제 질문부터 독서감상문까지, Claude가 아이의 학습 파트너가 되어드려요.
아이 혼자서도 안전하게 질문하고 배울 수 있어서 부모님도 안심!

---

✨ 핵심 기능

기능	설명
🕒 24시간 언제든 학습 도움	밤늦게 숙제하다 막혀도 걱정 없어요
💡 창의적 사고력 키우기	단순 답변이 아닌 생각하는 법을 알려줘요
🛡️ 안전한 AI 환경	아이들에게 적합한 안전한 대화만 제공

---

🎯 이런 분들께 추천!

• ✅ 바쁜 워킹맘/워킹대디
• ✅ 자기주도학습을 원하는 부모님
• ✅ 아이의 창의력 개발이 고민인 분
• ✅ 안전한 AI 교육 도구를 찾는 분

---

🚀 지금 시작하세요!

🎁 무료 체험 가능

👆 Claude AI 체험하기

---

#초등공부 #AI학습도우미 #엄마아빠필수템

💙 우리 아이의 밝은 미래를 Claude와 함께 시작하세요!

---

🛠️ 준비물 체크리스트

시작하기 전에 다음 도구들이 필요합니다:

• Python 3.4 이상 (pip 포함)
• Visual Studio Code - 코드 편집기
• Gitea - Git 저장소 관리 (GitHub Pages 대신 사용)

🚀 Python 환경 설정

1단계: Python 버전 확인

터미널에서 현재 Python 버전을 확인해보세요:

python3 --version
Copy

버전이 표시되면 다음 단계로 넘어가세요. 만약 Python이 설치되지 않았다면:

brew install python
Copy

2단계: PATH 환경변수 설정

경로 연결이란? 컴퓨터가 Python을 어디서 찾을지 알려주는 설정입니다.

~/.zshrc 파일에 다음 내용을 추가하세요 (이미 있다면 건너뛰기):

export PATH="/opt/homebrew/bin:$PATH"
Copy

설정을 저장한 후 터미널에서 갱신:

source ~/.zshrc
Copy

📁 프로젝트 설정 및 MkDocs 설치

3단계: 프로젝트 폴더 만들기

1. 적당한 위치에 새 폴더를 만들어주세요
2. Visual Studio Code에서 해당 폴더를 열어주세요
3. VS Code 터미널을 열어주세요

4단계: Python 가상환경 만들기

가상환경이란? 프로젝트마다 독립적인 Python 환경을 만드는 것입니다. 이렇게 하면 다른 프로젝트와 충돌하지 않아요.

python3 -m venv venv
source venv/bin/activate
Copy

5단계: MkDocs Material 설치

Material 테마는 MkDocs의 가장 인기 있는 테마입니다:

pip install mkdocs-material
Copy

6단계: 가상환경 다시 활성화

source venv/bin/activate
Copy

7단계: MkDocs 프로젝트 초기화

현재 폴더에 MkDocs 프로젝트를 만들어주세요:

mkdocs new .
Copy

⚙️ MkDocs 설정 파일 구성

8단계: mkdocs.yml 파일 설정

설정 파일의 역할: 사이트의 모든 디자인과 기능을 결정하는 핵심 파일입니다.

아래 내용으로 mkdocs.yml 파일을 만들어주세요:

site_name: Personal Document flutter (auth kage2k)
site_url: https://pdflutter.kage2kapp.org
site_description: Flutter 개발을 위한 실용적인 가이드와 문제 해결 방법
site_author: Heesung Jin (kage2k)

theme:
  name: material
  language: ko
  palette:
    scheme: slate
    primary: green
    accent: deep purple
  features:
    - navigation.footer
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - navigation.tracking
    - search.highlight
    - search.suggest
    - content.code.copy
    - content.code.select
    - content.code.annotate
    - content.tabs.link
  icon:
    logo: fontawesome/brands/android # flutter 아이콘 대신 안드로이드 아이콘 사용
    repo: fontawesome/brands/github

extra:
  social:
    - icon: simple/youtube
      link: https://www.youtube.com/@heesungjin8554
      name: YouTube 채널
    - icon: fontawesome/brands/github
      link: https://github.com/flutterkage2k/
      name: GitHub
    - icon: fontawesome/brands/x-twitter
      link: https://x.com/Jin18976573
      name: X (Twitter)
    - icon: material/storefront-edit-outline
      link: https://kage2kapp.org
      name: 개인 웹사이트

copyright: Copyright © 2025. All rights reserved.

extra_css:
  - assets/stylesheets/extra.css

extra_javascript:
  - https://unpkg.com/mermaid@10.6.1/dist/mermaid.min.js

markdown_extensions:
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
  - admonition
  - pymdownx.details
  - pymdownx.critic
  - pymdownx.caret
  - pymdownx.keys
  - pymdownx.mark
  - pymdownx.tilde
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
      use_pygments: true
      linenums: false
  - pymdownx.inlinehilite
  - pymdownx.snippets:
      base_path: ["docs", "docs/assets/scripts"]
  - pymdownx.superfences:
      custom_fences:
        - name: dart
          class: language-dart
          format: !!python/name:pymdownx.superfences.fence_code_format
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tasklist:
      custom_checkbox: true

# 네비게이션 구조
nav:
  - 홈: index.md
  - Flutter: 
      - 환경설정: 
          - Java 17: flutter/1_install_java17.md
          - Linter: flutter/2_flutter_linter_guide.md
      - 개발: 
          - AdMob: flutter/3_admob_flutter_guide.md
      - 문제해결: 
          - 빌드 에러: flutter/4_flutter_fix_guide.md

plugins:
  - search:
      lang:
        - ko
        - en
      separator: '[\s\-\.]+'

# 개발 환경 설정
dev_addr: 127.0.0.1:8000
use_directory_urls: true
Copy

9단계: 로컬에서 테스트 실행

설정이 제대로 되었는지 확인해보세요:

mkdocs serve
Copy

브라우저에서 http://127.0.0.1:8000으로 접속하여 사이트가 잘 나오는지 확인하세요.

📝 Git 무시 파일 설정

10단계: .gitignore 파일 만들기

Git 무시 파일이란? Git에 올리지 않을 파일들을 지정하는 목록입니다. 불필요한 파일들이 저장소에 들어가는 것을 막아줍니다.

프로젝트 루트에 .gitignore 파일을 만들고 다음 내용을 넣어주세요:

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
# downloads/  # MkDocs 문서의 downloads 폴더를 위해 주석 처리
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
pip-wheel-metadata/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# PyInstaller
#  Usually these files are written by a python script from a template
#  before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/

# Translations
*.mo
*.pot

# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal

# Flask stuff:
instance/
.webassets-cache

# Scrapy stuff:
.scrapy

# Sphinx documentation
docs/_build/

# PyBuilder
target/

# Jupyter Notebook
.ipynb_checkpoints

# IPython
profile_default/
ipython_config.py

# pyenv
.python-version

# pipenv
#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
#   However, in case of collaboration, if having platform-specific dependencies or dependencies
#   having no cross-platform support, pipenv may install dependencies that don't work, or not
#   install all needed dependencies.
#Pipfile.lock

# PEP 582; used by e.g. github.com/David-OConnor/pyflow
__pypackages__/

# Celery stuff
celerybeat-schedule
celerybeat.pid

# SageMath parsed files
*.sage.py

# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/

# Spyder project settings
.spyderproject
.spyproject

# Rope project settings
.ropeproject

# mkdocs documentation
/site

# mypy
.mypy_cache/
.dmypy.json
dmypy.json

# Pyre type checker
.pyre/

# =============================================================================
# MkDocs 추가 설정
# =============================================================================

# MkDocs 빌드 결과물 (이미 있지만 확실히)
site/

# MkDocs 서버 실행시 생성되는 파일들
.mkdocs_cache/

# =============================================================================
# 개발 환경 관련 추가
# =============================================================================

# IDE 설정 파일들
.vscode/
.idea/
*.swp
*.swo
*~

# 맥OS 파일들
.DS_Store
.AppleDouble
.LSOverride

# 윈도우 파일들
Thumbs.db
ehthumbs.db
Desktop.ini

# 리눅스 파일들
*~
.fuse_hidden*
.directory
.Trash-*

# =============================================================================
# 백업 및 임시 파일
# =============================================================================

# 백업 파일들
*.bak
*.backup
*.orig
*.tmp

# 로그 파일들 (추가)
*.log.*
logs/

# =============================================================================
# 프로젝트별 설정 (필요시 추가)
# =============================================================================

# 개인 설정 파일 (예: 개발자마다 다른 설정)
config.local.yml
secrets.yml

# 테스트 결과물
test-results/
screenshots/

# MkDocs 문서의 downloads 폴더는 포함되어야 함
!docs/flutter/downloads/
Copy

🐳 Docker 배포 준비

11단계: requirements.txt 파일 생성

requirements.txt란? Python 프로젝트에 필요한 라이브러리 목록을 저장하는 파일입니다.

프로젝트 루트에서 다음 명령어를 실행:

pip freeze > requirements.txt
Copy

생성된 requirements.txt 파일 내용:

babel==2.17.0
backrefs==5.8
certifi==2025.4.26
charset-normalizer==3.4.2
click==8.2.1
colorama==0.4.6
csscompressor==0.9.5
ghp-import==2.1.0
htmlmin2==0.1.13
idna==3.10
Jinja2==3.1.6
jsmin==3.0.1
Markdown==3.8
MarkupSafe==3.0.2
mergedeep==1.3.4
mkdocs==1.6.1
mkdocs-get-deps==0.2.0
mkdocs-material>=9.0.0,<10.0.0
mkdocs-material-extensions==1.3.1
mkdocs-minify-plugin==0.8.0
packaging==25.0
paginate==0.5.7
pathspec==0.12.1
platformdirs==4.3.8
Pygments==2.19.1
pymdown-extensions==10.15
python-dateutil==2.9.0.post0
PyYAML==6.0.2
pyyaml_env_tag==1.1
requests==2.32.3
six==1.17.0
urllib3==2.4.0
watchdog==6.0.0
Copy

12단계: Dockerfile 작성

Dockerfile이란? Docker 이미지를 만들기 위한 설계도입니다. 우리 사이트를 어떻게 패키징할지 정의합니다.

프로젝트 루트에 Dockerfile을 만들고 다음 내용을 입력:

# =============================================================================
# MkDocs Flutter 문서 사이트 Dockerfile
# =============================================================================

# 1단계: 빌드 환경
FROM python:3.11-slim as builder

# 작업 디렉토리 설정
WORKDIR /app

# 시스템 의존성 설치 (빌드 시에만 필요)
RUN apt-get update && apt-get install -y \
    git \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Python 의존성 복사 및 설치
COPY requirements.txt .
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt

# 프로젝트 파일 복사
COPY . .

# MkDocs 빌드
RUN mkdocs build --clean

# =============================================================================
# 2단계: 운영 환경 (Nginx)
# =============================================================================

FROM nginx:alpine as production

# 메타데이터 라벨
LABEL maintainer="Heesung Jin (kage2k)"
LABEL description="Flutter Documentation Site with MkDocs Material"
LABEL version="2.0"

# 빌드된 사이트를 Nginx로 복사
COPY --from=builder /app/site /usr/share/nginx/html

# 사용자 정의 Nginx 설정 복사
COPY nginx.conf /etc/nginx/nginx.conf

# Nginx 기본 설정 제거 및 권한 설정
RUN rm -f /etc/nginx/conf.d/default.conf && \
    chown -R nginx:nginx /usr/share/nginx/html && \
    chmod -R 755 /usr/share/nginx/html

# 포트 노출
EXPOSE 80

# 헬스체크 추가
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD curl -f http://localhost/ || exit 1

# Nginx 실행
CMD ["nginx", "-g", "daemon off;"]
Copy

13단계: Nginx 설정 파일 작성

Nginx란? 웹 서버로, 우리가 만든 정적 사이트를 인터넷에 서비스하는 역할을 합니다.

nginx.conf 파일을 만들고 다음 내용을 입력:

events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';
    
    access_log /var/log/nginx/access.log main;
    error_log /var/log/nginx/error.log warn;
    
    sendfile        on;
    tcp_nopush      on;
    tcp_nodelay     on;
    keepalive_timeout  65;
    types_hash_max_size 2048;
    
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types
        text/plain
        text/css
        text/xml
        text/javascript
        application/json
        application/javascript
        application/xml+rss
        application/atom+xml
        image/svg+xml;
    
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;
    
    server {
        listen       80;
        server_name  localhost;
        root   /usr/share/nginx/html;
        index  index.html index.htm;
        
        location / {
            try_files $uri $uri/ /index.html;
        }
        
        location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
            add_header Access-Control-Allow-Origin "*";
        }
        
        location ~* \.html$ {
            expires 1h;
            add_header Cache-Control "public, must-revalidate";
        }
        
        location /assets/fonts/ {
            expires 1y;
            add_header Cache-Control "public, immutable";
            add_header Access-Control-Allow-Origin "*";
        }
        
        # 기존 nginx.conf에서 /flutter/downloads/ 부분만 교체

        location /flutter/downloads/ {
            expires 1d;
            add_header Cache-Control "public";
            
            # 텍스트 파일 다운로드 강제
            location ~* \.txt$ {
                add_header Content-Type "text/plain; charset=utf-8";
                add_header Content-Disposition "attachment; filename=$1";
            }
            
            # 스크립트 파일 (향후 사용 시)
            location ~* \.sh$ {
                add_header Content-Type "application/x-shellscript";
                add_header Content-Disposition "attachment; filename=$1";
            }
            
            # ZIP 파일 (필요시)
            location ~* \.zip$ {
                add_header Content-Type "application/zip";
                add_header Content-Disposition "attachment; filename=$1";
            }
        }  
        
        error_page 404 /404.html;
        location = /404.html {
            internal;
        }
        
        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            internal;
        }
        
        location ~ /\. {
            deny all;
            access_log off;
            log_not_found off;
        }
        
        location ~ ~$ {
            deny all;
            access_log off;
            log_not_found off;
        }
        
        location /health {
            access_log off;
            return 200 "healthy\n";
            add_header Content-Type text/plain;
        }
    }
}
Copy

14단계: Prettier 무시 파일 설정

Prettier란? 코드 포맷팅 도구인데, 마크다운 문서는 건드리지 않도록 설정합니다.

.prettierignore 파일을 만들고 다음 내용을 입력:

# Prettier에서 제외할 파일들

# 마크다운 파일 모두 제외
*.md
**/*.md

# MkDocs 문서 디렉토리
docs/
docs/**/*.md

# 기타 문서 파일들
README.md
CHANGELOG.md
LICENSE.md

# 빌드 결과물
site/
site/**/*

# 설정 파일들 (선택사항)
mkdocs.yml
.gitignore

# 스크립트 파일들 (선택사항)
*.sh
**/*.sh
Copy

🚀 Git 저장소 설정 및 Coolify 배포

15단계: Gitea에 저장소 만들기

1. Gitea에서 새 public 저장소를 만들어주세요
2. VS Code에서 프로젝트를 Git과 연결:
   bash
git init
git add .
git commit -m "Initial commit"
git remote add origin [당신의 Gitea 저장소 URL]
git push -u origin main

16단계: Coolify 프로젝트 설정

Coolify란? Docker 기반의 배포 플랫폼으로, 코드 변경사항을 자동으로 배포해주는 도구입니다.

다음 스크린샷을 참고하여 Coolify에서 설정하세요:

17단계: Webhook 연결 설정

Webhook이란? Git 저장소에 변경사항이 생기면 Coolify에 자동으로 알려주는 기능입니다.

Coolify에서 Webhook URL 복사

Coolify에서 제공하는 webhook URL을 복사해주세요.

Gitea에서 Webhook 설정

Gitea 저장소 설정에서 webhook을 추가하고, 위에서 복사한 URL을 입력하세요.

!!! warning "webhook 작업을 안하면" Coolify에서 Auto Deploy가 작동하지 않습니다. 코드를 푸시해도 자동으로 배포되지 않아요.

🎉 완료 및 테스트

모든 설정이 끝났습니다! 이제 다음과 같이 테스트해보세요:

1. 로컬 테스트: mkdocs serve로 로컬에서 사이트 확인
2. Git 푸시: 변경사항을 Git에 푸시
3. 자동 배포: Coolify에서 자동으로 배포되는지 확인
4. 사이트 접속: 배포된 사이트에 접속해서 잘 작동하는지 확인

💡 전문가 팁

• 정기적인 백업: 중요한 문서는 정기적으로 백업하세요
• 브랜치 전략: 큰 변경사항은 별도 브랜치에서 작업 후 병합하세요
• 모니터링: Coolify 로그를 정기적으로 확인하여 문제를 조기에 발견하세요
• 성능 최적화: 이미지 크기를 최적화하고 불필요한 플러그인은 제거하세요

이제 전문적인 문서 사이트를 자동으로 배포할 수 있는 환경이 완성되었습니다! 🎊