여러분만의 Git 서버.
저장소가 곧 조직도다.

문제를 해결하는 가장 작은 것부터 시작하십시오. 그 위에 얹는 모든 계층은 여러분이 운영해야 하는 서비스이기 때문입니다. SSH를 통한 베어 저장소는 이미 가지고 있는 서버에서 명령 하나면 끝나며, 인증과 이력, 푸시 권한을 갖춘 진짜 Git 원격 저장소를 제공합니다. 웹 애플리케이션도, 데이터베이스도, 끝없는 업그레이드도 없고, sshd 외에는 패치할 것도 없습니다. 커밋을 노트북과 플랫폼 밖으로 꺼내고 싶은 1인 사용자라면 이것으로 완전한 답이 되며, 2단계 이후로는 더 읽지 않아도 됩니다.

# On the server, as an unprivileged user:
mkdir -p ~/git/project.git && cd ~/git/project.git
git init --bare

# On your laptop:
git remote add origin ssh://user@git.example.com/~/git/project.git
git push -u origin main

두 번째 사람이 관여하거나, 베어 저장소 디렉터리로는 할 수 없는 네 가지 — 브라우저로 이력 살펴보기, 풀 리퀘스트로 변경 사항 리뷰하기, 코드 옆에서 이슈 추적하기, 한 사람에게 저장소 하나에 대한 접근 권한 부여하기 — 중 하나라도 원할 때 포지가 필요해집니다. 이는 기능 면에서도 진짜 발전이고 운영 부담 면에서도 진짜 증가입니다. 신중하게 선택하십시오:

Forgejo와 Gitea는 조상이 같아서 일상적인 사용에서는 여전히 거의 똑같아 보입니다. Forgejo는 2024년 초 하드 포크가 되었고 베를린에 등록된 비영리 협회인 Codeberg e.V.가 소유하고 있으며, Gitea는 상표를 소유하고 기여자에게 저작권 양도를 요구하는 영리 기업이 개발합니다. 둘 다 좋은 소프트웨어입니다. 다만 그중 관리 주체의 이해관계가 여러분이 이 페이지를 읽는 이유와 맞아떨어지는 쪽은 하나뿐입니다.

이 가이드의 나머지 부분은 Forgejo를 사용합니다. 2단계부터 6단계까지의 내용은 Gitea에도 거의 그대로 적용됩니다 — 컨테이너 이름과 몇몇 환경 변수만 바뀔 뿐, 전체적인 형태는 달라지지 않습니다.

Forgejo, PostgreSQL, Caddy. Forgejo는 저장소를 보관하고 인터페이스를 제공하며, PostgreSQL은 Git 객체가 아닌 모든 것을 보관하고, Caddy는 TLS를 종료하고 두 번 요청할 필요 없이 인증서를 발급받습니다. PostgreSQL은 의도적으로 호스트에 공개되지 않습니다. 그것을 필요로 하는 단 하나의 컨테이너에서만, 이름을 통해, Compose 네트워크로만 접근할 수 있습니다.

/srv/forgejo/.env

FORGEJO_DOMAIN=git.example.com
FORGEJO_VERSION=15                             # the LTS line; 16 is current stable
POSTGRES_PASSWORD=$(openssl rand -base64 32)   # paste the value, do not leave the $( )

/srv/forgejo/docker-compose.yml

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:${FORGEJO_VERSION}
    container_name: forgejo
    environment:
      USER_UID: 1000
      USER_GID: 1000
      FORGEJO__database__DB_TYPE: postgres
      FORGEJO__database__HOST: db:5432
      FORGEJO__database__NAME: forgejo
      FORGEJO__database__USER: forgejo
      FORGEJO__database__PASSWD: ${POSTGRES_PASSWORD}
      FORGEJO__server__DOMAIN: ${FORGEJO_DOMAIN}
      FORGEJO__server__ROOT_URL: https://${FORGEJO_DOMAIN}/
      FORGEJO__server__SSH_DOMAIN: ${FORGEJO_DOMAIN}
      FORGEJO__server__SSH_PORT: "2222"          # what clones will say
      FORGEJO__server__SSH_LISTEN_PORT: "22"     # what the container listens on
      FORGEJO__service__DISABLE_REGISTRATION: "true"
      FORGEJO__repository__DEFAULT_PRIVATE: private
      FORGEJO__security__INSTALL_LOCK: "true"
    restart: unless-stopped
    volumes:
      - ./data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:3000:3000"    # web, reached only by Caddy
      - "2222:22"                # git over SSH, public
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    container_name: forgejo-db
    environment:
      POSTGRES_USER: forgejo
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: forgejo
    restart: unless-stopped
    volumes:
      - ./postgres:/var/lib/postgresql/data
    # No ports: block. This is the point.

  caddy:
    image: caddy:2-alpine
    container_name: forgejo-caddy
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy-data:/data
      - ./caddy-config:/config

/srv/forgejo/Caddyfile

