doc: add forge-instance details to gitea.md

[Infinoid]

I took a stab at describing the new forge-instance feature in gitea.md.

I wasn't completely sure about the wording of the "Enterprise level" point in the "Differences from GitHub" section, please adjust as needed.

[Infinoid]

FYI, we've been running in forge-instance mode for a week, it's still looking good.

Aside: I'm looking at customizing the gitea runner config to have a centralized, persistent cache server. Step 3 of this doc describes how the runner config should look. It would be nice if gitea.md mentioned this too, but I need to figure out the templates first. It looks pretty involved.

[gabriel-samfira]

This is great! Thanks!

[gabriel-samfira]

Aside: I'm looking at customizing the gitea runner config to have a centralized, persistent cache server. Step 3 of this doc describes how the runner config should look. It would be nice if gitea.md mentioned this too, but I need to figure out the templates first. It looks pretty involved.

The cache server setup seems interesting. Does the runner itself need to be configured to use it, or is this something that you can plug into using the actions/cache action? If no changes need to be done in GARM, I believe it would be a great addition to the docs.

[gabriel-samfira]

FYI, we've been running in forge-instance mode for a week, it's still looking good.

nice! I am hoping to finish the proxy server support soon and cut a new release, which will include the forge instance entity.

[Infinoid]

The cache server setup seems interesting. Does the runner itself need to be configured to use it, or is this something that you can plug into using the actions/cache action? If no changes need to be done in GARM, I believe it would be a great addition to the docs.

The runner itself needs to be configured to use it, by giving it a config file which tells it where the cache server lives:

cache:
  external_server: "http://<cache-server-host>:8088/"
  external_secret: "replace-with-a-strong-random-secret"  # must match the server

So that contains the (internal) hostname and password to connect to the cache server. So the template would need to write that to a file, then pass it to the runner with the -c config.yaml argument.

I think it's probably better to treat that as a separate issue. I just mentioned it as a heads up that this is what I'm looking at next.

[gabriel-samfira]

The cache server setup seems interesting. Does the runner itself need to be configured to use it, or is this something that you can plug into using the actions/cache action? If no changes need to be done in GARM, I believe it would be a great addition to the docs.

The runner itself needs to be configured to use it, by giving it a config file which tells it where the cache server lives:

cache:
  external_server: "http://<cache-server-host>:8088/"
  external_secret: "replace-with-a-strong-random-secret"  # must match the server

So that contains the (internal) hostname and password to connect to the cache server. So the template would need to write that to a file, then pass it to the runner with the -c config.yaml argument.

I think it's probably better to treat that as a separate issue. I just mentioned it as a heads up that this is what I'm looking at next.

So this can be done with a runner install template and extra_specs. No changes to GARM, unless we bake the runner install template changes into the default template.

Let me set up a gist. Gimme 30 min.

[gabriel-samfira]

Something like this:

Extra specs used on the pool:

{
  "extra_context": {
    "gitea_cache_address": "https://samfira.com",
    "gitea_cache_secret": "asdsadsafsdaasdgag"
  }
}

Runner install template used: https://gist.github.com/gabriel-samfira/fc126e801f6df813c06cf307eec8f276

Edit: For anyone stumbling on this, the extra_context data is bogus. Please don't copy/paste it. It won't work. It's just sample data.

[Infinoid]

Oh, that's very useful, thanks!

I wouldn't bake that into the default template as-is, though. These are not the only fields that users might want to fiddle with. I think a more general approach would be to pass in the full config.yaml file as a base64-encoded string.

[gabriel-samfira]

I wouldn't bake that into the default template as-is, though. These are not the only fields that users might want to fiddle with. I think a more general approach would be to pass in the full config.yaml file as a base64-encoded string.

The runner install template manager plus the extra_context key gives you huge flexibility. And given that we use a tiny wrapper that downloads the full script from the GARM api, size is not an issue. So people can abuse it in any way they need to :). The above example doesn't touch GARM code. Just template + extra_specs.

I updated it and added sudo at line 209, but otherwise, it works.

Feel free to extend it in any way you see fit.

[gabriel-samfira]

one more note:

We have this in the template:

getRunnerFile "systemd/unit-file?runAsUser={{ .RunnerUsername }}" "$SVC_NAME" || fail "failed to get service file"

This calls into GARM to generate the systemd unift file from a template. The reasoning was to be able to generate more complex files on systems that don't necessarily have tooling or are very minimal, but do have curl.

You may generate the systend unit files in the template, without calling into GARM for that. It's just a "convenience".

[Infinoid]

Feel free to extend it in any way you see fit.

I will! Thanks, the example really helps.