Gitea 설치 가이드 2026: Proxmox CT Helper-Scripts로 15분 구축하고 기본 보안 설정·백업까지

이 글은 Proxmox CT(LXC) 환경에서 Gitea를 빠르게 설치하고, “운영 가능한 Git 서버”로 기본 보안 설정과 백업 포인트까지 잡는 과정을 정리한다. 설치보다 중요한 건 데이터(리포지토리/DB) 보존과 접속 경로(내부/외부)를 초기에 정리하는 것이다.

이 글의 목표(성공 기준)

Gitea가 정상 기동하고 웹 UI에 접속된다.
관리자 계정/기본 보안 설정(가입/권한/SSH)을 최소 기준으로 정리한다.
업데이트 전 백업/복구 체크리스트가 있어 장기 운영이 가능하다.

Proxmox 홈랩에 Git 서버를 붙이면 뭐가 달라질까?

홈랩을 운영하다 보면 어느 순간 이런 생각이 듭니다. “서비스는 늘어나는데, 설정 파일과 스크립트는 왜 여기저기 흩어져 있지?” 메모장에 붙여둔 명령어, 맥북 Downloads 폴더에 있는 임시 스크립트, NAS에 굴러다니는 백업 파일까지… 이쯤 되면 운영이 아니라 보물찾기죠.

그래서 오늘은 Proxmox CT(LXC) + Helper-Scripts 조합으로 Gitea를 빠르게 올리고, 실제 운영에 필요한 기본 보안 설정과 백업 루틴까지 한 번에 정리해보겠습니다. 이미 이 블로그에서 다뤘던 Uptime Kuma 설치 글이나 Vaultwarden 설치 글처럼, 이번에도 “빨리 설치하고 오래 굴리는” 흐름으로 갑니다.

참고로 오늘 방식의 핵심은 간단합니다. 설치는 Helper-Scripts로 빠르게, 운영 품질은 사람이 이해하고 조정할 수 있는 최소한의 수동 단계로 보강하는 겁니다. 초반 속도와 장기 안정성을 둘 다 챙기는 쪽이죠.

왜 하필 Gitea인가? (그리고 왜 CT인가?)

Gitea는 한 줄로 요약하면 “셀프호스팅 Git 플랫폼의 밸런스형”입니다. 가볍고, 빠르고, 설치 선택지가 많고, 팀 협업 기능까지 기본기가 탄탄합니다. 공식 저장소에서도 프로젝트 목표를 “쉽고 빠르게 셀프호스팅 Git 서비스를 구축하는 것”으로 분명히 말하고 있습니다. 원문이 궁금하면 Gitea GitHub 저장소를 한 번 읽어보세요.

그럼 VM 대신 CT(LXC)는 왜 쓰냐고요? 홈랩 관점에선 아주 현실적인 이유가 있습니다.

부팅/복제가 빠르고 리소스 오버헤드가 작습니다.
Proxmox 백업/스냅샷 워크플로와 자연스럽게 맞물립니다.
한 대의 N100 홈서버에서 여러 서비스를 병행할 때 밀도가 좋아집니다.

쉽게 비유하면, VM이 원룸 전체 임대라면 CT는 잘 정리된 코리빙 룸입니다. 격리는 유지하면서 관리비를 줄이는 느낌이라고 보시면 됩니다 🙂

설치 방식 비교: 지금 내 홈랩에 맞는 선택은?

방식	장점	주의점	추천 상황
Proxmox Helper-Scripts 기반 CT	구축 속도 빠름, 표준화 쉬움, 반복 설치에 강함	설치 후 보안/백업 정책은 직접 확정 필요	홈랩에서 빠르게 운영 시작하고 싶은 경우
Docker Compose 수동 구성	구성 가시성 높음, 서비스 결합 유연	권한/볼륨/업데이트 관리 포인트가 늘어남	컨테이너 운영 경험이 충분한 경우
독립 VM 수동 설치	격리성 극대화, OS 단위 실험 자유도	리소스 사용량 큼, 운영 부담 증가	규모가 크거나 강한 격리가 필요한 경우