git.example.com {
    encode zstd gzip
    request_body {
        max_size 512MB          # raise it if you push large repositories
    }
    reverse_proxy 127.0.0.1:3000
}

이 두 SSH 관련 줄은 사람들이 흔히 잘못 설정하는 부분이니 두 번 읽어볼 가치가 있습니다. SSH_LISTEN_PORT는 컨테이너 내부의 포트로, Forgejo의 내장 SSH 서버가 바인딩하는 곳입니다. SSH_PORT는 Forgejo가 보여주는 클론 URL에 표시하는 포트로, 포트 매핑의 공개 측과 일치해야 합니다. 이 둘이 어긋나면 사용자가 복사해서 붙여넣는 그 한 가지만 빼고 나머지는 전부 작동합니다.

띄운 다음, 명령줄에서 관리자를 생성하십시오. 웹 설치 프로그램은 사용하지 마십시오. 새 인스턴스에서는 호스트네임을 찾아낸 누구든 그것에 접근할 수 있고, 그것을 통해 처음 생성된 계정이 관리자가 됩니다 — 굳이 뛰어들 필요 없는 경쟁입니다. 위 파일의 INSTALL_LOCK이 컨테이너가 시작되기도 전에 이를 차단합니다.

docker compose up -d
docker compose logs -f forgejo        # wait for "Starting new Web server"

docker compose exec -u git forgejo forgejo admin user create \
  --admin --username you --email you@example.com --random-password

브라우저에서 호스트네임을 열고, 출력된 비밀번호로 로그인한 다음 바로 변경하십시오. 그런 다음 작동하는 인스턴스를 폐쇄된 인스턴스로 바꿔주는 설정들을 하나씩 살펴보십시오 — 대부분은 위의 환경 변수 블록에서 이미 설정되어 있지만, 그냥 넘겨짚기보다는 하나하나 확인해 볼 가치가 있습니다:

기억해 둘 만한 경로 하나. 실제 사용되는 설정 파일은 호스트의 ./data/gitea/conf/app.ini에 있습니다. Forgejo는 기존 설치와의 호환성을 위해 gitea라는 디렉터리 이름을 그대로 유지했으며, 이는 누구나 딱 한 번은 놀라게 되는 부분입니다. FORGEJO__section__KEY 형태의 환경 변수는 시작할 때 그 파일에 기록되므로, Compose 파일만으로 전체 설정을 관리할 수 있습니다 — 다만 app.ini를 직접 편집하면, 같은 키에 대한 환경 변수가 다음 재시작 때 그 편집 내용을 덮어씁니다. 둘 중 하나를 선택해서 일관되게 사용하십시오.

Forgejo Actions는 GitHub Actions와 동일한 형식의 워크플로 파일을 .forgejo/workflows/에서 읽어, Forgejo Runner라는 별도의 프로그램에 넘깁니다. 러너는 포지의 일부가 아니며 같은 머신에 있을 필요도 없습니다 — 이것이 설계 전체의 핵심이며, 이 단계에 그냥 넘어갈 수 없는 경고가 따라붙는 이유입니다.

인스턴스에서 Actions를 활성화한 다음, 관리 패널에서 등록 토큰을 발급받으십시오 — 인스턴스 전체 범위로 하거나, 확신이 없을 때 더 나은 기본값인 조직 하나 또는 저장소 하나로 범위를 제한할 수 있습니다. 러너는 포지 쪽으로 나가는 연결만 맺으므로 인바운드 포트가 전혀 필요 없고, 공개 주소가 없는 머신을 포함해 어떤 방화벽 뒤에도 둘 수 있습니다.

# In the Compose environment of the forge, or app.ini:
#   FORGEJO__actions__ENABLED: "true"
# Then: Site administration -> Actions -> Runners -> Create new runner

# On the runner machine:
forgejo-runner generate-config > config.yml

forgejo-runner register --no-interactive \
  --instance https://git.example.com \
  --token <REGISTRATION_TOKEN> \
  --name runner-01 \
  --labels docker:docker://node:22-bookworm,debian:docker://debian:12

forgejo-runner --config config.yml daemon

레이블은 워크플로와 러너 사이의 계약입니다. runs-on: docker를 요청하는 작업은 오른쪽에 있는 이미지로 빌드된 컨테이너를 받습니다. 실제로 제공할 준비가 된 레이블만 선언하십시오. 아무도 제공하지 않는 레이블을 요청하는 작업은 실패하는 대신 영원히 대기하며, 이는 긴 하루의 끝에 디버깅하기 혼란스러운 일이기 때문입니다.

.forgejo/workflows/ci.yml

on: [push, pull_request]

jobs:
  test:
    runs-on: docker
    container:
      image: node:22-bookworm
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

