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_configand changePort 22byPort XXXXXwhereXXXXXis 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 byssh 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.confand uncomment the 3 lines about port forwardingnet/ipv4/ip_forward=1,net/ipv6/conf/default/forwarding=1andnet/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 enableor restart the servicesudo 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/Caddyfilewith:
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. Warning: gitroot-last is for linux-amd64, others arch/cpu can be found in versions page:
cd ~/gitroot/wget -O gitroot https://gitroot.dev/releases/gitroot-last
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.ymlfile, 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
ExecStartwith 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 repository, will be the admin of this instance.
You can install some plugins and configure an executor.
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.