이번 글은 첫 번째 라인, 즉 Helper-Scripts + CT를 기준으로 설명합니다. 실제로 이 경로가 “오늘 바로 시작”이라는 검색 의도에 가장 잘 맞습니다.

사전 준비 체크리스트

Proxmox VE 호스트 접근 권한 (root 또는 동등 권한)
고정 IP 또는 DHCP 예약 계획
도메인(선택): 예) git.example.com
역방향 프록시(Caddy/Nginx 등) 운영 여부 결정
백업 저장 위치(로컬 디스크, NAS, 외부 스토리지) 확정

여기서 가장 중요한 건 마지막 항목입니다. Git 서비스는 코드만 있는 게 아니라 이슈, 위키, 릴리스, 액션 로그 같은 운영 맥락이 같이 쌓입니다. 백업 위치를 먼저 정하는 습관이 나중에 팀 멘탈을 지켜줍니다.

1단계: Proxmox Helper-Scripts로 Gitea CT 생성

공식 커뮤니티 스크립트 페이지에서 Gitea 항목을 확인한 뒤, Proxmox 호스트에서 설치 스크립트를 실행합니다. 참고 링크는 Proxmox VE Helper-Scripts Gitea 페이지입니다.

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/gitea.sh)"

이 명령이 하는 일은 크게 세 가지입니다. 첫째, CT 생성에 필요한 기본값(코어, 메모리, 디스크, OS 버전)을 준비합니다. 둘째, Gitea 바이너리와 서비스 구동에 필요한 구성요소를 설치합니다. 셋째, 서비스 기동 후 웹 접속 가능한 상태까지 초기화를 마칩니다.

실행 중에 CT ID, 스토리지, 네트워크 관련 선택지를 묻는 경우가 있습니다. 여기서의 팁은 간단합니다.

처음부터 과한 사양을 주기보다 CPU 1~2코어, RAM 1~2GB, 디스크 8GB+로 시작
IP는 반드시 고정 또는 DHCP 예약
설치가 끝나면 출력되는 접속 URL을 즉시 기록

“나중에 기억하지 뭐”가 가장 위험합니다. 운영 메모를 안 남기면 2주 뒤의 나는 남이 됩니다.

2단계: 웹 초기 설정(설치 마법사)

브라우저에서 http://CT_IP:3000으로 접속하면 Gitea 초기 설정 화면이 열립니다. 여기서 결정한 값이 이후 운영 품질에 꽤 큰 영향을 줍니다.

2-1) 데이터베이스 선택

작은 홈랩이라면 SQLite로 빠르게 시작할 수 있지만, 장기 운영(사용자 증가, 백업/복구 빈도 증가)을 보면 PostgreSQL이나 MariaDB를 권장합니다. 공식 설치 문서에서도 배포 방식별 DB 구성을 자세히 다루고 있으니, 필요하면 Gitea 설치 문서를 같이 보세요.

2-2) 서버 URL(ROOT_URL) 확정

외부 접속 도메인을 쓸 계획이라면 초기에 ROOT_URL을 명확히 맞춰두는 게 좋습니다. 예를 들어 https://git.example.com/처럼요. 이 값이 틀리면 알림 링크, 클론 URL, OAuth 콜백에서 미묘한 문제를 만날 수 있습니다.

2-3) 관리자 계정/조직 정책

관리자 계정은 실사용 계정과 분리하세요. 운영자 전용 계정과 일반 개발 계정을 나누면 감사 추적이 훨씬 깔끔해집니다. 당장은 번거로워 보여도, 나중엔 “왜 그때 안 나눴지?”가 됩니다.

3단계: 기본 보안 설정(꼭 필요한 것만)

여기부터가 실전 운영 품질을 좌우합니다. 복잡한 보안 설정보다, 효과가 확실한 최소 세트를 먼저 적용하는 게 포인트입니다.

3-1) HTTPS 강제와 역방향 프록시 헤더 정합성

