gitea / ubuntu linux 개발 환경 구축기

4월 08, 2026

개발 환경 구축기

Gitea가 뭔가요

Gitea는 내 서버에 직접 설치해서 운영할 수 있는 Git 저장소 관리 도구입니다. GitHub처럼 코드를 올리고, 버전을 관리하고, 웹 UI로 파일을 둘러볼 수 있는데, 다른 점이 있다면 서버가 내 것이라는 겁니다.

Go 언어로 만들어져서 가볍고 빠릅니다. 라즈베리파이에도 돌아갈 정도입니다.

왜 GitHub 말고 Gitea인가

GitHub도 Private 저장소를 무료로 제공합니다. 그러니까 보안 때문에 Gitea를 선택해야 한다는 건 아닙니다. 다만 이런 경우라면 Gitea가 맞습니다.

소스코드를 외부 서버에 올리기 싫을 때. 인터넷이 안 되는 환경에서 써야 할 때. 이미 서버가 있고 직접 관리하고 싶을 때. 이 세 가지 중 하나라도 해당된다면 Gitea를 선택하면 됩니다.

참고 개인 용도라면 GitHub 무료 플랜도 충분합니다. Private 저장소도 무제한이고 서버 관리를 안 해도 됩니다. 굳이 서버를 직접 관리하고 싶지 않다면 GitHub를 쓰세요.

설치 전 준비

이 글의 환경은 Ubuntu 20.04 LTS입니다. Docker 없이 바이너리를 직접 설치합니다.

먼저 OS 버전을 확인합니다.

cat /etc/os-release

설치 과정

먼저 Gitea 전용 시스템 계정을 만듭니다. Gitea는 이 계정으로 실행됩니다.

sudo adduser --system --shell /bin/bash \
  --gecos 'Git Version Control' \
  --group --disabled-password \
  --home /home/git git

바이너리를 다운로드합니다.

sudo wget -O /usr/local/bin/gitea \
  https://dl.gitea.com/gitea/1.21.11/gitea-1.21.11-linux-amd64
sudo chmod +x /usr/local/bin/gitea

필요한 디렉토리를 만들고 권한을 설정합니다.

sudo mkdir -p /var/lib/gitea/{custom,data,log}
sudo chown -R git:git /var/lib/gitea/
sudo chmod -R 750 /var/lib/gitea/
sudo mkdir /etc/gitea
sudo chown root:git /etc/gitea
sudo chmod 770 /etc/gitea

systemd 서비스 파일을 만들어서 서버 재시작 시 자동으로 뜨게 합니다.

sudo tee /etc/systemd/system/gitea.service << 'EOF'
[Unit]
Description=Gitea (Git with a cup of tea)
After=syslog.target
After=network.target

[Service]
RestartSec=2s
Type=simple
User=git
Group=git
WorkingDirectory=/var/lib/gitea/
ExecStart=/usr/local/bin/gitea web \
  --config /etc/gitea/app.ini \
  --work-path /var/lib/gitea
Restart=always
Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea

[Install]
WantedBy=multi-user.target
EOF

서비스를 등록하고 시작합니다.

sudo systemctl daemon-reload
sudo systemctl enable gitea
sudo systemctl start gitea

정상적으로 실행됐는지 확인합니다.

sudo systemctl status gitea

환경 설정

설정 파일을 만듭니다. SQLite를 DB로 사용하면 별도 DB 설치 없이 바로 쓸 수 있습니다.

sudo tee /etc/gitea/app.ini << 'EOF'
[server]
HTTP_PORT = 3000
ROOT_URL = http://서버IP:3000/

[database]
DB_TYPE = sqlite3
PATH = /var/lib/gitea/data/gitea.db

[security]
INSTALL_LOCK = false

[repository]
ROOT = /var/lib/gitea/repositories

[log]
ROOT_PATH = /var/lib/gitea/log
EOF

파일 권한을 설정합니다. 이 부분이 핵심입니다. 아래 삽질 기록을 꼭 읽어보세요.

sudo chown root:git /etc/gitea/app.ini
sudo chmod 660 /etc/gitea/app.ini

Gitea를 재시작하고 브라우저에서 http://서버IP:3000에 접속하면 초기 설정 화면이 나옵니다.

sudo systemctl restart gitea

삽질 기록 (주의점)

삽질 1 — app.ini 권한 문제

가장 오래 헤맨 부분입니다. 설치 화면에서 Submit을 눌러도 500 에러가 나면서 다시 설치 화면으로 돌아오는 루프가 생겼습니다.

원인은 이렇습니다. 설치가 완료되면 Gitea는 app.ini에 INSTALL_LOCK = true를 써야 합니다. 그런데 app.ini 소유자가 root이고 git 그룹에 쓰기 권한이 없으면 이 작업이 실패합니다. Gitea는 재시작되면서 app.ini를 다시 읽는데, INSTALL_LOCK이 여전히 false니까 또 설치 화면을 보여줍니다. 이 루프가 무한 반복됩니다.

해결책은 chmod 660으로 git 그룹에 쓰기 권한을 주는 것입니다.

삽질 2 — 포트 충돌

Gitea 기본 포트는 3000입니다. 같은 서버에서 다른 서비스가 이미 3000을 쓰고 있으면 시작이 안 됩니다. 포트 충돌 여부는 이렇게 확인합니다.

sudo ss -tlnp | grep 3000

충돌이 있으면 app.ini에서 HTTP_PORT를 다른 값으로 바꾸면 됩니다.

삽질 3 — WorkPath 오인식

systemd 서비스 파일에서 환경변수만으로는 WorkPath가 제대로 안 잡히는 경우가 있습니다. ExecStart에 --work-path /var/lib/gitea를 명시적으로 추가해야 안전합니다.

팁 /install 경로는 Gitea 1.21부터 404를 반환합니다. 정상입니다. 그냥 http://서버IP:3000 으로 접속하면 됩니다.

기본 사용법

Gitea에서 계정을 만들고 저장소를 생성한 뒤, 로컬 프로젝트에서 아래 명령어를 실행하면 됩니다.

cd 프로젝트폴더
git init
git add .
git commit -m "첫 커밋"
git remote add origin http://서버IP:3000/유저명/저장소명.git
git push -u origin main

이후 변경사항이 생길 때마다 이 세 줄이면 됩니다.

git add .
git commit -m "변경 내용"
git push

설치 자체보다 권한 설정과 포트 확인이 핵심이었습니다. 이 글대로 따라하면 삽질 없이 30분 안에 끝낼 수 있을 겁니다.

Development Story with AI