Github을 대체하자 - Forgejo

Oh my server

Private한 git 서비스가 필요할 때

많은 작업들을 git과 연동하여 사용하고 있다.

$\LaTeX$ 을 통한 논문 작성 (.tex)
Hugo blog (.md)
Obsidian을 통한 개인 메모 관리 (.md)

이들 작업들은 plain text에 기반한다는 공통점을 가진다. 그래서 git과 연동할 경우, 과거의 변화를 추적하거나, 특정 시점으로 roll back 하는 등 많은 이점이 생긴다.

물론 텍스트 뿐만 아니라 이미지를 함께 사용하기도 한다. $\LaTeX$ 문서에도 이미지가 들어가고, 블로그에도 이미지가 들어가고, obsidian에도 가끔 이미지가 들어간다. 그렇지만 git 버전 컨트롤에 이미지를 포함하면 github으로 전송해야할 directory의 용량이 굉장히 커진다는 문제가 발생한다.

이미지를 .gitignore에 추가하고 따로 관리하는 것도 생각해 봤지만 굉장히 번거로울 것 같았다. tex와 md를 컴파일할 pc마다 동일한 이미지들이 존재하도록 만들어줄 별도의 시스템이 필요해지기 때문이다. 그래서 그냥 git에 연동하여 쓰되, 너무 용량이 큰 파일은 사용하지 않는걸로 규칙을 정하고 사용을 해왔다.

예상은 했지만, 문서의 규모가 커지다보니 각 repository는 점차 그 용량이 커지게 되었고 어떤 repository는 2GB를 넘어버렸다. 아직까진 github에서 별도의 경고가 없었지만, 5GB가 상한선이라고 하니 괜히 신경이 쓰였다.

그래서 간만에 proxmox에 새로운 서비스를 하나 추가하기로 했다. 오늘의 주제인 forgejo이다. 본격적으로 forgejo에 대해 알아보기 전에, 우선 github과 git을 구분해보자.

Github의 정체: git과 github은 다르다.

  graph LR;
    A["Local git directory <br>(git)"]-->|push|B["Git remote server <br>(github, gitea, forgejo)"];
    B-->|pull|A;

Github은 일종의 클라우드 서비스다. Git은 원래 github같은 클라우드 서비스없이 local에서 동작하도록 만들어졌다. 다만, 협업을 위해 이를 클라우드 서비스인 github에 push하고 여러 사람이 작업할 수 있게 한 것일 뿐이다. 그래서 우리는 github 대신 다른 클라우드 서비스를 선택할 수 있다.

Github을 대체하는 다른 서비스에는 대표적으로 gitea, forgejo 등이 있다. 이들과 github의 차이점은 selfhosting이 가능하다는 점이다. 즉, 제한없이 내가 원하는 만큼 용량을 확보할 수 있고, 내 코드가 제3자의 서버에 업로드 된다는 걱정을 덜어낼 수 있다.

Github 대신 다른 걸 쓰자니, 이런 걱정이 들 수 있다.

Github 대신 다른 서버로 바꾼다고? 그럼 명령어가 다 달라져서 새로 배워야하는 것 아냐?

다행히 아니다. 명령어는 원래 사용하던 git 명령어를 그대로 쓴다. 다만, origin을 github에서 내 서비스(그러니까 forgejo)로 변경하는 것 뿐이다.

그럼, forgejo를 proxmox 서버에 설치해보자.

Forgejo 설치

Forgejo는 docker, binary라는 두 가지 설치 방식을 제공한다. 필자는 proxmox 서버에 설치하기 때문에, PVE script를 통해 설치한다. (2번 방식과 근본적으로 동일하다.)

PVE script로 설치하기

고맙게도 PVE script에서 forgejo 설치 스크립트를 제공하고 있다. Proxmox의 host shell에 붙여넣기하여 설치를 진행해주자. 고급 설정이 필요없다면, default로 그냥 진행해주면 된다.

proxmox host의 shell

# 시간이 지나면서 바뀌었을 수 있으니, 위 설치 스크립트 링크에서 항상 최신 버전을 사용하자.
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/forgejo.sh)"

Initial configuration 초기설정

설치가 완료되면 http://<ip_to_forgejo>:3000로 접속해주자. 기본 포트는 3000번으로 설정되어 있다.

접속하면 Initial configuration 페이지가 우릴 맞아준다. 먼저, Database settings 부분을 보자. MySQL, PostgreSQL, SQLite3로 총 세 개의 선택지가 있다. 난 거의 혼자서 쓸 것이기에 대규모 DB까진 필요없으니, SQLite3를 선택하여 진행했다.

다음으로 General settings다.

이 포스트에서는 다음의 사용 환경을 전제로 한다.