Gitea 공식 문서의 Reverse Proxy 항목에서 가장 강조하는 부분은 ROOT_URL, Host 헤더, X-Forwarded-Proto 전달입니다. 관련 내용은 Reverse Proxies 문서에 정리되어 있습니다.

예를 들어 Caddy를 쓰는 경우는 아래처럼 단순하게 시작할 수 있습니다.

git.example.com {
    reverse_proxy 192.168.0.50:3000
}

이 설정의 목적은 “TLS 종료는 프록시에서, 애플리케이션은 내부 HTTP로”라는 역할 분리입니다. 구성 단순성과 인증서 자동화 측면에서 홈랩에 특히 유리합니다.

3-2) SSH 포트와 접근 표면 정리

Gitea는 웹 UI 외에 Git over SSH를 자주 쓰게 됩니다. 포트를 기본값 그대로 둘지, 커스텀할지는 팀 습관에 맞추되, 중요한 건 외부 노출 범위를 의도적으로 제한하는 겁니다. 예를 들어 외부는 HTTPS만 열고, SSH는 Tailscale이나 내부망으로만 제한하는 식입니다.

이 단계의 핵심은 “뚫기 어렵게”보다 “불필요한 문을 줄이기”입니다. 잠금장치를 열 개 다는 것보다 문을 두 개 닫는 게 더 효과적일 때가 많습니다.

3-3) 자동 업데이트와 재시작 정책

보안 공지 확인 후 수동 업데이트만으로 운영할 수도 있지만, 홈랩에서는 실수로 미루기 쉽습니다. 최소한 OS 보안 업데이트 자동화는 켜두는 편이 낫습니다.

apt update
apt install -y unattended-upgrades
dpkg-reconfigure -plow unattended-upgrades

첫 줄은 패키지 인덱스를 최신화하고, 둘째 줄은 자동 보안 업데이트 도구를 설치하며, 셋째 줄은 실제 적용 정책을 대화형으로 활성화합니다. 즉, “새벽에 알아서 패치” 체계를 만드는 과정입니다.

3-4) 릴리스 업그레이드 기준선 만들기

어느 버전을 따라갈지도 중요합니다. 안정 지향 홈랩이라면 최신 태그를 무조건 즉시 반영하기보다, 릴리스 노트를 확인하고 주간 단위로 반영하는 방식이 좋습니다. 릴리스 확인은 Gitea Releases에서 가능합니다.

한 줄 요약: 업데이트는 빠르게가 아니라 예측 가능하게 하세요.

4단계: 백업/복구 루틴 만들기 (운영의 본체)

백업은 “하면 좋다”가 아니라 “안 하면 언젠가 크게 아프다”에 가깝습니다. Gitea 공식 문서도 백업 시점 일관성을 위해 서비스 정지 상태를 권장합니다. 자세한 근거는 Backup and Restore 문서를 참고하세요.

가장 단순한 기준 루틴은 아래와 같습니다.

systemctl stop gitea
sudo -u git /usr/local/bin/gitea dump -c /etc/gitea/app.ini --tempdir /tmp
systemctl start gitea

첫 줄은 쓰기 작업이 섞이지 않도록 서비스를 멈춰 백업 일관성을 확보하고, 둘째 줄은 설정/데이터/저장소/DB 덤프를 아카이브로 만듭니다. 셋째 줄은 다운타임을 최소화하기 위한 서비스 재개입니다.

여기서 끝내지 말고, 생성된 파일을 NAS나 별도 스토리지로 복사하세요. 그리고 월 1회는 “복구 리허설”을 해보는 걸 권장합니다. 백업 파일이 존재하는 것과, 실제로 복구되는 것은 다른 문제이기 때문입니다.

5단계: 운영 초반에 자주 부딪히는 문제와 해결 포인트

문제 1) 클론 URL이 내부 IP로 나온다

대부분 ROOT_URL 또는 프록시 헤더 전달 불일치 문제입니다. 앱 설정과 프록시 설정을 같이 확인하세요.

