Document setup policy reasoner

[DanielVoogsgerd]

Right now, it is quite the struggle to get the policy reasoner setup with Brane. It does not help that there is very little (or any?) documentation on it, by itself this would not be a problem (for me), but considering there is quite the layer of "helpers" when starting and creating images, it becomes very opaque what needs to be done to get everything to work nicely.

I think I'm through most of it, though, so let this be a reminder to add the docs when I finally have everything up and running.

Things that are still unclear:

• When starting the checker image, the checker complains that no Node file was provided: Node file path not specified (give it as either '--state-resolver "n=..."' or '--state-resolver "node-file-path=..."'), where does this need to be provided. Of course, I am providing a node-file when starting the worker image, but it seems like branectl does not seem to pass this on to the checker image.

[Lut99]

What do you mean by "helpers"?

And also, uhh that is unexpected. I don't think there's been a time where the reasoner has been working in the Brane container before we implemented this change, so it should be in the Dockerfile? Check Dockerfile.rls. But yes we desperately need policy-reasoner docs, lol, to document all this.

Note, by the way, that this flag is for the BraneApiStateResolver connector to tell it where to find a node.yml that explains where to find said brane-api. Should be easy to add (but again, weird it wasn't there before).

[DanielVoogsgerd]

What do you mean by "helpers"?

The elaborate build infrastructure, i.e. main.py, branectl (start), and docker buildx mostly. They are nice, but when debugging they create separation between what I am doing and what ends up actually happening, this can be a bit of a pain when you aren't intimately familiar with what is actually being done. So I end up spending a significant amount of time figuring out why something is cached, or why a flag isn't passed from x to y.

With this problem in particular, I wouldn't know where this nodefile should have been provided, for example.

We will figure it out, though.

[Lut99]

I see, right. You make a fair point.

What would help towards this? Collapse the helpers, or provide better documentation? I think that documenting the build system is actually not a bad idea regardless xD but do you think that would help you in this?

FYI, the nodefile is pointed-to by branectl (through branectl -n ...), then it passes the path as an env to the docker-compose-worker.yml file which then mounts it as a volume (at least, it should). The path which it mounts to in the container should be given as argument to the policy-reasoner binary in the compose file (through command:), but maybe it mounts at the default location and doesn't both. Or the Dockerfile.rls sets this itself with CMD (though I doubt that).

[DanielVoogsgerd]

What would help towards this? Collapse the helpers, or provide better documentation? I think that documenting the build system is actually not a bad idea regardless xD but do you think that would help you in this?

The thing that would help the most is getting the framework to work as a whole. If I have a working version of Brane it is way easier to make changes and not get lost in these kinds of problems, because there is something that works that I can reference that I know will work, but we are working on that, and I think quite close.

From that point, I think it is just some small changes here and there that would really help, but we'll see when we get there.

The big thing that I think we should reconsider is the way make.py is written. I am not entirely sure how it should be, but right now it is too big, abstract, and complex. It is basically one big OOP wrapper, with some really terse logic (the targets part). I do think we can improve on that in various ways, but I think we have bigger fish to fry.

[Lut99]

Lol. Yeah, it's a beast xD

Fair enough, then, let's keep it like this for now until your instance works. RE that: don't hesitate to hit me up if you encounter something!