How to install Gitea on a fresh Ubuntu/Debian server
If you’ve just spun up a clean Ubuntu or Debian box and want a lightweight Git service that won’t eat your RAM, this is the recipe. We’ll walk through downloading, configuring, and running Gitea so you can start pushing repositories in minutes.
1: Pick the right OS version
First, make sure you’re on a supported release. I’ve seen people try to install Gitea on Ubuntu 12.04 or Debian 7 and end up with broken dependencies. Stick to at least Ubuntu 20.04 LTS or Debian 10 Buster.
2: Update the system
sudo apt update && sudo apt upgrade -y
Fresh installs often miss a few security patches that Gitea’s dependencies rely on. Upgrading first keeps the package database clean and avoids surprises when you later install the Go runtime or MariaDB.
3: Install prerequisites
sudo apt install git curl wget unzip -y
You’ll need git for pulling the repository, curl/wget for downloading binaries, and unzip because Gitea’s official release comes zipped. Skip any other heavy packages; keep this lean.
4: Create a dedicated Gitea user
sudo adduser --disabled-login --gecos "" gitea
Running Gitea as root is a rookie mistake that leads to file‑permission nightmares later. A minimal user keeps your server tidy and forces you to think about the files it owns.
5: Grab the latest release
cd /tmp wget https://dl.gitea.io/gitea/1.18.3/gitea-1.18.3-linux-amd64 -O gitea chmod +x gitea sudo mv gitea /usr/local/bin/
Replace 1.18.3 with the current tag if you’re reading this later. The binary is a single file, so there’s no package manager fuss.
6: Set up directories
sudo mkdir -p /var/lib/gitea/{custom,data,log}
sudo chown -R gitea:gitea /var/lib/gitea
data holds your repositories; log keeps the output tidy. Giving ownership to the Gitea user prevents permission errors when it creates new repos.
7: Choose a database
Gitea ships with SQLite, but for production we recommend MariaDB or PostgreSQL. Here’s a quick MariaDB set‑up:
sudo apt install mariadb-server -y sudo mysql_secure_installation # Follow prompts to set root password and remove anonymous users
Then create the Gitea database:
CREATE DATABASE gitea CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; GRANT ALL PRIVILEGES ON gitea.* TO 'gitea'@'localhost' IDENTIFIED BY 'yourStrongPassword'; FLUSH PRIVILEGES;
If you’re still on the learning phase, SQLite is fine—just skip the MariaDB steps and use the default config.
8: Configure Gitea
sudo -u gitea mkdir /etc/gitea cat <<EOF | sudo tee /etc/gitea/app.ini [database] DB_TYPE = mysql HOST = 127.0.0.1:3306 NAME = gitea USER = gitea PASSWD = yourStrongPassword [repository] ROOT = /var/lib/gitea/data/repositories [security] INSTALL_LOCK = true EOF
The INSTALL_LOCK flag blocks the web installer once you’re done; it’s a tiny but useful safety net. Adjust the host, user and password to match what you set up earlier.
9: Create a systemd unit
sudo cat <<EOF | sudo tee /etc/systemd/system/gitea.service [Unit] Description=Gitea (Git with a cup of tea) After=network.target [Service] RestartSec=2s Type=simple User=gitea Group=gitea WorkingDirectory=/var/lib/gitea ExecStart=/usr/local/bin/gitea web -c /etc/gitea/app.ini Environment="HOME=/home/gitea" SyslogIdentifier=gitea [Install] WantedBy=multi-user.target EOF
Why the RestartSec? Gitea occasionally spawns a child process that needs a small pause before retrying. It keeps the service from hammering the CPU.
10: Start it up
sudo systemctl daemon-reload sudo systemctl enable --now gitea.service
Check status:
systemctl status gitea
You should see “active (running)”. If not, look at journalctl -u gitea for clues.
11: Open the firewall
If you’re on a fresh server with UFW or firewalld, expose the default Gitea port:
sudo ufw allow 3000/tcp
Or add it to firewalld’s permanent rules if you prefer that stack.
12: Hit the web UI
Open http://your‑server-ip:3000 in a browser. The first time you hit this, you’ll be greeted with an account creation wizard. Log in with a username and password of your choosing; the database credentials you entered earlier will already be wired in.
Once inside, feel free to tweak settings—enable SSH, set up email notifications, or integrate your favorite CI tool. Gitea’s UI is snappy enough that you won’t need to touch the command line again.
13: Common gotchas
- Wrong binary architecture – If you accidentally download an ARM build on an x86 server, it will refuse to start. Double‑check the URL or let wget fetch the correct one.
- File permissions on repositories – After cloning a repo as root, Gitea may lose access. Always clone and push through the gitea user’s SSH key.
- Database connection errors – A misspelled password in app.ini is a classic “why isn’t my app starting?” culprit.
I once had a friend who pointed the service to a MySQL server on a different host, but forgot to open port 3306. The log complained about “connection refused”, and all we did was add an exception in /etc/hosts.deny. Lesson: double‑check network reachability before you blame Gitea.
14: Wrap it up
You’ve got a self‑hosted Git server that can scale from one repo to dozens, all running on a clean Ubuntu or Debian box. From here, the real fun begins—creating teams, setting up webhooks, and maybe even building an internal code‑review workflow.