문제 2) 대용량 푸시/첨부에서 413 오류

프록시의 업로드 크기 제한값이 작을 때 발생합니다. Nginx라면 client_max_body_size 조정이 필요하고, Caddy/프록시 체인에서도 상한값을 확인해야 합니다.

문제 3) 백업은 했는데 복구가 불안하다

가장 흔한 상황입니다. 해결은 단순합니다. 테스트 CT를 하나 만들고 복구 절차를 문서로 남겨 팀이 그대로 따라할 수 있게 하세요. “내 머릿속 절차”는 장애 상황에서 잘 동작하지 않습니다.

6단계: 팀 협업 기준까지 같이 정하면 운영이 편해진다

설치만 끝내면 절반입니다. 협업 규칙을 같이 정해야 진짜 운영이 됩니다.

기본 브랜치 보호(직접 push 제한, PR 필수)
리뷰 승인 기준(최소 1인/2인)
이슈 템플릿(버그/기능요청 분리)
릴리스 태그 규칙(예: vYYYY.MM.DD)

이건 거창한 정책이 아니라 팀의 “작업 리듬”을 맞추는 장치입니다. 규칙이 있으면 속도가 느려지는 게 아니라, 불필요한 대화가 줄어서 오히려 빨라집니다.

실전 네트워크 구성 예시: 내부망은 단순하게, 외부 접근은 통제되게

홈랩에서 자주 쓰는 안전한 패턴은 이렇습니다. Gitea CT는 내부망에만 두고, 외부 노출은 역방향 프록시 한 곳에서만 받습니다. 예를 들어 Gitea는 192.168.0.50:3000에 두고, 외부 사용자는 https://git.example.com으로만 접근하게 만드는 식입니다. 이렇게 하면 인증서, 접근 로그, 차단 정책을 한 레이어에서 관리할 수 있어 운영 복잡도가 크게 줄어듭니다.

Git over SSH를 꼭 외부에 열어야 한다면, 방화벽에서 소스 IP 제한을 걸거나 VPN/Tailscale 경유만 허용하는 방식이 좋습니다. “열어두고 잘 막아보자”보다 “원천적으로 좁게 열자”가 운영 피로도를 낮춥니다. 특히 혼자 운영하는 홈랩은 보안 설계가 복잡할수록 오래 못 갑니다.

운영 점검 루틴: 하루 3분, 주간 20분, 월간 1시간

서비스 품질은 대단한 기술보다 반복 루틴에서 나옵니다. 아래 루틴은 소규모 홈랩에서 효과가 좋은 편입니다.

하루 3분 루틴

서비스 상태 확인: systemctl status gitea
디스크 여유 확인: df -h
최근 에러 로그 확인: journalctl -u gitea -n 100 --no-pager

첫 줄은 “서비스가 살아있는지”를 확인합니다. 둘째 줄은 저장소 증가로 인한 디스크 압박을 빠르게 감지합니다. 셋째 줄은 인증 실패, 포트 충돌, 권한 문제 같은 초반 신호를 잡아냅니다. 이 3개만 해도 큰 장애를 꽤 많이 예방합니다.

주간 20분 루틴

백업 파일 생성 여부와 크기 변동 확인
릴리스 노트에서 보안 패치 포함 여부 확인
조직/리포지토리 권한(Owner/Collaborator) 점검

권한 점검은 특히 중요합니다. 프로젝트가 늘어나면 임시 권한을 주고 잊어버리는 일이 자주 생기기 때문입니다. 홈랩도 결국 작은 프로덕션입니다. 누가 어디까지 가능한지 주기적으로 청소해두면 사고 범위를 줄일 수 있습니다.

월간 1시간 루틴

복구 리허설: 테스트 CT에 덤프 복원
도메인/인증서 만료 점검
사용하지 않는 리포지토리/러너/웹훅 정리

여기서 핵심은 복구 리허설입니다. 백업만 있고 복구가 느리면, 장애 시 체감은 “백업이 없는 것”과 크게 다르지 않습니다. 월 1회 리허설은 미래의 장애 시간을 줄이는 가장 확실한 투자입니다.

