DokuWiki 구축 및 협업 워크플로우 가이드

이 가이드는 사용자의 채찍질을 받으며 수십번의 시행착오를 반복한 Cursor AI + Gemini 2.5 Pro + Claude 4 Sonnet가 작성했습니다.

이 문서는 다음과 같은 과정을 안내합니다:

• PC에 존재하는 DokuWiki 작업물을 기반으로 Git 저장소 구성
• 라즈베리파이 서버에 배포
• PC(콘텐츠 공장)와 라이브 서버(팀 협업 공간) 간의 안전한 동기화

이 단계는 현재 PC에 있는 dokuwiki-dev 폴더를, 앞으로 모든 작업의 기준이 될 '마스터 Git 저장소'로 만드는 과정입니다.

PC에서 DokuWiki의 변경사항을 바로 확인하기 위해 XAMPP를 설치하고 설정합니다.

XAMPP 설치:

• XAMPP 공식 홈페이지에서 설치합니다.

포트 충돌 해결:

• XAMPP 제어판에서 Apache 시작 시 `Port 80 in use` 오류가 발생하면
• Config > httpd.conf 파일을 열어 Listen 80을 Listen 8080으로 수정
• 저장 후 Apache를 재시작합니다.

심볼릭 링크 생성: 관리자 권한으로 명령 프롬프트(CMD)를 열고, 아래 명령어를 실행하여 XAMPP가 우리 프로젝트 폴더를 인식하도록 합니다.

mklink /D "C:\xampp\htdocs\my-wiki" "C:\Users\YourUser\path\to\MYPROJECT\dokuwiki-dev"

확인: 웹 브라우저에서 다음 주소로 접속하여 PC의 위키를 확인할 수 있습니다.

http://localhost:8080/my-wiki/

PC의 dokuwiki-dev 폴더를 Git으로 관리 시작합니다.

Git 초기화: VS Code에서 MYPROJECT/dokuwiki-dev 폴더를 열고, 터미널에 아래 명령어를 입력합니다.

git init

.gitignore 파일 생성: 프로젝트 루트에 .gitignore 파일을 만들고, 아래 내용을 붙여넣어 불필요한 파일이 Git에 포함되지 않도록 합니다.

# DokuWiki .gitignore for Unified Management

# 캐시, 로그, 잠금 파일 등 서버에서만 생성되는 파일 무시
/data/cache/
/data/locks/
/data/tmp/
/data/log/
/data/attic/

# 로컬 사용자 인증 정보 및 ACL 설정은 제외
# 이 파일들은 서버에서 별도로 생성/관리됩니다.
/conf/users.auth.php
/conf/acl.auth.php
/conf/local.php
/conf/local.php.bak

첫 커밋: 현재까지 작업한 모든 내용(콘텐츠, 디자인)을 저장소에 기록합니다.

git add .
git commit -m "Initial commit of DokuWiki project from PC"

로컬 저장소를 GitHub과 연결하여 중앙 허브를 만듭니다.

GitHub에 새 저장소 생성:

• GitHub 웹사이트에서 `your-repo`라는 이름의 비어있는(Empty) 새 저장소를 만듭니다.

원격 저장소 연결 및 푸시: PC의 터미널에서 아래 명령어를 순서대로 실행하여 로컬 내용을 GitHub에 올립니다.

git remote add origin https://github.com/your-username/your-repo.git
git branch -M main
git push -u origin main

PC에서 완성한 초기 버전을 라즈베리파이에 그대로 복제하여 라이브 위키를 만듭니다.

라즈베리파이 터미널에서 웹서버, PHP, Git을 설치합니다.

sudo apt update
sudo apt install apache2 php git

라즈베리파이의 웹 루트 폴더로 이동하여, GitHub에 올려둔 우리 프로젝트를 내려받습니다.

cd /var/www/html
sudo git clone https://github.com/your-username/your-repo.git dokuwiki

서버에서 DokuWiki가 정상적으로 작동하도록 마지막 설정을 진행합니다.

설치 마법사 실행:

• 웹 브라우저에서 아래 주소로 접속합니다:

http://라즈베리파이_IP주소/dokuwiki/install.php

• 관리자 계정 등 초기 설정을 완료합니다
• 이 과정은 서버에만 필요한 `conf/local.php` 등의 파일을 생성합니다

권한 설정: 설치가 끝난 후, DokuWiki가 파일을 저장할 수 있도록 아래 명령어로 폴더 권한을 설정해줍니다.

