Remotely managing repositories

+ One of gotsysd(8)'s + coolest features is it's ability to let you manage your repositories + directly from + gotsys.conf(5). + For example, your server configuration will initially contain the following + snippet: +

+    repository gotsys {
+      permit rw flan_hacker
+    }
+

+ This declares a repository named gotsys and allows + flan_hacker to read and write to it. That is, the + flan_hacker user is allowed to clone and send new changes to the + repository. +

+ The gotsys repository is special, as it lets you manage your + repository space by committing changes to it. However, it is declared as + any other repository. For example, the following snippet creates three new + repositories: +

+    repository "public_repo_a" {
+      permit rw flan_hacker
+    }
+    repository "public_repo_b" {
+      permit rw flan_hacker
+      permit ro anonymous
+    }
+    repository "private_repo_c" {
+      permit rw flan_hacker
+    }
+

+ Just like with the gotsys repository, we declare three new + repositories that can be read and written to by the flan_hacker. + Note that public_repo_b also allows the anonymous user to + clone the repository, but not to send new changes to it, as it is declared + with the ro mode (read-only). Repositories that are readable by the + anonymous user will include a clone url in the summary of the + repository when browsing it with a web browser. +

+ Lastly, it is worth noting that there is currently no way to rename or + delete repositories via + gotsys.conf(5). + However, you can simply remove any repository declaration from your + configuration and the repository will no longer be accesible. +

Setting up a custom domain

+ A good way to personalize your repository space is by assigning it a custom + domain. This can be done as follows: +

+
+ Contact an + administrator and let them know you'd like to use a custom domain. You + will receive a confirmation informing you that the domain has been + configured, as well as an IP address. +
+
+
+ Create a DNS A-record using the registrar of your choice, and point it at + the provided IP address. +
+
+
+ Lastly, configure a web server in your + gotsys.conf(5) + using your custom domain. For example, the following snippet configures + one for no.vmmbugs.net: +
+
```
+    web server no.vmmbugs.net {
+      site owner "Vmm Hacker"
+    }
+    
```
+

Configuring authentication

+ The Game of Trees Hub configures all web servers with authentication + enabled by default. This requires visitors to log in before accessing your + repositories or website. However, it is up to you to configure who is + allowed to authenticate and who isn't. If you want anyone to be able to + authenticate, you can use the anonymous user, a reserved user + which doesn't need to be declared with the user directive: +

+    web server no.vmmbugs.net {
+      site owner "Vmm Hacker"
+      permit anonymous
+    }
+

+ This will present you with a login screen and instructions on how to + authenticate over ssh when visiting + no.vmmbugs.net. +

+ If you want only specific users to be able to authenticate, you need to + declare them first with the user directive: +

+    user flan_hacker {
+      authorized key ssh-ed25519 <base64-encoded key> flan_hacker@gothub.org
+    }
+    web server no.vmmbugs.net {
+      site owner "Vmm Hacker"
+      permit flan_hacker
+    }
+

+ Note that in this case you won't be presented with instructions on how to + authenticate, as it is expected from the permitted user to know how to do + so. +

+ You can set permit/deny rules for all repositories on a web + server, like we did in the examples above, or per-repository using the + repository directive within the web server block. +

+ As a nice bonus, enabling authentication gives your repositories and + website an added layer of protection against scraping bots. +

Configuring the visibility of repositories

+ When first configuring a web server, you may notice that no repositories + are shown in the repository index. This is because web servers on the Game + of Trees Hub are initially configured to hide all repositories, preventing + the accidental leakage of private repositories. You can use + repository-specific parameters to configure this behaviour. +

+ Repository-specific parameters can be set by using the repository + directive inside a web server block. For example, the following + snippet configures all repositories to be hidden by default, and + selectively unhides two repositories. +

+    web server no.vmmbugs.net {
+      site owner "Vmm Hacker"
+      permit anonymous
+      hide repositories on
+      repository "public_repo_a" {
+        hide repository off
+      }
+      repository "public_repo_b" {
+        hide repository off
+      }
+    }
+

+ If most of your repositories are public, you can spare yourself some + tipping by making all repositories visible by default, and hidding only the + private ones. +

+    web server no.vmmbugs.net {
+      site owner "Vmm Hacker"
+      permit anonymous
+      hide repositories off
+      repository "private_repo_c" {
+        hide repository on
+      }
+    }
+

+ If you decide to do this, be careful not to leak any private repositories! +

Validate your configuration

+ Invalid configurations will be automatically rejected by the server when + sending changes to it. To avoid this, you can validate your configuration + before committing any changes with the following + gotsys(1) + command: +

+    $ gotsys check -f /path/to/gotsys.conf
+

+ This will report any errors in your configuration. Once there are no more + errors, the command will output configuration OK, at which point you + can safely send your changes to the server. +