Craft your forge // Build your project // Grow your community freely
1<!--
2SPDX-FileCopyrightText: 2025 Romain Maneschi <romain@gitroot.dev>
3 4SPDX-License-Identifier: CC-BY-SA-4.0
5--> 6 7# From zero to hero
8 9You are intriged by GitRoot, but want to try it before deploye one instance? In this tutorial I propose to you to launch a local instance on your post. Linux users you are welcome, Mac one should work but never tested, **Windows user sorry but this will not work**.
10 11## Download and run
12 13Dowload: `wget -O gitroot https://gitroot.dev/releases/gitroot-last && chmod +x gitroot`. Warning: `gitroot-last` is for linux-amd64, others arch/cpu can be found in [versions page](../../CHANGELOG.md).
14 15Initialisation: `./gitroot --initConfig ./conf.yml`. You can review the file `conf.yml`, but for now default configuration should be good.
16 17Run: `./gitroot -config="./conf.yml" -data="./data"`.
18 19GitRoot will create a directory `data` where you launch it. All its data will be stocked here. By default GitRoot listen to port `4545` for ssh and `4546` for http.
20 21> Reminber to delete the `./conf.yml` file, after the first launch all configurations are stored in the root repository.
22 23## Clone root repository
24 25In GitRoot all is stored in git. Even the repositories hosted on your instance. You need to clone the [root repository](../technicals/root_repository.md) to discover repositories or to add a new one (replace admin with the pseudo you want to use): `$PSEUDO=admin git clone ssh://$PSEUDO@127.0.0.1:4545/ root && cd root`.
26 27## Create your first repository
28 29In the [root repository](../technicals/root_repository.md) open `.gitroot/repositories.yml` and add:
30 31```diff
32 root:
33 kind: normal
34 defaultbranch: main
35+ repo1:
36+ defaultbranch: main
37``` 38 39Commit and push, GitRoot will build your new repo: `git add . && git commit -m "add repo1 repository" && git push`.
40 41By default GitRoot use `main` has [defaultBranch](../technicals/default_branch.md) but you can put every name you like.
42 43You can clone and use your new repository: `git clone ssh://127.0.0.1:4545/repo1` 44 45> To delete a repository see [delete repository](../how-tos/delete_repository.md)
46 47## Install plugin
48 49GitRoot by itself don't do so much, but when you add some plugins it start to be a full forge.
50 51Before using a plugin in your repo, instance forge need to install it.
52 53In your [root repository](../technicals/root_repository.md) edit `.gitroot/plugins.yml` and add your first plugin:
54 55```yml
56- purl: pkg:gitroot/$scope/$name@$version?checksum=$checksum®istry=$url
57``` 58 59> Find plugin PURLs and more on the [gitroot registry](../../plugins/index.md).
60 61Git commit and push: `git add . && git commit -m "add lot of plugins" && git push` 62 63GitRoot add all default configuration requiered for this plugin but not active it.
64 65After a `git pull` you will see that GitRoot had added a commit in your [root repository](../technicals/root_repository.md) and in all repositories of your forge.
66 67```diff
68 purl: pkg:gitroot/$scope/$name@$version?checksum=$checksum®istry=$url
69+ name: plugin
70+ active: false
71+ run:
72+ - path: issues/**/*.md
73+ branch:
74+ - "*"
75+ when:
76+ - add
77+ - mod
78+ write:
79+ git:
80+ - path: issues/**/*.md
81+ can:
82+ - mod
83+ web: []
84+ configuration:
85+ metadata:
86+ - default: autogenerated
87+ mandatory: true
88+ name: id
89+ type: crc16
90+ - default: 50.0
91+ mandatory: true
92+ name: priority
93+ type: int
94``` 95 96> Want to delete a plugin? See [delete a plugin](../how-tos/delete_plugin.md)
97 98## Use a plugin
99100In any repository with plugin installed you can turn `active: false` to `active: true` in the `.gitroot/plugins.yml`. Don't forget to look/edit default configuration.
101102```diff
103 purl: pkg:gitroot/$scope/$name@$version?checksum=$checksum®istry=$url
104- active: false
105+ active: true
106 run:
107 - path: issues/**/*.md
108```109110For more details on plugins rights [read the documentation](../how-tos/plugin_rights.md).
111112## Configure an executor
113114If you want more than what the plugin ecosystem can provide, [configure an executor](../technicals/executors.md) and use all the tools you want.
115116## Play with your forge
117118Congratulation you have a full forge on your desktop! You can start developping something fun.
119120You can [customize the web representation](../how-tos/customize_web.md) of your repository. Or you can use some [plugins](../index.md#plugins).
121122But this is on your computer, you can't invite friends to play with you. For that you need to use an instance available on the web follow [deploy an instance](./deploy_instance.md) to do that.
123124Or find a provider and [use it](./use_instance.md).
125126But in any case enjoy your life.