Gitea is like GitHub and Gitlab. A git backend with a web gui with a eye candy (*Just like GitHub). To be honest I have nothing to say as I think it's self explained.
It's easy to host it but before I start I will assume that:
* You are running debian 11
* You already have a VPS: https://blog.esmailelbob.xyz/how-to-get-a-vps
* Your linux distro is up-to-date (sudo apt update && sudo apt upgrade
)
* You have a domain name: https://blog.esmailelbob.xyz/how-to-get-a-domain-name
* Have sudo access or root account
* Already installed docker and docker-compose: https://blog.esmailelbob.xyz/how-to-install-docker-and-docker-compose
* Already installed Nginx: https://blog.esmailelbob.xyz/how-to-install-and-configure-nginx-96yp
* Already have a reverse proxy conf file: https://blog.esmailelbob.xyz/how-to-use-reverse-proxy-with-nginx
* Already have certbot to issue cert: https://blog.esmailelbob.xyz/how-to-use-certbot-with-nginx-to-make-your-website-get
System Requirements
CPU: 2 CPU cores
RAM: 1GB
Changes in DNS (domain side)
You really do not need to add any dns entries except if you want to create subdomain for this container then you go in your domain's dns panel and add either CNAME entry that looks like subdomain.domain.com and make it's target the root domain domain.com or A entry with subdoamin.domain.com and make it's target the IP of your VPS
Initial setup
We need a docker-compose.yml
file but first we need to do some initial setup first so:
. First we need to create a new user account on our VPS (host machine*) and we will name that user git
and Add a password for it:
sudo useradd -m git
sudo passwd git
*. Second we login using the git user:
```bash
su git
And we now need to run these commands (save their output for later):
echo $(id -u)
echo $(id -g)
Now get back (press ctrl+d)
gitea docker-compose file
Now we prepare our docker-compose.yml file:
version: "3"
networks:
gitea:
external: false
services:
server:
image: gitea/gitea
container_name: gitea
environment:
- USER_UID=1001 # Enter the UID found from previous command output
- USER_GID=1001 # Enter the GID found from previous command output
- GITEA__database__DB_TYPE=mysql
- GITEA__database__HOST=db:3306
- GITEA__database__NAME=gitea
- GITEA__database__USER=gitea
- GITEA__database__PASSWD=giteaaa
- GNUPGHOME=/data/git/.gnupg/
restart: always
networks:
- gitea
volumes:
- ./data:/data
- /etc/timezone:/etc/timezone:ro
- /etc/localtime:/etc/localtime:ro
- /home/git/.ssh/:/data/git/.ssh
ports:
- "127.0.0.1:3330:3000"
- "127.0.0.1:2222:22"
depends_on:
- db
db:
image: mysql
restart: always
environment:
- MYSQL_ROOT_PASSWORD=gitea
- MYSQL_USER=gitea
- MYSQL_PASSWORD=gitea
- MYSQL_DATABASE=gitea
networks:
- gitea
volumes:
- ./mysql:/var/lib/mysql
Required stuff to change:
USER_UID: Change this to what number we got from running echo $(id -u) command as the git user
USER_GID: Change this to what number we got from running echo $(id -g) command as the git user
MYSQL_PASSWORD and MYSQLROOTPASSWORD: These passwords for our gitea database so you know, change them?
Optional stuff to change:
127.0.0.1:3330:3000: Change this to server gitea online (using nginx later)
127.0.0.1:2222:22: This is needed if we will use ssh to clone our repos
– ./data:/data: This is where our config files and other needed data will be saved for gitea
– /home/git/.ssh/:/data/git/.ssh: This is for ssh, We will create a ssh key later for the git user
– GNUPGHOME=/data/git/.gnupg/: This is where git will look for gpg keys to sign commits, since gitea 1.17 they changed folder, if you will start fresh install you would not need it but for someone like me I had to change where folder located
Spin it up!
Now after we done editing, and everything is cool. We need to run our container so just run:
docker-compose up -d
the -d
option does not let docker post logs of running application but if you want to see logs you can run:
sudo docker-compose logs -f -t
To check if there any weird behaviors or errors
nginX
Now after we make sure it's running well. We need to serve it over the internet (called reverse proxy) so without much talk, here is our server block for gitea:
server {
listen [::]:80;
listen 80;
server_name [domain name] ; ;
location / {
include /etc/nginx/reverse-proxy.conf;
proxy_pass http://127.0.0.1:3330/;
}
}
server_name: Change this to match domain name of gitea
include: is our reverse proxy file
proxy_pass: the IP and port of our running docker image
After we run it, visit gitea in your browser and we really do not need to change anything. You can change settings of “Administrator Account Settings”, “Server and Third-Party Service Settings” and “Email Settings” you will find these under “Optional Settings” Section at end of the page but other than that I really recommend to not change other settings like gitea base URL because after some trial and error I noticed when I change that later in app.ini
file (more about that later) gitea actually work and I can clone fine.
So after we done we need to edit app.ini
(If you used my docker file, it should be located in: data/gitea/conf/app.ini) and change DOMAIN and SSH_DOMAIN to our gitea domain name, for my case it was git.esmailelbob.xyz
and change ROOT_URL to be “https://
” + our gitea domain name so it would look like https://git.esmailelbob.xyz/
in my case. Now restart docker-compose (docker-compose down; docker-compose up -d
) and you are good to go :)
After this you should be up and running for gitea! :) just do not forget to run certbot --nginx
to make it secure with https://
Update it
Of course after some time the image will be outdated and you need to update and what I love about docker that it's easy to update, really just to do it run:
docker-compose down && docker-compose pull && docker-compose up -d
What it does is: 1) Stops the container, 2) Pull last update (download last update) and 3) Re-run the container back!
Firewall
If you use firewall (ufw for example) you really do not need any ports other than 443 and 80 as we use nginx reverse proxy
Now we enable SSH for our gitea instance – This is Optional
If you want to enable SSH clone. It's easy to enable for gitea docker.
Host machine, VPS or server
We need to do all of these steps on our VPS side.
. Make sure we already mapped ssh port in our docker compose file (If you follow along, you already done this*)
ports:
[...]
- "127.0.0.1:2222:22"
. Make sure we already added UID and GID of git user in our docker compose file (If you follow along, you already done this*)
environment:
- USER_UID=1000 # this is for example, please change it
- USER_GID=1000
*. We need to mount .ssh of git user inside docker-compose file so this ensure that both git user on our Host or VPS and git user inside docker-compose both allow access of our SSH keys (If you follow along, you already done this)
volumes:
- /home/git/.ssh/:/data/git/.ssh
. Now generate SSH key for gitea itself. This key pair will be used to authenticate the git user on the host to the container (no need to switch to git for this*)
sudo -u git ssh-keygen -t rsa -b 4096 -C "Gitea Host Key"
*. Now copy SSH key we created for git user to authorized_keys
( Again no need to change to user to use git on host or VPS ) so both git user and git user inside docker of gitea get same copy of authorized ssh keys:
sudo -u git cat /home/git/.ssh/id_rsa.pub | sudo -u git tee -a /home/git/.ssh/authorized_keys
sudo -u git chmod 600 /home/git/.ssh/authorized_keys
*. Now we can view /home/git/.ssh/authorized_keys (cat /home/git/.ssh/authorized_keys
) and make sure it looks like:
# SSH pubkey from git user
ssh-rsa <Gitea Host Key>
*. Now we need to create a executable script:
cat <<"EOF" | sudo tee /usr/local/bin/gitea
#!/bin/sh
ssh -p 2222 -o StrictHostKeyChecking=no git@127.0.0.1 "SSH_ORIGINAL_COMMAND=\"$SSH_ORIGINAL_COMMAND\" $0 $@"
EOF
sudo chmod +x /usr/local/bin/gitea
This script forward commands from git host to gitea container
Now get back to our client or desktop
We need to do all of these steps on our desktop or own PC side.
So now on PC simply create a ssh key:
ssh-keygen -t ECDSA
And go to ~/.ssh/` and get the public key of your SSH key and login to your gitea and in settings ([gitea domain url]/user/settings) import your SSH key. And create a repo for test and try to clone it over SSH :)
For more info please get back to gitea docs at https://docs.gitea.io/en-us/install-with-docker/#sshing-shim-with-authorized_keys
Now we enable GPG commit sign for our gitea instance – This is Optional
If you want to see that sweet little green lock beside your commits and to let people know that it was really you who made those changes, You need to enable GPG key signing inside gitea and it's simple!
First we need to login inside docker itself as the git user (do not mix it up with git user on our host machine) to do so just type:
docker exec -it -u git gitea bash
Now do not panic you are inside gitea docker container as the git user! we simply need to generate a gpg key pair which is simple as:
gpg --full-generate-key
Answer questions and make sure to type name and email right as we need to use them later!
* If you get permissions error (gpg: WARNING: unsafe permissions on homedir '/home/path/to/user/.gnupg) you might want to try
chown -R $(whoami) data/git/.gnupg/
chmod 600 ~/.gnupg/* data/gitea/home/.gnupg/
chmod 700 ~/.gnupg data/gitea/home/.gnupg/
data/git/.gnupg/: Is where .gnupg folder saved inside docker container, If you used same setup as mine you do not have to worry but if you changed volumes you might want to search where it's saved in your case!
After we done. You can run:
gpg --list-secret-keys
To list created keys and note their Id
, name
and email
(we need them for later)
Now, logout of container (press ctrl+d
or type exit
) and now edit app.ini file (data/gitea/conf/app.ini) and paste (this is my setup i use):
[repository.signing]
DEFAULT_TRUST_MODEL = collaboratorcommitter
SIGNING_KEY = defualt
SIGNING_NAME = gitea
SIGNING_EMAIL = gitea@esmailelbob.xyz
INITIAL_COMMIT = always
CRUD_ACTIONS = always
WIKI = always
MERGES = always
SIGNING_KEY: Leave it as is (more on that later).
SIGNING_NAME: Type same name you typed while you were creating the GPG key
SIGNING_EMAIL: Type same email you typed while you were creating the GPG key
Now you need to restart docker (docker-compose down; docker-compose up -d
) and go to your git domain.com/api/v1/signing-key.gpg
(Ex: git.esmailelbob.xyz/api/v1/signing-key.gpg
) and make sure you see a public gpg key displayed, If you see an empty page try to change SIGNING_KEY
in app.ini
to key's ID itself not default.
Now we need to login back in docker as git user (docker exec -it -u git gitea bash
) and we need to create a .gitconfig
file in data/git/.gitconfig (Again, if you followed my docker compose setup it should be in same order so do not worry but if you changed volumes then you need to search where git folder saved) and your .gitconfig
file it should look like:
[user]
email = git@esmailelbob.xyz
name = gitea
signingkey = 55B46434BB81637F
[commit]
gpgsign = true
[gpg]
program = /usr/bin/gpg
[core]
quotepath = false
commitGraph = true
[gc]
writeCommitGraph = true
[receive]
advertisePushOptions = true
procReceiveRefs = refs/for
What need to change are:
email: Type email that you typed while creating gpg. Should match your GPG key we created
name: Type name that you typed while creating gpg. Should match your GPG key we created
signingkey: Your GPG key ID that we created
Now leave gitea container bash and restart docker (docker-compose down; docker-compose up -d
) and now give it a try :). Make a test repo and try to commit stuff and you should see the magic green lock
NOTE 1: After you make key, export it's public key and add it inside your gitea account in settings ([gitea domain url]/user/settings) .
NOTE 2: If you want to for example only sign commits if user has gpg key in their account or never commits at all you can do that, please get back to gitea docs to see the other options but for me I wanted it to ALWAYS sign commits
For more info please get back to gitea docs at https://docs.gitea.io/en-us/signing/
NOTE 3: It's not related to gitea but it's related to gpg and git. On your PC if you want to enable gpg sign too:
*. Generate gpg key (gpg --full-generate-key
) and grab it's ID, name and email for later
*. Edit .gitconfig (~/.gitconfig) file on your own desktop (not VPS/Host machine) to make it look like:
[filter "lfs"]
clean = git-lfs clean -- %f
smudge = git-lfs smudge -- %f
process = git-lfs filter-process
required = true
[user]
name = Esmail EL BoB
email = esmail@esmailelbob.xyz
signingkey = 4984C22F0C5CACDE73B05243F44C953A3C7A4E16
[http]
sslBackend = openssl
[commit]
gpgsign = true
And change name
, email
and signingkey
to same info you added while you were creating gpg key
. List GPG keys installed in your Desktop (gpg --list-secret-keys
) and view public key of our GPG key we just created (gpg --export --armor [key-id]
) and Add GPG public key to your gitea account via settings ([gitea domain url]/user/settings*).
Now you would be able to push commits and sign them automatically to gitea, github or any git really
Add more theme options in gitea – This is Optional
If you want to add more themes for gitea docker. We need to know what is our CustomPath
and if you follow along it should be data/gitea. So to add themes we need to get .css file and to tell app.ini (config file of gitea) what themes to enable so later we can select them from gitea webgui in settings.
So first let's created needed folders. Go to data/gitea and create a new folder called public and cd into it and create new folder called css so order would look like: data/gitea/public/css
cd data/gitea
mkdir public
cd public
mkdir css
cd css
Now It's time for .css
files, To do so we can search online for gitea themes or visit: https://gitea.com/gitea/awesome-gitea#user-content-themes to get some files for test.
We should be already in css folder so select .css
file you want and download it using wget:
wget [theme url]
Now it's time to edit app.ini to tell it to enable the theme(s) we downloaded in css folder! so open app.ini (should be in data/gitea/conf/app.ini) and paste:
[ui]
DEFAULT_THEME = gitea
THEMES = gitea,arc-green,plex,aquamarine,dark,dracula,hotline,organizr,space-gray,hotpink,onedark,overseerr,nord,earl-grey,github,github-dark
DEFAULT_THEME: Is default theme for all users and it's okay to leave as is really
THEMES: here list all of our downloaded themes, To know theme name you need to look at css file so it look like: theme-github.css here our theme name is github
Now restart docker (docker-compose down; docker-compose up -d
) and go to gitea and edit your settings (click on your profile picture from upper-right > click settings > select appearance from top bar – url should look like: [gitea domain]/user/settings/appearance) and select the theme you want and click “Update Theme” and you should be good to go :) – If you see nothing changed it means you either downloaded them in wrong folder or typed it's name wrong in app.ini so re-check it!
For more info please get back to gitea docs: https://docs.gitea.io/en-us/install-with-docker/#customization
#howto #selfhost #docker
Like my work?, support me: https://donate.esmailelbob.xyz