GitRoot

  1<!--
  2SPDX-FileCopyrightText: 2025 Romain Maneschi <romain@gitroot.dev>
  3
  4SPDX-License-Identifier: CC-BY-SA-4.0
  5-->
  6
  7# Deploy a GitRoot instance
  8
  9This tutorial explain you how to deploy a GitRoot instance.
 10
 11There 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](https://www.ovh.com) with debian 12.
 12
 13## Pre-requists
 14
 15To follow this tutorial you need:
 16
 17- full access to a VPS (need to manage network ports espacially to route port 22 tcp)
 18- a domain name pointing to this VPS (not strictly mandatory but better, nobody want to `git clone ssh://54.37.255.71:22`)
 19
 20## Server initialisation
 21
 22Before starting installing GitRoot itself, we need to change some system configuration.
 23
 24### Change default ssh port
 25
 26By 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/`.
 27
 28To do that:
 29
 30- `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.
 31- then `sudo systemctl restart sshd`. Now you should be able to connect to your server host by `ssh user@ip -p XXXXX`
 32
 33### Install a firewall
 34
 35In this tutorial I use [ufw](https://launchpad.net/ufw), but you can use any firewall you like.
 36
 37- `sudo apt install ufw`
 38- 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`
 39- add a rule at the end of `sudo nano /etc/ufw/before.rules` (after last COMMIT):
 40
 41```
 42*nat
 43:PREROUTING ACCEPT [0:0]
 44-A PREROUTING -p tcp --dport 22 -j REDIRECT --to-port 4545
 45COMMIT
 46```
 47
 48- allow your ssh connection to the host `sudo ufw allow tcp/XXXXX`
 49- allow ssh `sudo ufw allow ssh`
 50- allow https if you want to have an http view of your forge (not mandatory but hardly recommended) `sudo ufw allow https`
 51- allow internal GitRoot ssh port `sudo ufw allow 4545/tcp`
 52- activate all your rules `sudo ufw enable` or restart the service `sudo systemctl restart ufw`
 53
 54### Install a reverse proxy
 55
 56I use [caddy](https://caddyserver.com/) but any reverse proxy should work.
 57
 58- follow instruction [here](https://caddyserver.com/docs/install#debian-ubuntu-raspbian)
 59- configure your new backend `sudo nano /etc/caddy/Caddyfile` with:
 60
 61```
 62yourDomainName.yourTLD {
 63    reverse_proxy localhost:4546
 64}
 65```
 66
 67- reload caddy config `caddy reload -c /etc/caddy/Caddyfile`
 68
 69## GitRoot installation
 70
 71Grab a copy of the GitRoot binary and launch it:
 72
 73- `cd ~/gitroot/`
 74- `wget -O gitroot https://gitroot.dev/gitroot-0.1.0`
 75
 76### GitRoot pre-init configuration
 77
 78As 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:
 79
 80```yaml
 81sshaddr: 0.0.0.0:4545
 82httpaddr: 0.0.0.0:4546
 83domainname: localhost
 84rootcommitername: GitRoot
 85rootrepositoryname: root
 86defaultbranch: main
 87nbworkerinbackground: 3
 88```
 89
 90At least you should change the `domainname` property with `yourDomainName.yourTLD` but others parameters can be modified as you like.
 91
 92The 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`.
 93
 94After all is modification is done, run `./gitroot --config ./conf.yml --data ./data/`, GitRoot will generate all initial data needed in the `./data/` directory.
 95
 96> If this repository exist, GitRoot will not touch it and use it.
 97
 98You 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.
 99
100> Reminber to delete the `./conf.yml` file, like that your collegue will not misunderstand its purpose.
101
102But if you leave your ssh session, GitRoot will be closed by the system. To make GitRoot persistent run it with systemd.
103
104### Systemd configuration
105
106Add 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).
107
108> 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.
109
110```
111[Unit]
112Description=GitRoot service
113ConditionPathExists=/home/debian/gitroot/gitroot
114After=network.target
115StartLimitIntervalSec=60
116
117[Service]
118Type=simple
119User=debian
120Group=debian
121
122Restart=on-failure
123RestartSec=10
124
125WorkingDirectory=/home/debian/gitroot
126ExecStart=/home/debian/gitroot/gitroot --data ./data/
127
128[Install]
129WantedBy=multi-user.target
130```
131
132- reload systemd config `sudo systemctl daemon-reload`
133- launch gitroot on reboot `sudo systemctl enable gitroot`
134- launch gitroot `sudo systemctl start gitroot`
135
136## Congratulation
137
138If all is ok GitRoot should be accessible on (even if your are not ssh connected on the host):
139
140- https://yourDomainName.yourTLD
141- `git clone ssh://yourDomainName.yourTLD/`
142
143If not look at the logs with `journalctl -u gitroot.service`
144
145## Next
146
147Clone 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.
148
149Then make your [first project](../how-tos/create_repository.md) and if your instance is public don't forget to let us know by opening an issue on [gitroot.dev](https://gitroot.dev) and linking your domain.