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을 돌릴 곳

세 단계

bash
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)예요. 나머지는 처음 설정 화면에서 정해도 되고, 화면에서 저장한 값이 환경 변수보다 먼저예요.

SECRETS_KEY는 따로 보관해요

화면에서 저장한 비밀값(토큰, 비밀번호)을 이 키로 잠가요. 잃으면 저장한 비밀값을 다시 넣어야 하고, 백업에서 되살릴 때도 같은 키가 있어야 해요.

무엇을 같이 띄울지는 .env의 COMPOSE_PROFILES로 골라요. 기본은 https,git이에요.

프로필 뜨는 것 언제
(늘) galpi 갈피 서버와 화면
https caddy 자동 HTTPS. 다른 프록시를 쓰면 빼요
git forgejo, forgejo-restore, forgejo-backup 갈피 안 저장소(빈 저장소로 시작)와 그 백업
s3 s3, s3-bucket 내장 S3(versitygw). 작은 설치용. 큰 설치는 바깥 S3를 S3_*에 넣어요

처음 열기

  1. 몇십 초 뒤 https://<GALPI_DOMAIN>을 열면 설정 토큰을 넣는 화면이 나와요. 인증서는 Caddy가 첫 접속 때 받아요.

  2. 토큰은 로그와 DATA_DIR/setup-token(mode 600)에 있어요.

    bash
    docker compose logs galpi | grep '\[setup\]'
    
  3. 토큰과 이메일을 넣으면 그 사람이 첫 시스템 관리자가 되고(메일 없이 바로 로그인돼요) 위저드가 이어져요. 토큰은 한 번만 써요.

이미 사람이 들어온 서버(로그인한 사람이나 프로젝트가 있는 서버)는 설정을 마친 것으로 봐서, 기존 설치를 새 버전으로 올려도 위저드가 뜨지 않아요.

위저드의 단계

단계 정하는 것 확인
서버 주소 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로 끝내고, 이 정책이 다시 띄워요.

다음으로

  • VM을 돌릴 곳: Sprites, E2B 노드, Sysbox 노드
  • 운영: 로그인, 예산, 백업·복원, 업데이트
  • 폐쇄망: 인터넷이 없는 곳에 설치
Esc