I Self-Hosted My Own Gitea Instance on a Homelab – And Why You Should Too
If you are a developer, tinkerer, or one who values having control of your data, well, you probably have thought about hosting your own version control system. It all started for me when I set up Gitea on my homelab.
I had been using GitHub and GitLab for years, but there’s always been that tickling: What if these platforms go down? Or change their pricing? Or start scanning your code for who knows what? I wanted something lightweight, fast, and completely under my control. Gitea checked all the boxes.
What is Gitea?
Gitea is a lightweight self-hosted Git service similar to GitHub. It is open-source and easy to install for those wanting their private Git server without all the bloat in a very lightweight package.
Why Self-Host?
For me, self-hosting was not just about having full control. It also meant:
- Networking, containers, Linux and all that
- Have a backup Git solution for personal projects
- Not publicize my code without making use of third-party services
My Setup
I do have a homelab setup running – but you could do with just a low-power Intel NUC with Proxmox as the hypervisor. Here is how I have set up Gitea:
- Spun Up a Provisioned VM: I spun up an Ubuntu Server VM in Proxmox.
- Installed Docker + Docker Compose: Gitea works flawlessly in Docker. OR bare-metal on a VM.
- Docker Compose setup: I have used the official Gitea Docker image and done a simple setup with
docker-compose.ymlwith a PostgreSQL backend. - Setup Volumes: Once mounted, persistent storage so nothing gets lost on reboot.
- Reverse Proxy with Nginx: I started pointing a domain to my homelab and tasked Nginx as a reverse proxy serving Gitea over HTTPS.
- Let’s Encrypt SSL: Certbot to fetch and renew SSL certificates automatically.
#Install git
apt update && apt install git -y
#Get the correct download link for the latest version
wget https://dl.gitea.com/gitea/1.20.3/gitea-1.20.3-linux-amd64
#Move the binary to bin
mv gitea* /usr/local/bin/gitea
#Make executable
chmod +x /usr/local/bin/gitea
#Ensure it works
gitea --version
#Create the user/group for gitea to operate as
adduser --system --group --disabled-password --home /etc/gitea gitea
#Config directory was created by adduser
#Create directory structure (mountpoint should be /var/lib/gitea)
mkdir -p /var/lib/gitea/{custom,data,log}
chown -R gitea:gitea /var/lib/gitea/
chmod -R 750 /var/lib/gitea/
chown root:gitea /etc/gitea
chmod 770 /etc/giteaAfter that, we need a Systemd Service: (/etc/systemd/system/gitea.service)
[Unit]
Description=Gitea (Git with a cup of tea)
After=syslog.target
After=network.target
[Service]
# Uncomment the next line if you have repos with lots of files and get a HTTP 500 error because of that
# LimitNOFILE=524288:524288
RestartSec=2s
Type=notify
User=gitea
Group=gitea
#The mount point we added to the container
WorkingDirectory=/var/lib/gitea
#Create directory in /run
RuntimeDirectory=gitea
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always
Environment=USER=gitea HOME=/var/lib/gitea/data GITEA_WORK_DIR=/var/lib/gitea
WatchdogSec=30s
#Capabilities to bind to low-numbered ports
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE
[Install]
WantedBy=multi-user.targetThen run it:
systemctl daemon-reload
systemctl enable --now giteaNow you can access it via :3000 to do the intial setup.
Configure HTTPS (Self-Signed)
And finally, configure Gitea to use HTTPS and the usual ports (80/443) using a self-signed cert (or one you provide, old-school) by editing /etc/gitea/app.ini. I’ve provided a diff below, the +- indicates what lines to add and remove.
[server]
+PROTOCOL=https
+REDIRECT_OTHER_PORT=true
+CERT_FILE = /etc/gitea/cert.pem
+KEY_FILE = /etc/gitea/key.pem
SSH_DOMAIN = gitea.palnet.net
DOMAIN = gitea.palnet.net
-HTTP_PORT = 80
+HTTP_PORT = 443
ROOT_URL = https://gitea.palnet.net/
APP_DATA_PATH = /var/lib/gitea/data
DISABLE_SSH = falseAnd then generate a self-signed certificate and restart the server:
#Cd to the gitea directory
cd /etc/gitea
#sign cert
gitea cert --host teapot.apalrd.net
#Give gitea user read permissions
chown root:gitea cert.pem key.pem
chmod 640 cert.pem key.pem
#Restart gitea
systemctl restart giteaTo temporarily ignore certificates in Git (for testing), you can use the option -c http.sslVerify=false to git.
Configure HTTPS (Let’s Encrypt)
To use Let’s Encrypt you need a few different options in /etc/gitea/app.ini:
[server]
+PROTOCOL=https
+REDIRECT_OTHER_PORT=true
+ENABLE_ACME=true
+ACME_ACCEPTTOS=true
+ACME_DIRECTORY=https
+ACME_URL=https://acme-staging-v02.api.letsencrypt.org/directory
+ACME_EMAIL=adventure@apalrd.net
SSH_DOMAIN = gitea.palnet.net
DOMAIN = gitea.palnet.net
-HTTP_PORT = 80
+HTTP_PORT = 443
ROOT_URL = https://gitea.palnet.net/
APP_DATA_PATH = /var/lib/gitea/data
DISABLE_SSH = falseI have the URL set to the let’s encrypt staging repository as an example, you can use the directory URL of your own private CA, or leave it out entirely to use the let’s encrypt production server, which is the default if you leave the option out entirely. And then of course restart:
#Restart gitea
systemctl restart giteaIf Gitea can’t get a cert from Let’s Encrypt it will crash and you will have to look at journactl -xeu gitea to figure it out. Very frustrating. So make sure the Let’s Encrypt challenges will work (port 80 + 443 are correctly allowed by your network firewall)
Lessons Learned
- Backup is key – I now run a cron job that dumps the PostgreSQL database and backs up the Gitea data folder.
- Update regularly – Gitea updates are painless, but don’t skip them. Often security fixes come out.
- Performance is great – Gitea is fast, even on modest hardware.
Gitea went up in my homelab painlessly and rewarding. Finally, I have a private Git server I’m in control of, and it fits nicely into the rest of my self-hosted tools. If you have a homelab and are interested in taking charge of your dev workflows, I will recommend taking a trial on Gitea.