forgejo는 외부로 공개하지 않는다.

forgejo에 대한 접속은 tailscale이나 wireguard와 같은 VPN으로 한다.

그렇기 때문에 여기서 손댈 것은 없다. 그대로 두고 다음으로 넘어간다.

마지막으로 Optional settings다.

여기서 해줄 건, 세번째에 있는 Administrator account settings다. Forgejo 웹에 로그인할 때 사용할 관리자 계정을 만드는 작업이다. 다른 계정을 추가하는 건 나중에 관리자 계정으로 로그인 후 할 수 있다.

원하는 대로 계정을 설정해주자.

끝났으면, Install Forgejo를 눌러 설정을 마무리하자. 그러면 뭔가 친숙한 느낌의 웹페이지가 열린다.(github과 매우 흡사하다.)

ssh public key 등록하기

다음으로, 편리한 git 사용을 위해 내 pc의 ssh public key를 등록해줄 것이다. ssh key는 이미 생성해두었다고 가정하겠다. (혹시 없다면 이 가이드에 따라 생성해주자.)

먼저 다음을 실행하여 public key를 출력하고 그 내용을 복사해주자.

bash

# <key_name>은 자신이 만든 방식에 따라 다를 수 있으니 맞는걸로 바꿔서 출력해주자.
cat ~/.ssh/<key_name>.pub

그 다음, settings의 SSH/GPG keys 페이지로 간다.

Add key를 누르면 다음의 화면이 뜬다.

1, 2번을 순서대로 작성해준다. 1번에는 나중에 어느 pc의 key인지 구분할 수 있도록 별명을 지어준다. 아까 복사한 내용은 Content(2번)에 붙여넣어준다. 그리고 3번을 눌러준다.

생성이 끝나면 내가 등록한 키가 목록에 나타난다.

이로써 ssh을 통해 git을 사용할 환경이 준비되었다. 다음으로 repository를 생성해보자.

Repository 생성하기

Forgejo의 메인 화면에서 1, 2번 순서로 눌러 새 repository를 생성하자.

그러면 생성 페이지가 아래처럼 나오는데, repo name(1번)과 description(2번)을 작성하고 Create repository(3번)을 눌러준다. 그럼 repository 생성이 완료된다.

새 repo를 local에 가져오기

생성이 완료되면 곧바로 Quick guide 페이지가 뜬다.

1번은 우리가 생성한 repo의 이름이다. 2번에는 github이랑 똑같이 http와 ssh라는 두 개의 선택지가 있다. 우리는 ssh 사용을 설정해두었으니, 여기서도 ssh을 선택한다. (http보다 ssh 사용이 실제 더 편리하기도 하다.)

화면에 보이는 Creating a new repository on the command line의 내용을 그대로 복사한다. 그리고 터미널을 통해 git 경로로 쓸 directory로 이동한 후 붙여넣기 해준다. 여기선 ~/test 경로를 사용할 것이다.

bash

# 원하는 이름의 경로를 만들고 거기로 이동
mkdir ~/test
cd ~/test

bash

# 복사한 내용 붙여넣기
touch README.md
git init
git switch -c main
git add README.md
git commit -m "first commit"
git remote add origin ssh://git@<forgejo_ip>/will/test.git # <forgejo_ip>는 forgejo의 내부망 ip이다.
git push -u origin main

ssh 인증 관련 질문에는 yes를, 그리고 이어서 ssh key의 password를 입력해준다.

그러면 ~/test 경로에 README.md와 .git이 생긴 걸 확인할 수 있다. 성공적으로 initialize가 되었단 의미다.

축하한다. 이젠 git을 사용하기만 하면 된다.

보너스: tailscale/wireguard 를 쓴다는게 무슨 소리일까?

본 포스팅에서 구축한 시스템은 tailscale이나 wireguard 같은 vpn이 없으면 사실 상 외부에서는 접속할 수 없다. (그만큼 더 안전하단 말이기도 하다.)

Tailscale이나 wireguard가 있다면 이런 접속 형태가 될 것이다. 이로써 오직 나만이 접근 가능한 git 환경을 구축할 수 있다.

  graph LR;
    A["PC <br>(외부망)"]-->|ssh을 통한 push|B["tailscale/wireguard 노드<br>(내부망)"];
    B-->|"forward (ssh을 통한 push)"|C["Forgejo 서버<br>(내부망)"];
    C -->|ssh을 통한 pull|B;
    B-->|"forward (ssh을 통한 pull)"|A;

다음에 tailscale이나 wireguard에 대해서도 포스팅을 해보겠다.

Last updated on 8 Sep 2025

Nextcloud Calendar로 일정 관리하기 (feat. iOS 캘린더와 연동하기)