Galpi
설치와 처음 설정
Docker Compose로 서버 한 대에 갈피를 띄우고, 로그에 찍힌 설정 토큰으로 첫 관리자가 되어 위저드로 설정해요.
필요한 것
- 리눅스 서버 한 대(2 vCPU, 4 GB 메모리, 디스크 20 GB면 시작할 수 있어요)와 Docker(Compose 포함). 없으면
curl -fsSL https://get.docker.com | sh. - 도메인 이름 하나. DNS에서 이 서버의 공인 IP를 가리키게 해요(예:
galpi.example.com). - 바깥에서 80, 443번 포트가 열려 있어야 해요(Let's Encrypt). 내장 S3를 노드에 열면 9443번도요.
- 채팅 VM을 돌릴 곳: Fly Sprites 토큰, 또는 노드로 붙일 서버(E2B는 KVM 필요, Sysbox는 KVM 없이). 나중에 정해도 돼요. → VM을 돌릴 곳
세 단계
cd deploy
cp .env.example .env && chmod 600 .env # 1. GALPI_DOMAIN, SECRETS_KEY 등을 채워요
./build.sh # 2. 이미지를 만들어요 (몇 분)
docker compose up -d # 3. 띄워요
.env에서 꼭 채울 것은 GALPI_DOMAIN과 SECRETS_KEY(openssl rand -base64 32), 갈피 안 저장소를 쓰면 FORGEJO_ADMIN_PASSWORD(openssl rand -hex 24)예요. 나머지는 처음 설정 화면에서 정해도 되고, 화면에서 저장한 값이 환경 변수보다 먼저예요.
화면에서 저장한 비밀값(토큰, 비밀번호)을 이 키로 잠가요. 잃으면 저장한 비밀값을 다시 넣어야 하고, 백업에서 되살릴 때도 같은 키가 있어야 해요.
무엇을 같이 띄울지는 .env의 COMPOSE_PROFILES로 골라요. 기본은 https,git이에요.
| 프로필 | 뜨는 것 | 언제 |
|---|---|---|
| (늘) | galpi |
갈피 서버와 화면 |
https |
caddy |
자동 HTTPS. 다른 프록시를 쓰면 빼요 |
git |
forgejo, forgejo-restore, forgejo-backup |
갈피 안 저장소(빈 저장소로 시작)와 그 백업 |
s3 |
s3, s3-bucket |
내장 S3(versitygw). 작은 설치용. 큰 설치는 바깥 S3를 S3_*에 넣어요 |
처음 열기
-
몇십 초 뒤
https://<GALPI_DOMAIN>을 열면 설정 토큰을 넣는 화면이 나와요. 인증서는 Caddy가 첫 접속 때 받아요. -
토큰은 로그와
DATA_DIR/setup-token(mode 600)에 있어요.bashdocker compose logs galpi | grep '\[setup\]' -
토큰과 이메일을 넣으면 그 사람이 첫 시스템 관리자가 되고(메일 없이 바로 로그인돼요) 위저드가 이어져요. 토큰은 한 번만 써요.
이미 사람이 들어온 서버(로그인한 사람이나 프로젝트가 있는 서버)는 설정을 마친 것으로 봐서, 기존 설치를 새 버전으로 올려도 위저드가 뜨지 않아요.
위저드의 단계
| 단계 | 정하는 것 | 확인 |
|---|---|---|
| 서버 주소 | PUBLIC_URL, VM이 갈피를 부를 주소 VM_CALLBACK_URL(노드면 node) |
|
| 메일 | SMTP_URL, MAIL_FROM. 비우면 메일은 서버 로그에만 |
나에게 시험 메일 보내기 |
| 로그인 | 이메일 코드, OIDC, 둘 다 | 발급자 정보를 읽고 리디렉트 주소를 보여 줘요 |
| VM | Sprites, E2B 노드, Sysbox 노드 중 하나. 노드는 가입 명령과 VM 크기 | Sprites는 토큰으로 목록을 읽어 봐요 |
| 파일 저장소 | S3 주소·버킷·키. 비우면 서버 디스크. DB 복제(Litestream)도 여기로 | 시험 파일을 쓰고 읽고 지워요 |
| LLM | 기본 모델(Anthropic 또는 OpenAI 호환), 등급별(Fast·Smart·Deep) 모델, 무료 모델, 하루 한도, 모든 채팅의 에이전트 지침 | 짧은 질문을 실제로 보내 봐요 |
| 정책과 예산 | 가입 도메인, 게스트, 프로젝트를 누가 만드는지, 프로젝트 없는 채팅, ChatGPT 연동, 채팅 보관 기간, 보관소에서 지운 것을 남겨 두는 기간과 한도, 질문 수 한도, 예산 | |
| 미리보기 | GeoDNS, CDN, 나중에. 미리보기 도메인 | |
| 갈피 안 저장소 | 켜고 끄기, Forgejo 주소와 관리 계정 | 관리 계정으로 API에 들어가 봐요 |
| 마무리 | 요약, 다시 시작, 첫 프로젝트 만들기 |
단계를 옮기면 그 단계에서 바꾼 값을 먼저 저장해요. 저장할 수 없으면(값이 틀렸거나 확인이 먼저 필요하면) 그 단계에 머물며 이유를 보여 줘요. 정한 값은 나중에 시스템 관리 → 설정에서 다시 바꿔요.


포트와 볼륨
| 무엇 | 포트 | 볼륨 | 메모 |
|---|---|---|---|
galpi |
127.0.0.1:8080 (GALPI_HTTP_BIND) |
galpi-data:/data |
DB와 저장한 설정. S3가 있으면 Litestream이 계속 복제해요 |
caddy |
80, 443/tcp, 443/udp, 9443 | caddy-data, caddy-config |
인증서가 caddy-data에 있어요 |
forgejo |
없음(갈피만 안쪽 망으로) | forgejo-data |
저장소, DB |
s3 |
127.0.0.1:7070(바깥은 Caddy의 9443) |
s3-data |
버킷이 폴더로 보여요 |
다른 프록시 뒤에 둘 때
COMPOSE_PROFILES에서https를 빼고GALPI_HTTP_BIND를 프록시가 닿는 주소로 바꿔요. 이미지가 production으로 돌아서 로그인 쿠키에Secure가 붙어요.http://로는 로그인이 되지 않아요.- 프록시는 TLS를 끝내고 스트림을 모아 두지 않아야 해요(nginx면
proxy_buffering off).X-Forwarded-For는 접속한 사람의 주소로 새로 써요(proxy_set_header X-Forwarded-For $remote_addr). - 로그인 코드 요청 한도처럼 주소마다 세는 것은, 연결한 쪽이 믿는 프록시일 때만
X-Forwarded-For의 클라이언트 주소로 세요. 같은 호스트나 사설망의 프록시(루프백, 사설 주소)는 늘 믿어요. 공인 주소의 프록시(클라우드 부하 분산기, 다른 호스트의 프록시)는GALPI_TRUSTED_PROXIES에 주소나 네트워크를 쉼표로 적어요(34.120.0.0/16,2001:db8::1). 적지 않으면 그 뒤의 모든 사람이 프록시 주소 하나로 세져서, 로그인 화면을 한꺼번에 연 사람이 많을 때 막힐 수 있어요. 클라이언트가 직접 닿을 수 있는 주소는 적지 마세요. - 갈피는 HTTP/1.1만 말해요. 프록시에서 갈피로 h2c를 켜지 마세요.
- 갈피는 쉬는 연결을 130초 열어 둬요(
GALPI_KEEPALIVE_MS). 프록시가 먼저 닫아야 해요. nginx는keepalive_timeout을 130초보다 짧게,proxy_http_version 1.1과proxy_set_header Connection ""도 넣어요. - 요청 본문은 들어 있는 Caddy처럼 둬요: nginx면
client_max_body_size 600m,client_header_timeout 30s,client_body_timeout 60s, 답변 스트림이 끊기지 않게proxy_read_timeout 1h.
.env에 CADDY_TLS=internal이면 Caddy 자체 인증서로 HTTPS를 해요(브라우저 경고). 노드의 VM은 그 인증서를 믿지 않으니 VM_CALLBACK_URL=node를 써요. 운영에서는 쓰지 마세요.
컨테이너 재시작 정책
restart: unless-stopped는 지우지 마세요. 화면의 다시 시작은 서버를 종료 코드 75로 끝내고, 이 정책이 다시 띄워요.
다음으로
설치 방법 · 서버 설치 · 배포 · 도커 · docker compose