명령어를 복붙하기 전에 이해하면 좋은 포인트

설치 가이드에서 자주 보는 명령어는 겉보기엔 간단하지만 의미를 알면 응용이 쉬워집니다.

systemctl stop gitea

이 명령은 서비스 프로세스를 정상 종료해 데이터 변경을 멈춥니다. 백업 일관성을 확보하려고 멈추는 것이지, “문제가 있어서” 멈추는 게 아닙니다.

sudo -u git /usr/local/bin/gitea dump -c /etc/gitea/app.ini --tempdir /tmp

-u git는 Gitea 실행 사용자 권한으로 명령을 실행하겠다는 의미입니다. 파일 권한 꼬임을 줄이는 데 중요합니다. -c는 어떤 설정 파일을 읽을지 지정하고, --tempdir는 중간 파일이 생성될 위치를 지정합니다. 즉, 백업의 재현성을 높이는 옵션 조합입니다.

systemctl start gitea

다운타임을 줄이기 위해 즉시 서비스를 재개합니다. 여기까지 실행한 뒤에는 웹 접속과 저장소 clone/push 테스트를 한 번 수행해 “운영 복귀 확인”까지 끝내는 습관을 들이세요.

초기 성능 튜닝: 과하지 않게, 체감 위주로

홈랩에서는 과한 튜닝보다 병목 제거가 먼저입니다. 가장 많이 체감되는 포인트는 세 가지입니다.

디스크: 느린 저장소를 쓰면 이슈/검색/푸시 체감이 급격히 떨어집니다.
메모리: 사용자 수가 늘면 캐시와 DB 응답에서 차이가 납니다.
프록시: 압축/버퍼/업로드 한도 설정이 잘못되면 “가끔 느린 서비스”가 됩니다.

Gitea 자체는 가벼운 편이라, 대부분의 체감 문제는 주변 레이어(디스크·네트워크·프록시)에서 발생합니다. 그래서 먼저 아키텍처를 단순하게 잡고, 병목이 확인될 때만 조정하는 방식이 효율적입니다.

작게 시작해도 좋은 이유: 확장 경로가 명확하다

처음부터 모든 걸 완벽히 구성할 필요는 없습니다. CT 한 개에서 시작해도, 이후 확장 경로가 분명합니다. 예를 들어 DB를 외부로 분리하고, 러너를 별도 노드에 붙이고, 백업 보관 정책을 3-2-1로 발전시키는 식으로 단계적 확장이 가능합니다.

중요한 건 “지금 감당 가능한 설계”를 고르는 겁니다. 홈랩은 오래 운영하는 사람이 이깁니다. 처음부터 너무 무겁게 시작하면, 기술보다 체력이 먼저 고갈됩니다.

마무리: 설치 속도보다 중요한 건 복구 가능성

오늘 구성은 설치 자체보다 운영 균형에 초점을 맞췄습니다. Helper-Scripts로 빠르게 시작하고, HTTPS/헤더 정합성/업데이트/백업 루틴으로 최소한의 안전장치를 붙이면 홈랩에서도 충분히 안정적인 Git 플랫폼을 만들 수 있습니다.

특히 기억할 한 가지를 꼽자면 이겁니다. “잘 되는 서버”보다 “다시 살릴 수 있는 서버”가 더 좋은 서버입니다. 지금 당장 30분 투자해서 백업-복구 리허설까지 해두면, 미래의 나에게 꽤 큰 선물을 주는 셈입니다.

다음 커밋부터는 “파일 어디 있지?” 대신 “PR 열어둘게요”가 일상이 되길 바랍니다. 홈랩 운영의 체감 난이도가 생각보다 크게 내려갈 겁니다.

썸네일 이미지 출처: Gitea 공식 홈페이지의 제품 UI 스크린샷 일부를 편집해 사용했습니다.

3줄 요약

자주 막히는 지점(트러블슈팅)

결론/다음 단계

같이 보면 좋은 글