Docker Compose로 Planka 직접 호스팅하기
Docker Compose를 사용하여 Planka를 VPS에 배포하는 방법을 알아봅니다. Postgres 연동과 Traefik 설정은 물론, 로그인 오류를 유발하는 BASE_URL 환경 변수 설정 및 관리자 계정 생성 시 주의사항을 상세히 다룹니다.
Planka를 직접 호스팅하여 얻는 이점
Planka를 직접 호스팅하면 Trello에서 이미 익숙한 카드, 리스트, 라벨 모델을 갖춘 칸반 보드를 직접 제어하는 VPS에서 운영할 수 있습니다. 서버 비용 외에는 사용자당 요금이나 계정 수 제한이 없습니다. 이 가이드에서는 Docker Compose를 사용하여 Traefik 뒤에 Planka를 배포하며, 데이터베이스로는 Postgres를, 사용자가 업로드하는 모든 파일을 저장하기 위해 명명된 볼륨(named volume)을 사용합니다.
Planka 2는 프로젝트 자체의 Fair Use License에 따라 배포됩니다. 프로젝트 측은 이를 오픈 소스가 아닌 소스 공개(source-available) 모델로 설명합니다. 조직 내부 프로젝트를 위해 직접 운영하는 것은 허용됩니다. 제3자에게 상용 호스팅 서비스로 제공하려면 Pro 또는 Enterprise 라이선스가 필요합니다.
이 가이드는 Trello 무료 플랜에서 이주하려는 2~5명 규모의 팀을 대상으로 합니다. 어떤 보드 서비스를 운영할지 결정 중이라면 먼저 직접 호스팅 가능한 Trello 대안 비교를 읽어보시기 바랍니다. 이 가이드는 이미 선택을 마쳤다고 가정하며 배포 과정만 다룹니다.
Docker Engine과 Compose 플러그인이 설치된 VPS와 해당 서버를 가리키는 DNS A 레코드가 필요합니다. 또한 해당 서버에서 이미 TLS(전송 계층 보안)를 종료하고 있는 Traefik 인스턴스가 있어야 합니다. Traefik이 아직 설정되지 않았다면 먼저 여러 Compose 앱 앞단에 Traefik 리버스 프록시 설정하기를 진행하십시오. 아래 파일 형식이 생소하다면 VPS를 위한 Docker Compose 기초를 먼저 읽어보시기 바랍니다.
Planka는 어느 정도 규모의 VPS가 필요한가?
프로젝트의 기술 FAQ에서는 소규모 팀을 위해 최소 2 GB RAM과 10 GB 스토리지를 권장하므로, 이 수치는 측정값이 아닌 시작점으로 간주해야 합니다.
실제로 실행되는 프로세스는 작습니다. API와 빌드된 프론트엔드를 제공하는 Node.js 프로세스 하나와 데이터를 저장하는 Postgres 서버가 실행됩니다. Postgres는 관리 프로세스 하나와 열린 연결마다 백엔드 프로세스 하나를 생성합니다. Planka 컨테이너 내부에는 나가는 요청을 필터링하기 위한 작은 프록시 프로세스도 함께 실행됩니다. 2 GB 플랜은 소규모 팀을 위한 프로젝트의 RAM 권장 사양과 일치합니다. 보드 서비스는 리소스를 적게 점유하지만, 동일한 VPS에서 팀의 문서를 함께 관리할 계획이라면 해당 애플리케이션의 사양을 먼저 고려하십시오. Notion 스타일의 워크스페이스로 AFFiNE 실행하기는 Planka가 리소스를 요청하기 전부터 이미 수 기가바이트의 메모리를 필요로 합니다.
첨부 파일은 시간이 지남에 따라 용량이 증가하므로 메모리보다 디스크 크기를 먼저 산정하십시오. 이 글의 내용을 맹신하기보다 직접 자신의 인스턴스를 측정하십시오.
docker stats --no-stream
docker system df -v첫 번째 명령은 컨테이너별 실시간 메모리 및 CPU 사용량을 출력합니다. 두 번째 명령은 각 볼륨이 차지하는 공간을 보여줍니다. 설치 직후가 아닌, 일반적인 업무 주간을 보낸 뒤에 두 측정값을 확인하십시오. 유휴 상태의 보드만으로는 팀의 실제 사용량을 파악할 수 없기 때문입니다.
Compose 파일 작성
디렉터리를 생성하고 소유권을 변경하여 sudo을 통해 이 파일들을 수정할 필요가 없도록 합니다.
sudo mkdir -p /opt/planka
sudo chown "$USER":"$USER" /opt/planka
cd /opt/plankaCompose 파일 옆에 .env 파일을 생성하여 비밀 값을 저장합니다. Compose는 이 파일을 자동으로 읽어 값을 치환합니다.
umask 077
{
printf 'SECRET_KEY=%s\n' "$(openssl rand -hex 64)"
printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 24)"
printf 'ADMIN_PASSWORD=%s\n' "$(openssl rand -hex 12)"
} > .env
chmod 600 .envopenssl rand -hex를 사용하는 데에는 이유가 있습니다. 16진수 문자열은 숫자와 a부터 f까지의 문자로만 구성되므로, 삽입되는 DATABASE_URL 연결 문자열을 손상시키지 않습니다. 표준 Base64는 슬래시, 더 플러스 기호, 패딩을 위한 등호 기호를 포함할 수 있지만 골뱅이 기호는 포함하지 않습니다. 연결 URL에서 특별한 의미를 갖는 문자는 퍼센트 인코딩이 필요합니다. 더 넓은 범위의 패턴은 Compose 파일에서 비밀 정보 제외하기에서 다룹니다.
이제 docker-compose.yml를 실행합니다. kanban.example.com를 두 곳 모두 본인의 호스트 이름으로 변경하십시오.
services:
planka:
image: ghcr.io/plankanban/planka:2.2.1
restart: unless-stopped
volumes:
- planka-data:/app/data
environment:
- BASE_URL=https://kanban.example.com
- DATABASE_URL=postgresql://planka:${POSTGRES_PASSWORD}@postgres/planka
- SECRET_KEY=${SECRET_KEY}
- TRUST_PROXY=true
- DEFAULT_ADMIN_EMAIL=you@example.com
- DEFAULT_ADMIN_PASSWORD=${ADMIN_PASSWORD}
- DEFAULT_ADMIN_NAME=Your Name
- DEFAULT_ADMIN_USERNAME=admin
networks:
- proxy
- internal
labels:
- "traefik.enable=true"
- "traefik.docker.network=proxy"
- "traefik.http.routers.planka.rule=Host(`kanban.example.com`)"
- "traefik.http.routers.planka.entrypoints=websecure"
- "traefik.http.routers.planka.tls.certresolver=default"
- "traefik.http.services.planka.loadbalancer.server.port=1337"
depends_on:
postgres:
condition: service_healthy
postgres:
image: postgres:16-alpine
restart: unless-stopped
volumes:
- db-data:/var/lib/postgresql/data
environment:
- POSTGRES_DB=planka
- POSTGRES_USER=planka
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
networks:
- internal
healthcheck:
test: ["CMD-SHELL", "pg_isready -U planka -d planka"]
interval: 10s
timeout: 5s
retries: 5
volumes:
planka-data:
db-data:
networks:
proxy:
external: true
internal:해당 파일에 포함된 네 가지 결정 사항은 사용자가 임의로 변경했다가 후회하는 경우가 많으므로 설명이 필요합니다.
- Planka 서비스에는
ports:블록이 없습니다. Traefik은proxy네트워크를 통해 컨테이너에 도달하므로 1337 포트는 호스트에 노출되지 않습니다. 포트를 노출하면 프록시와 인증서를 우회할 수 있는 경로를 제공하게 됩니다. loadbalancer.server.port=1337은 컨테이너 내부의 포트를 지정합니다. Planka는 1337 포트에서 대기하지만, 업스트림 예제는 포트를 호스트에 매핑하기 때문에 3000 포트로만 접근합니다. 여기에는 호스트 매핑이 없으므로 Traefik에 컨테이너 포트를 알려주어야 합니다.condition: service_healthy는 Postgres의 상태 확인(healthcheck)과 짝을 이룹니다. 이 설정이 없으면 Planka는 데이터베이스가 연결을 수락하기 전에 시작되어 첫 번째 쿼리에서 실패하고 종료되는데, 이는 크래시 루프처럼 보입니다. 작동 원리는 Compose 상태 확인 및 시작 순서에 있습니다.- 데이터베이스 서비스의 이름을
postgres으로 지정한 데에는 의도가 있습니다. Planka 2는 기본 차단 목록이localhost,postgres인 내부 필터를 통해 나가는 요청을 라우팅합니다. 서비스 이름을 바꾸면 해당 목록에서 데이터베이스가 자동으로 제외됩니다.
시작하기 전에 Compose가 비밀 정보를 인식하는지 확인하십시오.
docker compose config | grep -E 'image:|BASE_URL|POSTGRES_USER'이 명령은 .env 값이 이미 치환된 파일을 출력합니다. 값이 비어 있다면 Compose가 .env 파일을 읽지 못하는 것이며, 이는 보통 다른 디렉터리에서 명령을 실행했을 때 발생합니다.
관리자 부트스트랩 변수의 실제 동작 방식
Planka 1.13 버전부터는 관리자가 자동으로 생성되지 않으므로, 새로 설치한 데이터베이스에는 로그인할 수 있는 사용자가 없습니다. DEFAULT_ADMIN_* 그룹은 이를 해결하는 두 가지 방법 중 하나입니다.
Planka는 시작 시 DEFAULT_ADMIN_EMAIL와 일치하는 사용자를 찾습니다. 해당 사용자가 없으면 함께 설정된 비밀번호, 표시 이름, 사용자 이름을 사용하여 계정을 생성합니다. 이후 다시 시작할 때도 이 변수들을 사용하여 일치하는 계정 정보를 업데이트하며, DEFAULT_ADMIN_PASSWORD이 설정되어 있으면 비밀번호를 재설정합니다.
DEFAULT_ADMIN_EMAIL은 사용자가 자주 간과하는 두 번째 역할을 수행합니다. 이 변수가 설정되어 있는 동안에는 해당 계정의 이름, 역할, 이메일 주소를 인터페이스를 통해 변경하거나 삭제할 수 없습니다. 이는 계정 잠김 방지를 위한 보호 장치이며, UI에서 해당 계정의 이름이나 이메일 주소를 수정할 수 없는 이유이기도 합니다. 변수를 제거하고 재시작하면 해당 계정은 다른 계정과 동일하게 수정 가능한 일반 관리자 계정이 됩니다.
비밀번호 설정 줄은 주의가 필요합니다. environment: 아래에 있는 모든 내용은 컨테이너에서 docker inspect를 실행할 수 있는 사람이라면 누구나 읽을 수 있으므로, DEFAULT_ADMIN_PASSWORD을 영구적으로 유지해서는 안 됩니다. 로그인 후 해당 줄을 삭제하고 docker compose up -d을 다시 실행한 다음, 인터페이스에서 비밀번호를 변경하십시오.
더 깔끔한 방법은 변수를 전혀 사용하지 않는 것입니다. DEFAULT_ADMIN_* 그룹 전체를 주석 처리한 뒤, 대화형 방식으로 계정을 생성하십시오.
docker compose run --rm planka npm run db:create-admin-user이 명령은 이메일, 비밀번호, 표시 이름, 선택 사항인 사용자 이름을 입력받아 데이터베이스에 직접 기록합니다. 비밀번호가 Compose 파일이나 컨테이너의 설정된 환경 변수에 노출되지 않습니다. VPS에 여러 사람이 셸 접근 권한을 가지고 있다면 이 방식을 사용하십시오. 이 명령은 depends_on 덕분에 Postgres를 먼저 시작하므로, 한 번도 실행된 적 없는 스택에서도 정상적으로 작동합니다.
어떤 방식을 선택하든 Planka 비밀번호는 직접 관리해야 합니다. 2.1.1 버전까지는 Community 에디션에서 자체 싱글 사인온 서버로 운영하는 Authentik과 같은 OIDC 제공업체에 로그인을 위임할 수 있었으나, 2026년 8월에 출시된 2.2.0 버전부터는 OIDC 및 SSO 기능이 PLANKA Pro로 이전되었습니다. 같은 릴리스에서 Community 에디션에 추가된 기능은 로컬 계정을 위한 2단계 인증(TOTP)이므로, 최소한 관리자 계정에는 이를 활성화하십시오.
BASE_URL이 호스트 이름과 일치하지 않을 때 로그인에 실패하는 이유
BASE_URL는 사용자가 브라우저에 입력하는 정확한 주소이며, 스킴(scheme)을 포함하고 마지막에 슬래시를 붙이지 않습니다. 이 스택의 경우 https://kanban.example.com가 해당합니다. Planka는 이 값을 기반으로 자체 링크와 허용된 WebSocket 오리진 목록을 생성하므로, BASE_URL이 잘못 설정되면 명확한 오류 메시지가 표시되지 않습니다. 대신 페이지가 로드되다가 무한히 대기하는 상태가 됩니다.
흔히 발생하는 사례는 업스트림 예제를 복사한 뒤 BASE_URL=http://localhost:3000을 그대로 두어, 실제 도메인의 HTTPS를 통해 사이트에 접속하는 경우입니다. 로그인 폼을 제출하면 자격 증명은 승인되지만 보드 화면이 나타나지 않습니다. 브라우저 개발자 도구 콘솔을 열어보면 /socket.io/로 향하는 요청이 실패하는 것을 볼 수 있습니다. 소켓은 브라우저 페이지의 오리진으로 연결되지만, 서버의 오리진 제한 설정은 BASE_URL에서 파생된 오리진만 허용하기 때문입니다.
TRUST_PROXY=true은 동일한 문제의 나머지 절반을 차지합니다. Planka는 Traefik 뒤에서 동작하므로, 모든 요청은 Docker 네트워크 내부에서 프록시 주소를 통해 일반 HTTP로 전달됩니다. TRUST_PROXY이 없으면 애플리케이션은 Traefik이 설정한 X-Forwarded-Proto 및 X-Forwarded-For 헤더를 무시합니다. 그 결과 연결이 안전하지 않다고 판단하여 모든 클라이언트를 하나의 공유 IP 주소로 취급합니다. 이 설정이 활성화되면 애플리케이션은 해당 헤더를 읽고 브라우저와 동일한 스킴을 사용하도록 동기화합니다.
Traefik은 별도의 추가 설정 없이 WebSocket을 프록시하므로 이 환경에서 선호되는 이유 중 하나입니다. nginx를 사용할 경우 프록시가 proxy_set_header Upgrade $http_upgrade 및 proxy_set_header Connection "upgrade" 업그레이드 헤더를 전달해야 하며, 그렇지 않으면 다른 원인으로 인해 동일하게 로딩 아이콘이 멈추는 현상이 발생합니다. 이 설정은 일반 location / 블록에 포함할 수 있으며, /socket.io을 위한 별도의 블록을 구성해도 되지만 필수는 아닙니다.
나중에 보드를 새로운 호스트 이름으로 옮기려면 BASE_URL 값과 Traefik Host() 규칙 두 가지를 함께 변경해야 합니다. 하나만 변경하고 나머지를 잊으면 다시 로딩 아이콘이 멈추는 현상을 겪게 됩니다. https://example.com/planka과 같은 하위 경로에서 Planka를 서비스하는 것은 2026년 3월에 릴리스된 버전 2.1.0부터 지원됩니다. 이전 태그를 사용 중이라면 별도의 서브도메인을 할당하십시오.
Planka가 첨부 파일과 아바타를 저장하는 위치
Planka 2는 사용자가 업로드한 모든 데이터를 컨테이너 내부의 단일 경로인 /app/data에 저장합니다. 첨부 파일, 사용자 아바타, 보드 배경 이미지가 모두 이 경로 아래에 위치합니다. 버전 1에서는 세 개의 개별 디렉터리를 사용했으므로, 이전 문서에서 복사한 Compose 파일은 더 이상 존재하지 않는 경로를 마운트하게 되어 의도한 데이터 마운트가 누락됩니다.
이 단일 마운트 설정 여부가 업그레이드 후에도 보드가 유지되는지, 아니면 곤란한 상황을 겪게 되는지를 결정합니다. Docker 이미지는 /app/data를 볼륨으로 선언하므로, Compose에서 마운트를 생략하면 업로드 파일은 익명 볼륨에 저장됩니다. Compose는 일반적인 up 재생성 과정에서는 이를 보존하지만, 이후 down를 실행하고 up를 수행하면 자동으로 다시 연결되지 않습니다. 보드는 정상적으로 돌아온 것처럼 보이고 카드도 모두 존재하지만, 데이터베이스 행은 여전히 이전 볼륨의 파일을 가리키고 있기 때문에 모든 첨부 파일 링크는 작동하지 않게 됩니다.
위의 Compose 파일에 명시된 이름 있는 볼륨(named volume)을 사용하면 이러한 문제를 방지할 수 있습니다. 바인드 마운트(bind mount)를 사용해도 동일한 효과를 얻을 수 있으며 일반적인 도구로 파일을 백업하기가 더 수월하지만, 한 가지 추가 단계가 필요합니다. 컨테이너 내부의 Node 프로세스는 UID 1000으로 실행되므로, root 소유의 호스트 디렉터리를 사용하면 첫 업로드 시 권한 오류가 발생합니다.
sudo chown -R 1000:1000 /opt/planka/data이 두 방식 사이의 장단점은 바인드 마운트와 이름 있는 볼륨 비교에서 다룹니다.
플랜의 디스크 용량보다 첨부 파일이 커질 경우, Planka는 S3_ENDPOINT, S3_BUCKET 및 관련 키 변수를 통해 S3 호환 스토리지에 파일을 기록할 수 있습니다. 이는 호스팅된 버킷을 가리키거나 다른 서버에 있는 자체 호스팅 MinIO 객체 스토리지를 가리킬 수 있습니다. S3를 활성화하면 기존 업로드 파일을 마이그레이션하지 않고도 파일 읽기 및 쓰기 대상이 해당 백엔드로 전환되므로, 팀이 보드를 사용하기 전에 이 설정을 결정해야 합니다.
스택을 시작하고 정상 작동 여부 확인
docker compose pull
docker compose up -d
docker compose psdocker compose ps 명령을 실행하면 postgres가 healthy 상태로, planka이 running 상태로 표시되어야 합니다. Planka가 반복적으로 재시작된다면 애플리케이션보다 데이터베이스 연결을 가장 먼저 확인해야 합니다.
docker compose logs -f planka정상적인 첫 부팅 시 데이터베이스 마이그레이션이 실행되지만, 프로덕션 설정은 noShip: true를 설정하여 포트 1337을 알리는 시작 메시지를 출력하지 않습니다. 로그만 신뢰하지 말고 Postgres에 직접 질의하여 스키마가 정상적으로 생성되었는지 확인하십시오.
docker compose exec postgres psql -U planka -d planka -c '\dt'board 및 card을 포함한 테이블 목록이 출력되면 마이그레이션이 성공한 것입니다. "Did not find any relations"라는 메시지가 나타나면 Planka가 연결되지 않은 것이므로, DATABASE_URL의 값을 .env 파일 내의 POSTGRES_USER 및 POSTGRES_PASSWORD 값과 비교하십시오.
그다음 VPS 내부가 아닌 로컬 머신에서 경로를 확인하십시오.
curl -I https://kanban.example.comHTTP/2 200은 Traefik이 인증서를 보유하고 있으며 컨테이너에 도달하고 있음을 의미합니다. Traefik이 반환하는 404 오류는 요청과 일치하는 라우터가 없음을 의미합니다. 이는 Host() 규칙이 요청한 호스트 이름과 일치하지 않거나, Traefik이 레이블을 인식하지 못했기 때문입니다. 502 오류는 라우터는 일치하지만 Traefik이 컨테이너에 도달할 수 없는 경우로, 컨테이너가 proxy 네트워크에 연결되지 않은 상황 등이 원인이 될 수 있습니다. 이제 사이트를 열고 관리자 계정으로 로그인하십시오.
버전 업데이트 전마다 pg_dump 실행하기
게시판 데이터는 두 개의 별도 저장소에 보관되므로, 백업은 Postgres 데이터베이스와 planka-data 볼륨을 모두 포함해야 합니다. 스택이 실행 중인 상태에서 데이터베이스를 덤프하십시오.
docker compose exec -T postgres pg_dump -U planka -d planka > "planka-db-$(date +%F).sql"-T 옵션은 Compose의 기본 의사 터미널(pseudo-terminal) 할당을 비활성화하여 덤프를 일반 출력 스트림으로 유지합니다.
다음은 업로드 파일입니다. Compose는 프로젝트 디렉터리 이름을 볼륨 이름 앞에 접두사로 붙이므로, 먼저 실제 볼륨 이름을 확인해야 합니다.
docker volume ls | grep planka
docker run --rm -v planka_planka-data:/data -v "$PWD":/backup alpine \
tar czf /backup/planka-files-$(date +%F).tgz -C /data .이 프로젝트는 저장소에 docker-backup.sh 및 docker-restore.sh를 포함하고 있으며, 공식 문서에서는 이를 매일 밤 cron 작업으로 설정하도록 안내합니다. 두 방식 모두 적절합니다. 다만, 한 번도 복원해 본 적 없는 백업은 의미가 없습니다. 따라서 테스트용 VPS에 한 번 복원해 보고, 로그인하여 첨부 파일을 열 수 있는지 확인하십시오. 업로드를 허용하는 모든 Compose 앱은 동일한 두 저장소를 사용합니다. 따라서 나중에 지원 데스크와 동일한 서버에 Chatwoot을 설치하더라도, 여기서 구축한 루틴을 볼륨 이름만 변경하여 그대로 적용할 수 있습니다.
버전 변경 직전에 반드시 덤프를 실행하십시오. 어젯밤에 수행한 백업은 지금 실행하려는 마이그레이션 직전의 백업과 동일하지 않습니다.
태그 고정 및 릴리스 노트 확인
해당 파일의 두 이미지 태그는 의도적으로 고정되어 있습니다.
ghcr.io/plankanban/planka:2.2.1은 2026년 10월 기준 최신 특정 릴리스입니다. Community 2.3.0 버전은 2026년 11월 4일에 보안 수정 사항을 포함하여 릴리스되었으며, 업스트림에서는 업데이트를 권장합니다. Community 2.3.1 버전은 2026년 11월 5일에 릴리스되었으며, 사용자 이름이 없는 멤버가 포함된 보드에서 카드 설명을 편집할 때 발생하는 충돌 문제를 해결했습니다. latest은 업스트림이 게시할 때마다 변경되므로, 무심코 실행한 docker compose pull 명령으로 인해 원치 않는 시점에 스키마 마이그레이션이 수행될 수 있습니다. 숫자를 변경하기 전에 릴리스 노트를 읽어보십시오. 주요 변경 사항과 보안 수정 사항이 그곳에 설명되어 있기 때문입니다. 2.0.3 버전은 보안 릴리스로 게시되었는데, 이는 우연히 적용하기보다 반드시 읽어봐야 할 유형의 정보입니다. 2026년 8월에 릴리스된 2.2.1 버전도 마찬가지입니다. 이 버전은 로컬 파일 스토리지를 사용하는 인스턴스에서 로그인한 사용자가 임의의 파일을 읽을 수 있는 경로 탐색 취약점을 수정했습니다. 이 가이드의 설정이 바로 그러한 방식이며, 권고문에는 2.1.1 이하 버전이 영향을 받는다고 명시되어 있습니다. 2.1.x 버전에서 넘어오는 경우 2.2.0 릴리스 노트를 먼저 읽어보십시오. 해당 릴리스는 SSO로만 로그인했던 사용자를 비활성화하며, 관리자가 비밀번호를 부여하고 다시 활성화하기 전까지는 사용할 수 없게 만들기 때문입니다. 업스트림이 이미지를 게시하는 경우 태그 고정은 쉽습니다. 프로젝트에서 이미지를 제공하지 않는다면 체크아웃한 git 태그에서 직접 빌드한 openGym과 같이 추가적인 단계를 거쳐 동일한 수준의 관리를 수행해야 합니다.
postgres:16-alpine을 메이저 버전에 고정하는 데에는 더 중요한 이유가 있습니다. Postgres는 메이저 버전에 종속된 형식으로 데이터 디렉터리를 기록하며, 서버는 다른 버전으로 작성된 디렉터리를 여는 것을 거부합니다. postgres:latest를 작성하고 태그가 16을 넘어가면 컨테이너는 시작되지 않습니다. 예를 들어 17 이미지의 경우 다음과 같은 메시지와 함께 중단됩니다.
FATAL: database files are incompatible with server
DETAIL: The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17.데이터가 손실되는 것은 아니며, 재시작한다고 해결되지도 않습니다. 새로운 Postgres 메이저 버전으로 이동하려면 이전 버전에서 덤프를 생성한 후 새 데이터 디렉터리에 복원하거나, 덤프 없이 데이터를 변환하지만 이전 및 새 서버 바이너리가 모두 필요한 pg_upgrade를 실행하거나, 새 버전을 실행하는 서버로 논리적 복제를 수행한 뒤 전환해야 합니다. 각 경로는 이미지 풀의 부작용이 아닌 계획된 마이그레이션이어야 합니다. 논리적 복제를 사용하면 새 서버가 동기화되는 동안 이전 서버를 계속 실행할 수 있습니다.
새로 시작하는 것이 아니라 기존 Planka 1.x 설치를 이전하는 경우, 해당 업그레이드는 프로젝트 문서에 별도의 절차가 명시되어 있습니다. 사전에 백업을 받아두지 않으면 1 버전으로 되돌릴 방법은 없습니다.
실패 유형 및 확인 가능한 메시지
Planka가 반복적으로 재시작되며 로그에 데이터베이스 관련 오류가 나타납니다. DATABASE_URL에 설정된 자격 증명이 Postgres 환경 설정과 일치하지 않는 경우입니다. POSTGRES_PASSWORD는 데이터 디렉터리가 처음 초기화될 때만 적용된다는 점에 유의하십시오. 따라서 잘못된 첫 부팅 이후에 변수를 수정해도 아무런 변화가 없습니다. 데이터베이스 역할의 비밀번호를 ALTER ROLE을 사용하여 설정된 비밀번호와 일치하도록 변경하십시오. db-data 볼륨을 삭제하는 것은 보존할 데이터가 없는 일회성 설치 환경에서만 고려할 수 있는 방법입니다.
로그인은 성공하지만 보드가 로드되지 않습니다. BASE_URL가 브라우저 주소창의 주소와 일치하지 않아 서버가 소켓의 origin을 거부하는 경우입니다. 브라우저 콘솔에서 /socket.io/으로 향하는 요청이 실패하는 것을 확인할 수 있습니다.
다른 기능은 정상이나 파일 업로드가 실패합니다. 바인드 마운트된 디렉터리의 소유권이 root로 되어 있는 경우입니다. 호스트 디렉터리에서 sudo chown -R 1000:1000를 실행한 뒤 컨테이너를 재시작하십시오.
업그레이드 후 첨부 파일이 사라졌습니다. /app/data가 기존 업로드 볼륨에 연결되지 않은 경우입니다. 해당 볼륨을 다시 연결하거나 백업에서 파일을 복구하십시오. 이후 이미지 태그를 변경하기 전에 반드시 명명된 볼륨(named volume)을 사용하십시오.
Traefik이 404 오류를 반환합니다. 요청과 일치하는 라우터가 없는 경우입니다. Host() 규칙이 DNS 레코드와 일치하지 않거나, 라벨이 Traefik에 전달되지 않았을 수 있습니다. docker compose config을 확인하면 치환된 라벨을 볼 수 있으며, 여기서 오타를 발견할 수 있습니다. 502 오류는 라우팅은 성공했으나 컨테이너에 도달할 수 없는 경우이므로, 컨테이너가 proxy 네트워크에 포함되어 있는지 확인하십시오.
알림이나 웹훅이 도착하지 않습니다. Planka 2는 내부 필터를 통해 나가는 HTTP 요청을 처리하며, 기본 차단 목록에는 localhost 및 postgres이 포함되어 있습니다. localhost을 대상으로 하는 웹훅은 설계상 차단됩니다. OUTGOING_ALLOWED_HOSTS를 설정하면 해당 목록에 없는 모든 호스트가 차단됩니다. 웹훅 대상을 다른 컨테이너의 서비스 이름으로 지정하고, 허용 목록을 사용하는 경우 필터를 제거하는 대신 해당 이름을 OUTGOING_ALLOWED_HOSTS에 추가하십시오.
일단 실행되면 운영 부하는 적습니다. 릴리스 노트를 주기적으로 확인하고, 업그레이드 전에는 항상 데이터베이스를 덤프하십시오. Docker 서비스 자체가 부팅 시 활성화되어 있다면 restart: unless-stopped 설정 덕분에 재부팅 후 스택이 자동으로 복구됩니다. 재부팅 후 스택이 올라오지 않는 경우에 대해서는 재부팅 후 자동으로 시작되는 Compose 스택을 참조하십시오.
FAQ
로그인 후 Planka가 무한 로딩되는 이유는 무엇입니까?
자격 증명은 승인되었으나 실시간 연결이 실패한 경우입니다. 브라우저는 페이지의 오리진으로 소켓을 열지만, Planka는 BASE_URL에서 허용된 소켓 오리진을 파생합니다. 따라서 해당 변수를 http://localhost:3000으로 둔 채 https://kanban.example.com로 사이트에 접속하면 서버가 연결을 거부합니다. 개발자 도구 콘솔에는 /socket.io/에 대한 요청 실패가 표시됩니다. BASE_URL를 끝에 슬래시가 없는 정확한 공용 주소로 설정하고, TRUST_PROXY=true을 추가하여 애플리케이션이 리버스 프록시의 X-Forwarded-Proto 헤더를 준수하도록 한 뒤 docker compose up -d를 실행하십시오.
첫 번째 Planka 관리자 계정은 어떻게 생성합니까?
버전 1.13부터는 관리자가 자동으로 생성되지 않습니다. 비밀번호, 이름, 사용자 이름 변수를 일치시켜 DEFAULT_ADMIN_EMAIL을 설정한 후 스택을 시작하거나, docker compose run --rm planka npm run db:create-admin-user를 실행하여 안내에 따라 입력하십시오. 대화형 명령은 공유 서버에서 더 안전합니다. 비밀번호가 docker inspect가 읽을 수 있는 컨테이너의 구성 환경으로 전달되지 않기 때문입니다. 설정 후 DEFAULT_ADMIN_EMAIL을 유지하면 해당 계정의 이름, 역할, 이메일 주소 변경이 방지되며 인터페이스에서 삭제할 수 없게 됩니다. 설정 후에는 DEFAULT_ADMIN_PASSWORD을 제거하십시오. 이 값이 설정된 상태로 두면 시작할 때마다 해당 계정의 비밀번호가 초기화됩니다.
Planka는 첨부 파일과 아바타를 어디에 저장합니까?
Planka 2에서 업로드된 모든 파일은 컨테이너 내부의 /app/data 아래에 저장됩니다. 여기에는 첨부 파일, 사용자 아바타, 보드 배경이 포함됩니다. 해당 경로를 명명된 볼륨(named volume)으로 마운트하십시오. 명시적인 마운트가 없으면 Docker 이미지는 익명 볼륨을 사용하며, 이는 docker compose down 이후 docker compose up를 실행할 때 자동으로 다시 연결되지 않습니다. 바인드 마운트도 가능하지만, Node 프로세스가 UID 1000으로 실행되므로 호스트 디렉터리에 sudo chown -R 1000:1000을 실행해야 합니다. 그렇지 않으면 권한 오류로 인해 업로드에 실패합니다.
자가 호스팅 Planka에는 어느 정도의 RAM이 필요합니까?
프로젝트의 기술 FAQ는 소규모 팀의 경우 최소 2 GB의 RAM과 10 GB의 저장 공간을 권장합니다. 기본 Docker 배포는 Node 프로세스, 연결당 백엔드 프로세스를 갖춘 Postgres 서버, 발신 요청 필터링을 위한 내부 Squid 프록시를 실행합니다. 정상적인 운영을 일주일간 수행한 후 docker stats --no-stream를 실행하여 실제 사용량을 기준으로 크기를 조정하십시오. 첨부 파일은 계속 증가하므로 메모리보다 디스크 사용량을 더 면밀히 모니터링해야 합니다.
데이터를 잃지 않고 Planka를 업그레이드하려면 어떻게 해야 합니까?
업그레이드 직전에 데이터베이스를 덤프하고 업로드 볼륨을 아카이브하십시오. 어젯밤의 백업 일정에 의존해서는 안 됩니다. docker compose exec -T postgres pg_dump -U planka -d planka > planka-db.sql을 사용하고, 리다이렉트된 출력에 의사 터미널 할당을 비활성화하기 위해 -T를 유지하십시오. 건너뛰는 모든 버전에 대한 릴리스 노트를 읽고, 이미지 태그를 latest 대신 특정 릴리스 버전으로 변경한 다음 docker compose pull과 docker compose up -d을 실행하여 마이그레이션 로그를 모니터링하십시오. Postgres 태그는 메이저 버전에 고정하십시오. 서버는 다른 메이저 버전으로 작성된 데이터 디렉터리를 열지 않습니다.