There are many popular online code hosting platforms that help you store and manage source code of your projects,Github andGitlab are the most common solutions among developers. But sometimes you want to host projects on your local server, is that possible ?

Well, yeah! Gitlab offers a self-managed version ready to deploy, setting it up may be a complex task and requires time and experience. Gitlab is considered as a devops platform, if you don't need such complex solution, thenGitea is the best choice for you.

Gitea is a cross-platform lightweight code hosting solution written inGo. The goal of this great product is to offer an easy, fast and painless deployment of a self-hosted Git service.

In this tutorial, we will walk through the steps of Gitea deployment on a Debian server.

Setup local server virtual machine

For the purpose of this tutorial, we will be usingVagrant to create a Debian virtual machine that runs onVirtualbox hypervisor. Make sure that you have Virtualbox and Vagrant installed on your machine.

# Create the Vagrantfilemkdir-p ~/vagrant/debian-bullseye64vim ~/vagrant/debian-bullseye64/Vagrantfile

Here is the Vagrant configuration file to run a Debian 11 VM, with a bridged IP address :

Vagrant.configure("2")do|config|config.vm.box="debian/bullseye64"config.vm.network"public_network",ip:"10.0.0.20"config.vm.provider"virtualbox"do|vb|vb.gui=falsevb.memory="512"endend

Now you can boot up the VM :

cd ~/vagrant/debian-bullseye64vagrant up

Since we've set up a bridged connection, the Debian VM is accessible on the local network. To check if the VM responds, you can ping10.0.0.20(the IP address may not be the same in your network, check your configuration and update the VM IP address to match your subnet).

By default, Vagrant sets up anSSH server on the VM, you can access the shell by runningvagrant ssh, make sure that you are on the same directory of the Vagrantfile.

Setup database

Gitea requires one of the following relational databases :

• MySQL
• PostgreSQL
• MSSQL
• SQLite3
• TiDB

In this tutorial, we are going to useMariaDB, the open-source equivalent of MySQL.

To get MariaDB running on Debian VM, you need to install MariaDB server package :

# Install server packagesudoaptinstall-y mariadb-server# Launch the installationmysql_secure_installation

After the installation is finished, you need to create a new user and database :

createdatabase`gitea`;createuser'gitea'@'localhost'identifiedby'superSecReTPASSwD';grantallprivilegeson`gitea`.*to'gitea'@'localhost';flushprivileges;

Install Gitea binaries

At the date of this tutorial, the latest available version of Gitea is1.15.4, you can check the officialGitea website. Run the following commands to download Gitea binary :

wget-O gitea https://dl.gitea.io/gitea/1.15.4/gitea-1.15.4-linux-amd64chmod755 gitea# make the binary executablesudo mvgitea /usr/local/bin/# move binary to $PATHwhich gitea# check if gitea binary is available in $PATH

Now you can execute Gitea binary, a local server will be started on port3000 and bound to0.0.0.0 IP address, you can access Gitea externally from your browser by visitinghttp://10.0.0.20:3000. For now, we need to prepare the Debian VM for Gitea before using it.

Prepare virtual machine for Gitea

To make Gitea instance work properly on your server, you need to installGit :

sudoaptinstall-y git# check installed git versiongit--version

Create a new system user for Gitea :

sudoadduser\--system\--shell /bin/bash\--gecos'Gitea'\--group\--disabled-password\--home /home/git\   git

Create folder structure for Gitea repositories and configuration files :

sudo mkdir-p /var/lib/gitea/{custom,data,log}sudo mkdir /etc/gitea

Update permissions and change ownership of Gitea directories to the previously created Git user :

sudo chownroot:git /etc/giteasudo chown-R git:git /var/lib/gitea/sudo chmod-R 750 /var/lib/gitea/sudo chmod770 /etc/gitea

You should update permissions of/etc/gitea after installation, it was previously set with write permissions so the installer can write the configuration file.

chmod750 /etc/giteachmod640 /etc/gitea/app.ini

Now you can run Gitea server, make sure that you have exported the Gitea working directory variable(You can skip this step, we will later run Gitea with a Linux service) :

exportGITEA_WORK_DIR=/var/lib/gitea/# working directorygitea web-c /etc/gitea/app.ini# launch Gitea web server

If you get a permission error, don't panic ! The explanation of this behavior is that your current user could not read theapp.ini configuration file, your user should be a member of Git group. In my case, the current user isvagrant and it is not a member of Git group, adding it to that latter will fix the permission error.

sudousermod-aG git$USER

You can kill Gitea server by hittingControl+c.

Gitea service

Running Gitea server manually is not practical, the ideal solution is to configure it to run on the system startup, to do so, you need to write a customLinux service that starts Gitea every time the system boots up.

Create a newsystemd service and open it with your favorite editor, I will be using vim :

sudovim /etc/systemd/system/gitea.service

Since Gitea saves data on MariaDB database, our custom service should be run after MariaDB service.

[Unit]Description=GiteaAfter=syslog.targetAfter=network.targetWants=mariadb.serviceAfter=mariadb.service[Service]Type=simpleUser=gitGroup=gitWorkingDirectory=/var/lib/gitea/ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.iniEnvironment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/giteaRestartSec=2sRestart=always[Install]WantedBy=multi-user.target

Now you can enable and run Gitea service :

sudosystemctl daemon-reloadsudosystemctlenablegitea--now

Congratulations! Now you have Gitea service running and enabled at system startup, try to reboot the VM and access Gitea server by visitinghttp://10.0.0.20:3000, you should see the setup page for Gitea in a web UI.

Firewall configuration

If you are trying to deploy Gitea to a public server, then the usage of a firewall is recommended as a security measure. We will not dive in details into firewall configuration, but here are some basic commands to install and enable the firewall, and allow port 3000 through the firewall(the one that Gitea uses to serve the web UI) :

sudoaptinstall-y ufw# install uncomplicated firewallsudosystemctlenableufw--now# enable and run firewall servicesudoufwenable# change firewall status to activesudoufw allow 22/tcp# allow sshsudoufw allow 3000/tcp# allow Gitea

Gitea web UI

When you open Gitea web UI for the first time, you will be prompted with a configuration page, the web UI saves your configuration to/etc/gitea/app.ini, you can skip the settings page and set your configuration directly by editing the configuration file.

Enter the database information that you previously created :

You have also to setup Gitea general parameters :

Set up the administrator account :

Now you can hitInstall Gitea to apply configuration, you will be redirected to the login page. Use your administrator account to get access to your Gitea instance.

Custom configuration

There are many configuration options than can be applied to you Gitea instance, let's assume that we are using Gitea in a team, and only the administrator can create accounts for new members.

How to prevent users from creating accounts on our Gitea instance ? The solution is pretty simple, you have to ssh into the Debian VM (or your physical server) and edit theapp.ini configuration file. Under theservice section, updateDISABLE_REGISTRATION totrue.

[service]REGISTER_EMAIL_CONFIRM=falseENABLE_NOTIFY_EMAIL=falseDISABLE_REGISTRATION=true      <---...

Restart Gitea service :

sudosystemctl daemon-reloadsudosystemctl restart gitea

Now the registration feature is disabled :

All available configuration options are listed inGitea configuration cheat sheet.

Summary

In this tutorial, we set up a Debian VM with a bridged network connection, we created database configuration and we deployed Gitea. We also configured Gitea directly form the configuration file.

If you are trying to deploy Gitea to a public server with a domain name, you can useNGINX reverse proxy. This will let you set up a domain name and alsoSSL/TLS certficates.