Improve dev documentation

[kobergj]

Dev documentation has a few flaws that users could run into when using ocis for the first time.

Summary:

• Installing pnpm alone is not enough, Node.js needs to be installed as well.
• Installing any Node.js is also not enough. Ubuntu 22.04 provides version v12.22.9, which is too old. There are several ways how to update it, but maybe the best one is here: https://deb.nodesource.com/
• OCIS_INSECURE always needs to be set, even if ocis init was already executed with insecure flag
• OCIS_URL needs to be set always

For background information see this ticket: #7391

[isbm]

Easiest if it will be written that the OCIS_URL needs to point to the real IP address.

[rhafer]

• OCIS_INSECURE always needs to be set, even if ocis init was already executed with insecure flag

@kobergj I might be missing something. But isn't that a bug we should fix in ocis init then?

[kobergj]

I might be missing something. But isn't that a bug we should fix in ocis init then?

Also an option. I wasn't sure if this might be intentional so only event tls is deactivated when running ocis init with insecure flag...

[isbm]

@rhafer I am also still wondering why this env var is even needed to be explicitly defined, if ocis init just asked if a user wants it insecure (y/N)?

[rhafer]

I am also still wondering why this env var is even needed to be explicitly defined, if ocis init just asked if a user wants it insecure (y/N)?

@isbm Right. And actually for me it is working just fine without setting OCIS_INSECURE. And that's how it is supposed to be. I wonder if it was just a follow up error for the wrongly set OCIS_URL in your case. Can you try again if ocis runs for you without OCIS_INSECURE set. (If it doesn't please reopen the other bug, so that we can try to find out what's going wrong.)

[mmattel]

Admin docs relevant, hooking myself in to be in the loop.

[isbm]

@isbm Right. And actually for me it is working just fine without setting OCIS_INSECURE.

Yes, it actually works. 👍🏼 I actually had checked exactly this yesterday as it would be the next logical step, since the variable does not really affects anything, just simply forgot to report it here, sorry.

I still get those errors on the STDOUT about handshake error (as an info, I guess), but I still think it should actually be quiet, because config says so.

I wonder if it was just a follow up error for the wrongly set OCIS_URL in your case.

Yes, that precisely it is: I am trying to run ocis in a dedicated VM and then talk to that VM from the browser using IPv4.

To my defence, my overall experience with oCIS is only few hours 😉 so yes, docs/ocis/deployment/basic-remote-setup.md says that explicitly and I was just blind:

OCIS_INSECURE=true \
PROXY_HTTP_ADDR=0.0.0.0:9200 \
OCIS_URL=https://your-host:9200 \
         ^^^^^^^^^^^^^^^^^^^^^^
./ocis server

Summarising, I think it would be a very good idea to explicitly emphasize the OCIS_URL part in the quick start documentation section.

I have also a question: why all that is in env variables, but in ocis.yaml? At least in my case ocis.yaml does not contain anything for proxy HTTP address or URL, but it does contain the insecure part. It has proxy, it has passwords, secrets etc. Shouldn't it be just there instead? Something like:

ocis_url: "https://10.20.30.40:9200"
proxy:
  insecure_backends: true
  service_account:
    ...
  http_addr: "0.0.0.0:9200"

[rhafer]

Yes, it actually works. 👍🏼 I actually had checked exactly this yesterday as it would be the next logical step, since the variable does not really affects anything, just simply forgot to report it here, sorry.

Ok, cool. Good to know.

I still get those errors on the STDOUT about handshake error (as an info, I guess), but I still think it should actually be quiet, because config says so.

AFAIK these errors are coming directly form the net/http module. And only happen upon the first connection attempt of a client, which abruptly closes the connection because in can't verify the TLS certificate (resulting in that handshake error on the server side). There is not much we can do about those. AFAIK you don't see them any more once you have accepted/ignored the certificate warning in the browser.

I have also a question: why all that is in env variables, but in ocis.yaml? At least in my case ocis.yaml does not contain anything for proxy HTTP address or URL, but it does contain the insecure part. It has proxy, it has passwords, secrets etc. Shouldn't it be just there instead? Something like ...

Ideally yes. Though OCIS_URL is somewhat special I think. It is used in a ton of different contexts, also depending on the setting of other configs. Though I agree, simplifying that would be great.

[isbm]

Ideally yes. Though OCIS_URL is somewhat special I think. It is used in a ton of different contexts, also depending on the setting of other configs. Though I agree, simplifying that would be great.

RedirectURIs: []string{
    "{{OCIS_URL}}/",
    "{{OCIS_URL}}/oidc-callback.html",
    "{{OCIS_URL}}/oidc-silent-redirect.html",
},

😭

[isbm]

@rhafer should the config reading/parsing to be finished at this point right after EnsureCommons? As it looks like then it just passed to the Server and then used.

[dschmidt]

I would like to add: docs/ocis/development/build.md gets you started for a single build, but it doesn't tell you anything about how to do incremental builds when changing anything in a service which is not picked up by make...