시크릿도 같은 방식으로 범위를 제한하십시오. Forgejo는 이를 저장소, 조직, 인스턴스 수준에서 저장합니다. 저장소 하나만 필요로 하는 배포 키는 그 저장소에만 존재해야 합니다. 그래야 관련 없는 프로젝트에서 침해된 워크플로가 그것을 읽을 수 없습니다. 대상이 지원하는 곳이라면 어디서든 장기 토큰보다 단기 토큰을 우선하고, 워크플로 파일에는 절대 시크릿을 넣지 마십시오 — 워크플로 파일은 저장소 안에 있고, 저장소에는 이력이 남기 때문입니다.

빌드가 실행할 때마다 같은 베이스 이미지를 가져온다면 캐싱하십시오. 로컬 레지스트리 미러나 영속적인 러너 캐시는 2분 걸리던 이미지 가져오기를 2초로 줄여주며, 여러분이 두들기고 있는 업스트림 레지스트리에 대한 예의이기도 합니다. 그리고 이 설계 전체가 자연스럽게 이끄는 패턴 하나를 눈여겨보십시오. 이것이 바로 이 가이드가 에이전트 런타임 가이드 옆에 놓인 이유입니다. 러너는 여러분의 포지에서 작업을 가져오는 범용 워커이므로, 예약된 유지보수, 데이터 파이프라인, 에이전트 워크로드도 바로 이곳에 속하게 됩니다.

포지를 셀프 호스팅하는 것은 누가 여러분의 작업물을 쥐고 있는지에 대한 진짜 변화이지, 투명인간이 되는 것은 아닙니다. 위의 모든 것을 마친 뒤에도 변하지 않는 사실이 네 가지 있으며, 이를 아는 것이 진짜 방어와 스스로에게 들려주는 이야기의 차이를 만듭니다.

디스크는 누군가의 건물 안에 있습니다. 임대한 서버는 문과 직원이 있는 데이터센터의 하드웨어에서 돌아갑니다. NordBastion은 고객의 워크로드를 들여다보지 않으며, 투명성 보고서와 워런트 캐너리는 만약 요청을 받는다면 어떤 일이 벌어질지를 설명합니다 — 하지만 정직한 진술은 구조적인 것입니다. 달라지는 것은 여러분의 저장소에 대한 제품 차원의 색인도, 커밋에 대한 분석 파이프라인도, 개정될 수 있는 개인정보 처리방침도 없다는 점입니다. 달라지지 않는 것은 그 머신이 물리적으로 존재하며 여러분의 집 안에 있지 않다는 점입니다.

인증서가 발급되는 순간 호스트네임은 공개됩니다. 공개적으로 신뢰되는 모든 인증서는 누구나 검색할 수 있는 인증서 투명성 로그에 게시되므로, git.yourproject.com은 한 번도 링크하지 않았더라도 찾아낼 수 있습니다. 이는 여러분의 코드가 유출되는 것은 아니지만, 그 프로젝트가 존재하며 대략 언제 시작되었는지가 유출되는 것입니다. 이미 공개한 이름의 서브도메인을 사용하거나, 공개 인증서를 아예 생략하고 WireGuard나 어니언 서비스로 포지에 접근하십시오.

이제 여러분은 웹 애플리케이션을 패치하는 사람입니다. 포지는 로그인 페이지이자, 신뢰할 수 없는 마크업을 위한 렌더링 파이프라인이자, SSH 서버이자, CI 엔진이며, 이 모두가 인터넷에서 접근 가능합니다. 이는 1단계의 베어 저장소보다 상당히 넓은 표면이며, 여러분이 계속 최신 상태로 유지해야 하는 것입니다. 릴리스 공지를 구독하고, 보안 릴리스는 이번 분기가 아니라 이번 주 안에 처리할 일로 다루십시오.

연합은 아직 여기 없습니다. Forgejo는 포지 간 연합(federation)에 실제로 공을 들이고 있고 그 진행 상황도 공개하고 있지만, 오늘 기준으로는 공유 플랫폼에서처럼 자신의 인스턴스에서 다른 누군가의 인스턴스로 풀 리퀘스트를 열 수는 없습니다. 실무적으로 이는 외부 기여자가 여전히 여러분의 포지에 계정을 가지고 있어야 하거나, 이메일로 패치를 받거나, 지나가며 기여하는 사람들을 위해 공개 미러를 유지해야 한다는 뜻입니다. 셋 중 여러분의 프로젝트에 맞는 방식을 미리 계획해 두고, 나중에 놀라지 마십시오.

여러분이 실제로 얻은 것을 정확히 말하면 이렇습니다. 무엇을, 누구와, 언제 만들었는지에 대한 날짜 기록이, 그것을 분석하는 것이 사업 모델의 일부인 회사의 손을 더 이상 거치지 않게 되었다는 것입니다. 이는 좁은 주장이지만, 진짜인 주장이기도 합니다. 그리고 이는 오직 6단계까지 마쳤을 때만 그 값어치를 합니다 — 검증된 복원 없이 셀프 호스팅한 포지는 프라이버시의 개선이 아니라, 브랜딩만 더 나은 단일 장애점일 뿐입니다.