Deploy a GitRoot instance

This tutorial explain you how to deploy a GitRoot instance.

There are as many way of deploying GitRoot as number of flowers in a prary. In this tutorial I explain how I have deployed GitRoot on gitroot.dev, a vps hosted on ovh with debian 12.

Pre-requists

To follow this tutorial you need:

• full access to a VPS (need to manage network ports espacially to route port 22 tcp)
• a domain name pointing to this VPS (not strictly mandatory but better, nobody want to git clone ssh://54.37.255.71:22)

Server initialisation

Before starting installing GitRoot itself, we need to change some system configuration.

Change default ssh port

By default sshd (the service which manage ssh connection to the host) is on port 22. But we want to use this port for GitRoot. User prefer to do git clone ssh://gitroot.dev/ instead of git clone ssh://gitroot.dev:4545/.

To do that:

• sudo nano /etc/ssh/sshd_config and change Port 22 by Port XXXXX where XXXXX is a random number who you are the only one to know.
• then sudo systemctl restart sshd. Now you should be able to connect to your server host by ssh user@ip -p XXXXX

Install a firewall

In this tutorial I use ufw, but you can use any firewall you like.

• sudo apt install ufw
• authorise redirect of port sudo nano /etc/ufw/sysctl.conf and uncomment the 3 lines about port forwarding net/ipv4/ip_forward=1, net/ipv6/conf/default/forwarding=1 and net/ipv6/conf/all/forwarding=1
• add a rule at the end of sudo nano /etc/ufw/before.rules (after last COMMIT):

1*nat
2:PREROUTING ACCEPT [0:0]
3-A PREROUTING -p tcp --dport 22 -j REDIRECT --to-port 4545
4COMMIT

• allow your ssh connection to the host sudo ufw allow tcp/XXXXX
• allow ssh sudo ufw allow ssh
• allow https if you want to have an http view of your forge (not mandatory but hardly recommended) sudo ufw allow https
• allow internal GitRoot ssh port sudo ufw allow 4545/tcp
• activate all your rules sudo ufw enable or restart the service sudo systemctl restart ufw

Install a reverse proxy

I use caddy but any reverse proxy should work.

• follow instruction here
• configure your new backend sudo nano /etc/caddy/Caddyfile with:

1yourDomainName.yourTLD {
2    reverse_proxy localhost:4546
3}

• reload caddy config caddy reload -c /etc/caddy/Caddyfile

GitRoot installation

Grab a copy of the GitRoot binary and launch it (binaries for others arch/cpu can be found in versions page):

• cd ~/gitroot/
• wget -O gitroot https://gitroot.dev/releases/0.2.0/gitroot-0.2.0-linux-amd64

GitRoot pre-init configuration

As all is stored in git, even the gitroot configuration, we need a way to configure gitroot before it start. To do that you can run ./gitroot --initConfig ./conf.yml it will create a conf.yml with default parameters:

1sshaddr: 0.0.0.0:4545
2httpaddr: 0.0.0.0:4546
3domainname: localhost
4rootcommitername: GitRoot
5rootrepositoryname: root
6defaultbranch: main
7nbworkerinbackground: 3

At least you should change the domainname property with yourDomainName.yourTLD but others parameters can be modified as you like.

The domainname is used to create the GitRoot (rootcommitername in config) user which will commit all the initial configuration in your forge. After your clone the root repository you will find some commits made by gitroot@yourDomainName.yourTLD with an ssh key generated and accessible in ./data/data/GitRoot.priv and ./data/data/GitRoot.pub. After that all plugins will have a user in the form of pluginName@yourDomainName.yourTLD.

After all is modification is done, run ./gitroot --config ./conf.yml --data ./data/, GitRoot will generate all initial data needed in the ./data/ directory.

If this repository exist, GitRoot will not touch it and use it.

You should be able to git clone ssh://yourDomainName.yourTLD/ on your desktop. And if you look at cat yourDomainName.yourTLD/.gitroot/forgeConfig.yml you will see all the informations you have put in the ./conf.yml file. Now, to modify something, you can change .gitroot/forgeConfig.yml in your clone, commit and push.

Reminber to delete the ./conf.yml file, like that your collegue will not misunderstand its purpose.

But if you leave your ssh session, GitRoot will be closed by the system. To make GitRoot persistent run it with systemd.

Systemd configuration

Add a systemd service to manage the binary and logs with sudo nano /lib/systemd/system/gitroot.service (in this example I am user debian in group debian, modify according to your server).

Warning: you need to update the ExecStart with the same -data="./data" has you have previously configured, else GitRoot will recreate all its datas with default configuration.

 1[Unit]
 2Description=GitRoot service
 3ConditionPathExists=/home/debian/gitroot/gitroot
 4After=network.target
 5StartLimitIntervalSec=60
 6
 7[Service]
 8Type=simple
 9User=debian
10Group=debian
11
12Restart=on-failure
13RestartSec=10
14
15WorkingDirectory=/home/debian/gitroot
16ExecStart=/home/debian/gitroot/gitroot --data ./data/
17
18[Install]
19WantedBy=multi-user.target

• reload systemd config sudo systemctl daemon-reload
• launch gitroot on reboot sudo systemctl enable gitroot
• launch gitroot sudo systemctl start gitroot

Congratulation

If all is ok GitRoot should be accessible on (even if your are not ssh connected on the host):

• https://yourDomainName.yourTLD
• git clone ssh://yourDomainName.yourTLD/

If not look at the logs with journalctl -u gitroot.service

Next

Clone as quickly as possible the root repository of your instance. The first user which will clone the root repo, will be the admin of this instance.

Then make your first project and if your instance is public don’t forget to let us know by opening an issue on gitroot.dev and linking your domain.