[DOC] - JHub App Launcher missing assumption information

[jourdain]

Preliminary Checks

• This issue is not a question, feature request, RFC, or anything other than a bug report. Please post those things in GitHub Discussions: https://github.com/nebari-dev/nebari/discussions

Summary

In the documentation a list of "apps type" is provided but it is not clear what assumptions are associated to the Generic Python Command case or the others. Or even how someone could contribute another app type to that list.

I'm guessing some parameters needs to be passed or assumed (i.e.: port, ...)

It would be nice to provide some background on what an app can be and what is supported or missing.

Steps to Resolve this Issue

In my case, I was coming with the following set of questions:

1. How can I enable trame apps to be deployed within Nebari.
2. Does Nebari natively support trame requirements? (HTTP+WebSocket)
   • A sentence like so could provide such information: jhub-app-launcher start a new pod within our k8 environment with the provided Python environment and handle the routing of the network so the application just need to serve http content on a provided port along with ... On top of regular HTTP request Nebari forward WebSocket connection with automatic disconnection every 30 seconds.
3. Can I use the Generic Python Command or do I need to register a new type?
   • (Suggestion) The Generic Python Command will run the provided command and add the following args to specify on which port (--port {dynamic-port-value}) the app should run and what prefix url (--prefix /nebari/proxy/app/{xyz}) will be used in front of the http requests.
4. How can someone go about adding a new application type to the current list.

Other warning could be needed in case limitation exists, like:

Caution:

• WebSocket are not supported for apps
• WebSocket connection have a 30 second timeout due to our proxy infrastructure.

(All my suggestions are just speculation to provide some ideas on the kind of information a user/developer might be looking for but does not reflect the reality by any means.)

[aktech]

Hey @jourdain thanks for raising the issue. The documentation for custom apps isn't there yet. That's probably the reason for all the confusion.

The generic python command does support dynamic ports, here is an example for starting a simple python server:

http.server {port} {--}directory /shared/users/api/

In the above command the {port} is the argument to http.server and internally "port" will be replaced by a dynamic port. Also note that if your cli command has named arguments like say --some-argument, you'd need to add curly braces around the double dash to distinguish it with proxy command. We use jhsingle-native-proxy for running arbitrary apps (you can find the above mentioned info in their readme as well).

Can you share the command that you'd run locally to start the app? (also the code if public)

[jourdain]

A simple way to validate if any trame app can work, we might be able to validate it with the following.

Required environment:

pip install trame trame-vtk trame-vuetify

Possible command line for the demo app:

python -m trame.app.demo {--}server {--}port {port}

[jourdain]

I guess my naive try did not work. Thanks for your input so far but if you have any other idea or guidance that will be great...
I'll try playing with jhsingle-native-proxy to see if I can figure out something in an isolated environment.

[jourdain]

The following command seems to working fine locally, thanks for your input.

jhsingle-native-proxy --authtype=none --ip 0.0.0.0 -- python -m trame.app.demo --port {port} --server

[jourdain]

I guess in the context of a real deployment (nebari), do my app needs to do something specific for activity or health check?
It seems like the pod is timing out thinking the server/app did not start during the 600s timeout.

[aktech]

I did a quick test using the following environment:

channels:
  - conda-forge
dependencies:
  - jhub-apps
  - streamlit
  - gradio
  - voila
  - dash
  - ipykernel
  - trame
  - trame-vtk
  - trame-vuetify
  - vmtk

I had to add vmtk as well to the environment. I am seeing the following:

Command Running:

python3 -m jhsingle_native_proxy.conda_runner /opt/conda /home/conda/akumar@quansight.com/envs/akumar@quansight.com-jhub-apps python -m trame.app.demo --server --port 50771

Error output:

CONDA_PREFIX=/home/conda/akumar@quansight.com/envs/akumar@quansight.com-jhub-apps

Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "/home/conda/akumar@quansight.com/envs/akumar@quansight.com-jhub-apps/lib/python3.11/site-packages/trame/app/demo.py", line 68, in <module>
    main()
  File "/home/conda/akumar@quansight.com/envs/akumar@quansight.com-jhub-apps/lib/python3.11/site-packages/trame/app/demo.py", line 64, in main
    cone.server.start(**kwargs)
  File "/home/conda/akumar@quansight.com/envs/akumar@quansight.com-jhub-apps/lib/python3.11/site-packages/trame_server/core.py", line 651, in start
    task = CoreServer.server_start(
           ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/conda/akumar@quansight.com/envs/akumar@quansight.com-jhub-apps/lib/python3.11/site-packages/trame_server/protocol.py", line 50, in server_start
    return server.start_webserver(
           ^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/conda/akumar@quansight.com/envs/akumar@quansight.com-jhub-apps/lib/python3.11/site-packages/wslink/server.py", line 301, in start_webserver
    return exec_modes[exec_mode]()
           ^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/conda/akumar@quansight.com/envs/akumar@quansight.com-jhub-apps/lib/python3.11/site-packages/wslink/server.py", line 284, in main_exec
    loop.run_until_complete(create_coroutine())
  File "/home/conda/akumar@quansight.com/envs/akumar@quansight.com-jhub-apps/lib/python3.11/asyncio/base_events.py", line 653, in run_until_complete
    return future.result()
           ^^^^^^^^^^^^^^^
  File "/home/conda/akumar@quansight.com/envs/akumar@quansight.com-jhub-apps/lib/python3.11/site-packages/wslink/backends/aiohttp/__init__.py", line 111, in start
    await self._site.start()
  File "/home/conda/akumar@quansight.com/envs/akumar@quansight.com-jhub-apps/lib/python3.11/site-packages/aiohttp/web_runner.py", line 119, in start
    self._server = await loop.create_server(
                   ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/conda/akumar@quansight.com/envs/akumar@quansight.com-jhub-apps/lib/python3.11/asyncio/base_events.py", line 1525, in create_server
    raise OSError(err.errno, 'error while attempting '
OSError: [Errno 99] error while attempting to bind on address ('::1', 50771, 0, 0): cannot assign requested address

I see you mentioned it's working for you locally. What do you get when you run something like (locally):

python -m trame.app.demo --server --port 5000

[jourdain]

Thanks for looking into that.

Locally I don't get that bind error. But you could try to add a --host 0.0.0.0 to fix the ::1 binding issue.

Indeed, with that example of trame, we need to add vtk as dependency. (but we shouldn't and fixing that now)
In my testing, I did add vtk, but maybe I was running into a similar bind error. I was just not able to see the log.

[aktech]

I was able to get the trame app working by using the following command:

trame.app.demo {--}server {--}host 0.0.0.0 {--}port {port}

[jourdain]

Wow, thanks for following up on that, this is awesome!