sudo chown -R www-data:www-data /var/www/html/dokuwiki

이제 PC와 라즈베리파이 양쪽에서 작업한 내용을 안전하게 동기화하는 실제 운영 단계입니다.

PC에서는 아래의 'PULL → CREATE → PUSH' 3단계 법칙만 기억하시면 됩니다.

📥 (PULL) 작업 시작 전, 항상 최신 내용 먼저 받기:

PC의 `dokuwiki-dev` 폴더에서 새로운 작업을 시작하기 전에 아래 명령어를 실행합니다.

다른 팀원이 라이브 서버에서 수정한 내용을 먼저 내 PC로 가져옵니다.

git pull origin main

✨ (CREATE) AI로 콘텐츠 대량 생산하기:

최신 상태가 된 `dokuwiki-dev/data/pages/` 폴더에서 작업합니다.

커서 AI를 사용하여 원하는 만큼의 폴더와 `.txt` 파일을 자유롭게 생성합니다.

📤 (PUSH) 완성된 콘텐츠 납품하기:

콘텐츠 생성이 끝나면 아래 명령어를 실행합니다.

PC에서 만든 새로운 파일들을 GitHub 저장소에 올립니다.

git add .
git commit -m "Add: 새로운 콘텐츠 묶음 추가"
git push origin main

라즈베리파이는 다음 두 가지 작업을 주기적으로 수행합니다:

• (1) 팀원들의 작업을 자동으로 GitHub에 백업
• (2) PC에서 올린 새 콘텐츠를 자동으로 내려받기

자동 동기화 스크립트 생성:

라즈베리파이에서 아래 명령어로 스크립트 파일을 생성합니다.

sudo nano /usr/local/bin/dokuwiki_sync.sh

열린 편집기에 아래 내용을 붙여넣습니다. 이 스크립트는 두 가지 기능을 수행합니다:

• 서버의 변경사항을 먼저 푸시
• 원격 저장소의 내용을 풀(pull)

#!/bin/bash

# DokuWiki 프로젝트 디렉토리로 이동
cd /var/www/html/dokuwiki || exit

# 1. 서버 변경사항 자동 커밋 및 푸시
# 변경사항이 있을 때만 실행
if ! git diff-index --quiet HEAD --; then
    echo "Changes detected on server. Pushing to origin..."
    sudo -u www-data git add .
    sudo -u www-data git commit -m "Auto-Sync: Content update from server on $(date)"
    sudo -u www-data git push origin main
fi

# 2. 원격 저장소의 최신 내용 가져오기 (PC 작업물 등)
echo "Pulling latest changes from origin..."
sudo -u www-data git pull origin main

스크립트 실행 권한 부여:

sudo chmod +x /usr/local/bin/dokuwiki_sync.sh

주기적인 실행 스케줄 등록 (Cron):

`sudo crontab -e` 명령어로 크론탭 편집기를 열고, 아래 내용을 추가합니다.

매 5분마다 동기화 스크립트를 실행하도록 설정합니다.

*/5 * * * * /usr/local/bin/dokuwiki_sync.sh > /var/log/dokuwiki_sync.log 2>&1

참고: `> /var/log/dokuwiki_sync.log 2>&1` 부분은 실행 로그를 파일로 남깁니다. 나중에 문제가 생겼을 때 원인을 파악하는 데 도움이 됩니다.

이제 완벽한 자동화 시스템이 완성되었습니다:

• PC: 편하게 콘텐츠 생산
• 팀원들: 라이브 위키에서 자유롭게 협업
• 서버: 모든 것을 알아서 동기화

• 라즈베리파이: 서버 호스팅 환경
• Linux: 서버 운영체제
• Nginx: 웹 서버 (Apache 대신 사용 가능)
• Git: 버전 관리 시스템
• GitHub: 원격 저장소 서비스

• 백업 전략: 정기적으로 전체 프로젝트를 별도 위치에 백업
• 충돌 해결: Git merge 충돌 발생 시 수동으로 해결 후 커밋
• 보안: GitHub 저장소를 Private으로 설정하여 보안 강화
• 모니터링: 동기화 로그를 정기적으로 확인하여 문제 조기 발견

🚀 AI 시대에 맞는 완전 자동화된 위키 협업 시스템 구축 완료!

PC에서는 AI로 콘텐츠를 대량 생산하고, 서버에서는 팀원들과 실시간 협업하세요.