안녕하세요! 스타듀밸리의 힐링과 마인크래프트의 모험을 섞어놓은 듯한 중독성 최강의 게임, 코어키퍼(Core Keeper)를 친구들과 24시간 즐기고 계신가요?
GCP(Google Cloud Platform)를 활용해 VM 인스턴스를 만들고, 우분투(Ubuntu) 환경에서 도커(Docker)를 이용해 24시간 돌아가는 데디케이티드 서버를 구축하는 기초 과정을 다뤘습니다. 하지만 “순정” 상태의 서버는 어딘가 아쉽고, 내가 친구랑 하던 맵을 그대로 가져오지 못해 답답하셨을 겁니다.
오늘은 그 해결책으로 서버에 모드(Mod)를 적용하는 방법과 내 PC에 있던 기존 세이브 파일(월드)을 서버로 옮기는 방법을 아주 상세하게 정리해 드리겠습니다. 특히 모드 적용 시 발생하는 환경 변수 오류 해결 꿀팁(override.env)까지 담았으니 끝까지 따라와 주세요!
1. 준비 단계: mod.io API 키 발급받기
코어키퍼의 데디케이티드 서버에 모드를 적용하려면, 모드 플랫폼인 mod.io와 서버를 연결해 줄 열쇠(API Key)가 필요합니다.
1) mod.io 접속 및 로그인
먼저 mod.io 코어키퍼 페이지에 접속하여 로그인을 진행합니다. 보통 스팀(Steam) 계정과 연동하여 로그인하면 편리합니다.
2) API Access 토큰 확인
로그인 후 우측 상단의 프로필 아이콘을 클릭하고 API Access 메뉴로 이동합니다. 혹은 아래 직링크를 이용하세요.
페이지에 접속하면 아래 두 가지 정보를 찾아 메모장 등에 복사해 둡니다.
- API Key:
Request버튼을 눌러 생성된 키 (눈 모양 아이콘을 눌러 확인 후 복사) - API URL:
API Path:우측에 적힌 주소 (예:https://u-*.modapi.io/v1)
2. 서버 설정 파일 수정: .env 및 override.env
이제 GCP 콘솔(SSH)로 돌아가서 도커 컨테이너 설정을 변경해야 합니다. 여기서 많은 분들이 실수하는 부분이 있으니 주의 깊게 봐주세요.
1) 적용할 모드 이름(ID) 찾기
.env 파일에 모드를 적기 위해서는 모드의 정확한 ‘ID’를 알아야 합니다.
mod.io에서 원하는 모드를 검색하고 URL을 확인해 보세요.
| 모드 이름 | URL 예시 | 우리가 필요한 ID |
| Better Text Input | .../corekeeper/m/better-text-input | better-text-input |
| Enemy Health Bars | .../corekeeper/m/healthbars | healthbars |
| CoreLib (필수) | .../corekeeper/m/core-lib | core-lib |
중요! 대부분의 모드는
core-lib같은 선행 모드를 필요로 합니다. 선행 모드를 누락하면 서버가 열리지 않으니 꼼꼼히 챙겨주세요.
2) override.env 파일 생성 (핵심 꿀팁)
일반적으로 .env 파일만 수정하면 된다고 생각하기 쉽지만, 도커 설정상 MODS_ENABLED=true가 제대로 읽히지 않아 모드 설치가 무시되는 버그가 발생할 수 있습니다. 이를 해결하기 위해 override.env 파일을 새로 만들어 덮어씌우는 방식을 추천합니다.
터미널에서 docker-compose.yml 파일이 있는 경로로 이동한 뒤 아래 명령어를 입력합니다.
vim override.env
그리고 아까 복사한 API 정보와 모드 리스트를 아래 양식에 맞춰 작성합니다.
코드 스니펫
MODS_ENABLED=true
MODIO_API_KEY=여기에_아까_복사한_API_KEY_붙여넣기
MODIO_API_URL=여기에_아까_복사한_API_URL_붙여넣기
MODS=healthbars,corelibrewiredextension,coreliblocalization,corelibcommands,better-text-input,core-lib
- MODS: 쉼표(
,)로 구분하여 모드 ID들을 나열합니다. 띄어쓰기 없이 작성하세요. SERVER_PORT는 게임 ID(Game ID)로 접속할 경우 필수는 아니므로 생략해도 무방합니다.
3) 도커 재실행 및 로그 확인
설정 파일을 저장(:wq)하고 나왔다면, 컨테이너를 재시작하여 모드를 다운로드하게 합니다.
# 컨테이너 종료 및 삭제
sudo docker compose down
# 컨테이너 데몬 모드로 다시 실행
sudo docker compose up -d
# 로그 확인 (모드 설치 과정 모니터링)
sudo docker logs -f core-keeper-dedicated
로그창에 Installing mods... 메시지와 함께 Installed CoreLib... 같은 성공 메시지가 뜨면 완벽하게 적용된 것입니다!
3. 기존 세이브 파일(맵) 서버로 옮기기
친구들과 열심히 일궈놓은 맵을 버리고 새로 시작할 수는 없겠죠? 내 컴퓨터(로컬)에 있는 맵 데이터를 서버로 이사시키는 방법입니다.
1) 서버의 기존 월드 데이터 초기화
먼저 충돌 방지를 위해 서버에 생성되어 있는 임시 월드 데이터를 삭제합니다.
sudo rm /root/server-data/worlds/*
2) 내 PC에서 월드 파일 찾기
윈도우 탐색기를 열고 아래 경로로 들어갑니다. (AppData 폴더가 안 보이면 ‘보기’ 탭에서 ‘숨긴 항목’을 체크하세요.)
- 경로:
C:\Users\[사용자명]\AppData\LocalLow\Pugstorm\Core Keeper\Steam\[스팀ID]\worlds
이 폴더를 보면 0.world.gzip, 1.world.gzip 등의 파일이 있습니다.
- 0번: 게임 내 첫 번째 슬롯 월드
- 1번: 게임 내 두 번째 슬롯 월드
내가 옮기고 싶은 월드가 게임 내에서 ‘4번째 슬롯’에 있었다면 3.world.gzip 파일과 3.world.gzip.pugbackup 파일을 복사하면 됩니다.
3) 서버로 파일 업로드 및 이름 변경
파일질라(FileZilla)나 SCP 명령어를 사용하여 위에서 찾은 두 파일을 서버의 /root/server-data/worlds/ 경로로 업로드합니다.
업로드 후, 서버에서 파일 이름을 0번(첫 번째 슬롯)으로 변경해 주어야 서버가 이를 메인 월드로 인식합니다.
# 파일이 있는 경로로 이동
cd /root/server-data/worlds/
# 이름 변경 (예: 3번 월드를 0번으로 변경)
mv 3.world.gzip 0.world.gzip
mv 3.world.gzip.pugbackup 0.world.gzip.pugbackup
4) 최종 접속 확인
이제 모든 준비가 끝났습니다. 도커 컨테이너가 실행 중인 상태에서 아래 명령어로 Game ID를 확인하고 접속해 보세요.
sudo docker exec -it core-keeper-dedicated cat /home/steam/core-keeper-dedicated/GameID.txt
기존 맵의 지형과 아이템이 그대로 유지된 채, 모드 기능까지 더해진 쾌적한 24시간 서버를 즐기실 수 있습니다.
4. 관련 링크 모음
- 참고한 GitHub 레포지토리 (Docker Image): escapingnetwork/core-keeper-dedicated
- mod.io (코어키퍼 모드 사이트): https://mod.io/g
- 스팀 커뮤니티 (월드 전송 가이드): Guide for Transferring Worlds
5. 자주 묻는 질문 (FAQ)
Q1. 모드를 적용했는데 서버 접속 시 ‘버전 불일치’ 오류가 뜹니다.
A1. 이는 서버에 설치된 모드 버전과 클라이언트(내 PC)에 설치된 모드 버전이 다르거나, 구성이 일치하지 않아서 발생합니다. 서버는 도커가 재시작될 때 최신 버전의 모드를 다운로드합니다. 따라서 내 PC의 모드도 최신 버전으로 업데이트되었는지 확인해 주세요. 또한, override.env에 적은 모드 리스트와 내 PC의 활성화된 모드 리스트가 정확히 일치해야 접속이 원활합니다.
Q2. .env 파일 대신 왜 override.env를 써야 하나요?
A2. docker-compose 실행 시 환경 변수를 불러오는 우선순위나 캐싱 문제로 인해, 기존 .env 파일을 수정해도 도커 컨테이너 내부에 MODS_ENABLED=true 값이 제대로 전달되지 않는 경우가 있습니다. 이럴 때 MODS_ENABLED=false로 인식되어 모드 설치 과정을 건너뛰게 됩니다. override.env를 생성하여 명시적으로 환경 변수를 덮어씌워 주면 이 문제를 확실하게 해결할 수 있어, 모드 적용 실패 확률을 획기적으로 낮출 수 있습니다.
Q3. 서버를 껐다 켜면 데이터가 날아가나요?
A3. 아니요, 날아가지 않습니다. 우리가 도커 설정(2편)을 할 때 볼륨(Volume) 설정을 통해 서버의 데이터 폴더(/root/server-data)를 호스트(GCP VM)의 폴더와 연결해 두었기 때문입니다. 컨테이너를 삭제하고 다시 만들어도, server-data 폴더 안에 있는 월드 파일(worlds)과 설정 파일들은 안전하게 보존됩니다. 안심하고 재부팅 하셔도 됩니다.
Q4. 맵을 옮겼는데 지도가 밝혀진 부분이 다 사라졌어요.
A4. 월드 파일(world.gzip)만 옮길 경우, 맵의 지형 정보는 유지되지만 내가 탐험해서 밝혀놓은 ‘지도(Map)’ 데이터는 초기화될 수 있습니다. 탐험 정보를 완벽하게 복원하려면 worlds 폴더 외에 maps 또는 map_data 관련 폴더도 함께 옮겨주어야 합니다. 다만, 서버 환경과 로컬 환경의 사용자 ID 매칭 문제로 인해 완벽한 복구는 까다로울 수 있으며, 핵심 플레이 데이터(아이템, 건축물)는 월드 파일만으로도 충분히 보존됩니다.
Q5. 모드를 추가하거나 빼고 싶을 땐 어떻게 하나요?
A5. 아주 간단합니다. 서버를 잠시 중지(docker compose down)한 뒤, override.env 파일을 열어 MODS= 부분에 있는 리스트를 수정해 주면 됩니다. 새로운 모드 ID를 추가하거나, 필요 없는 모드 ID를 지우세요. 그 후 다시 서버를 실행(docker compose up -d)하면, 서버가 부팅되면서 변경된 리스트에 맞춰 모드를 자동으로 설치하거나 삭제합니다.
참고 사이트 및 URL
- mod.io API Access: https://mod.io/me/access
- GitHub Core Keeper Docker: https://github.com/escapingnetwork/core-keeper-dedicated
이제 더 이상 호스트가 올 때까지 기다리지 마세요! 여러분만의 24시간 코어키퍼 세상에서 즐거운 모험 되시길 바랍니다.
댓글 남기기