Gitea is a painless self-hosted Git service written in Go and distributed under the MIT License, designed to provide similar core functionality as GitLab or GitHub, but at a much smaller resource footprint. The project started as a fork of the then-popular Gogs, but quickly became more active and bigger than the original.


For this guide you should be familiar with the basic concepts of


You’ll need your MySQL credentials. Get them with my_print_defaults:

[isabell@stardust ~]$ my_print_defaults client
[isabell@stardust ~]$

You need a database for gitea:

[isabell@stardust ~]$ mysql -e "CREATE  DATABASE ${USER}_gitea"
[isabell@stardust ~]$

Your gitea URL needs to be setup:

[isabell@stardust ~]$ uberspace web domain list
[isabell@stardust ~]$


Like a lot of Go software, gitea is distributed as a single binary. Download Gitea’s latest release, verify the checksum specified in the respective .sha256 file and finally make sure that the file can be executed.

[isabell@stardust ~]$ mkdir ~/gitea
[isabell@stardust ~]$ wget -O gitea/gitea
Resolving ( 2400:cb00:2048:1::681b:8e9b, 2400:cb00:2048:1::681b:8f9b,, ...
Connecting to (|2400:cb00:2048:1::681b:8e9b|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 52960072 (51M) [application/octet-stream]
Saving to: gitea/gitea’

100%[=======================================================>] 52,960,072  9.99MB/s   in 5.8s

2018-09-16 18:36:36 (8.72 MB/s) - gitea/gitea’ saved [60473144/60473144]
[isabell@stardust ~]$ sha256sum gitea/gitea
b84098f0b0018071aa1ba5522078820494def29e6385c25c581c4362a4e463b3 gitea/gitea
[isabell@stardust ~]$ chmod +x gitea/gitea
[isabell@stardust ~]$


Change the configuration

You need to create a custom directory

[isabell@stardust ~]$ mkdir -p ~/gitea/custom/conf/
[isabell@stardust ~]$

and a new config file at ~/gitea/custom/conf/app.ini to specify the port and domain and to disable public registration:

HTTP_PORT = 9000
ROOT_URL = https://%(DOMAIN)s


Gitea provides many other configuration options. Take a look at the Documentation to learn more.

Configure web server


Gitea is running on port 9000.

To make the application accessible from the outside, configure a web backend:

[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$

Setup daemon

Create ~/etc/services.d/gitea.ini with the following content:

command=%(ENV_HOME)s/gitea/gitea web

After creating the configuration, tell supervisord to refresh its configuration and start the service:

[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE                            RUNNING   pid 26020, uptime 0:03:14
[isabell@stardust ~]$

If it’s not in state RUNNING, check your configuration.

Finishing installation

Point your browser to the /install path on your domain to finish the installation.


Using the same public key for Gitea and your Uberspace will prevent you from logging in with this key via SSH. Login via password still works as expected, you can use the Dashboard to manage your keys.

SSH key management through gitea

If you want that gitea manages SSH authorized_keys you can do:

[isabell@stardust ~]$ ln -s ~/.ssh ~/gitea/

Add your key in gitea and then change the line in .ssh/authorized_keys to the following:

command="if [ -t 0 ]; then bash; elif [[ $SSH_ORIGINAL_COMMAND =~ ^(scp|rsync|mysqldump).* ]]; then eval $SSH_ORIGINAL_COMMAND; else /home/<username>/gitea/gitea serv key-1 --config='/home/<username>/gitea/custom/conf/app.ini'; fi",no-port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-...


Replace <username> with your username and put your public key after ssh-!


You can easily add AsciiDoc rendering to Gitea. Install asciidoctor via ruby gems:

[isabell@stardust ~]$ gem install asciidoctor

Edit your config file at ~/gitea/custom/conf/app.ini to enable asciidoctor in Gitea:

ENABLED = true
FILE_EXTENSIONS = .adoc,.asciidoc
RENDER_COMMAND = "asciidoctor -e -a leveloffset=-1 --out-file=- -"

In the end stop (supervisorctl stop gitea) and restart (supervisorctl stop gitea) Gitea. Try it with a .adoc or .asciidoc file.



Check the update feed regularly to stay informed about the newest version.

Check Gitea’s releases for the latest version. If a newer version is available, stop daemon by supervisorctl stop gitea and repeat the “Installation” step followed by supervisorctl start gitea to restart gitea.

Tested with Gitea 1.11.4, Uberspace 7.6.0

Written by: luto <>