Enhance on-boarding documentation & workflow for new users

[autonomousit]

What problem or use case are you trying to solve?
The current on-boarding process is split across multiple documentation sections and many of the default steps or instructions lead to unstable states. This is to be expected as a project grows and many new features are added but it would be helpful to re-assess this and try to streamline the process for new users to get started. This can be difficult for the maintainers to do as they have a lot of implicit knowledge that new users don't have and their dev environments may contain undocumented state that makes it hard for them to replicate the issues faced by new users. It also leads to unnecessary support workload for the maintainers as people try to get setup.

As someone with Python dev experience but unfamiliar with the project I'd like to volunteer to draft some enhanced documentation based on my own experience on getting started and

Describe the UX of the solution you'd like
There should be a clear Getting Started path that leads to a stable deployment and helps the user make key decisions based on the use case they have. There should also be clear migration or switching paths to change between different deployment methods without resulting in bad states. This is especially true of Development.md because many non-dev users may find themselves trying to implement this to access something like CLI mode.

Do you have thoughts on the technical implementation?
Some examples of things that I have come across in my own efforts to get things running the way I want:

• Development.md requirements setup is quite sparse and leads to errors (see [Bug]: pylcs wheel fails to install when running make build #5793 as an example). It requires python3.12-dev not just python3.12 and both Poetry (via pipx) and NPM (via nvm) have some very specific installation requirements that are not covered.
• The Persistent state setup in Development Mode is described as an optional extra however in my case it is required to maintain a stable environment (see [Bug]: GET /api/list-files HTTP/1.1" 401 Unauthorized  #5574 for an example).
• Many key configurations (such as a JWT secret) are limited to config.toml which can't be accessed when deploying via the docker image. There seems to be some undocumented environment variables that can be used for this (see the French and Chinese versions of troubleshooting.md on the 0.16.1 tag). It would be good to document any such environment variables that can be used to manipulate the docker deployment to achieve a similar running state as when using config.toml and Development mode.
• Development mode is used for much more then development and may be required by non-dev users to access CLI mode. It may be good to separate the instructions for running OpenHands in "local mode" (to access CLI mode for example) from the instructions for setting up a development environment in order to develop the Openhands project.
• Mounting a local storage path for the docker image local storage isn't really documented and changes from /.openhands in 0.16.1 to /.openhands-state in 0.17. There are some references to mounting these paths with docker run -v but they aren't explained and are poorly documented as to why you would do this. It also assumes the local path exists and if it isn't docker just fails to mount it silently without any errors which gives the impression that the volume has been mounted when it hasn't. This wouldn't be obvious to less experienced users.

Describe alternatives you've considered

Additional context
As a research architect for a tech company I have Python development experience as well as experience with LLMs, common tools like langchain, etc and other AI methods and technologies. As a new user to the project I think I have a good perspective on the on-boarding process and can help improve it in a way that might be difficult for the more experienced maintainers who have a lot of implicit knowledge of the project.

[enyst]

You are absolutely correct, and thank you for drafting / re-drafting some of this!

A note on this too:

Many key configurations (such as a JWT secret) are limited to config.toml which can't be accessed when deploying via the docker image. There seems to be some undocumented environment variables that can be used for this (see the French and Chinese versions of troubleshooting.md on the 0.16.1 tag). It would be good to document any such environment variables that can be used to manipulate the docker deployment to achieve a similar running state as when using config.toml and Development mode.

There's an attempt somewhere to document this...
https://docs.all-hands.dev/modules/usage/configuration-options
Hmm, it's a note at the start of each section.

The point here is: almost all settings that are in toml are also exposed as environment variables. So you can achieve almost anything by using only env, if you want. All of them are uppercase as environment vars.

The [core] section options are available as their uppercase variants, e.g. jwt_token as JWT_TOKEN. The options in sub-sections, like in [llm], [security], [sandbox], are available with the section prefix, e.g.

[llm]
model="gpt-4"

as LLM_MODEL.

The reason for "almost" is just that some features are too complex and not just a variable with a defined meaning, and those aren't exposed in env. In particular, it is possible for the user to define sub-sections, and those user-defined sections are not available in the env. But the system vars are.

[enyst]

Re: mounting openhands-state. This is fairly new, as you have noticed, and indeed it was bugged/in flux, just now. As per your older issue, it sounds like you may have run into a bug with it!

I'm not sure why we don't seem to have Development.md on the docs site. We should. I do agree with you that it can be useful actually, and I do remember linking it in topics here quite a number of times because it was needed.

[autonomousit]

Hey @enyst thanks for confirming the availability of env variables. I think the lack of visibility on this is the main reason many people are trying to deploy using Development.md because they think it's the only way to access certain features (I had this impression at first).

I think the goal should be that anyone who is only using OpenHands should only ever use the Docker deployment mode. Most people need just to set a persistent storage volume and a JWT secret and add an instruction file to their project. Then, some people will want to use a custom LLM provider or a custom sandbox (to install requirements.txt, for example). This is all fine for Web UI but there should also be some way to have Openhands start in CLI mode or headless mode in the docker container, then the user just SSHs into the container to access.

This would mean only people who truly intend to develop the Openhands app need to deploy locally. This would greatly simplify using Openhands and avoid non-dev users trying to do build steps and mess around with Makefiles, etc.

Anyway that's the vision :-)

[enyst]

That may have been the reason why it's not on the docs site, but it seems a bit confusing atm because we do have the Debugging page there, which assumes Development.md. 😅

I think running CLI and/or headless is possible with the docker app. Something like this https://docs.all-hands.dev/modules/usage/how-to/cli-mode#with-docker
Indeed AFAIK there are users who prefer it.

I really appreciate you taking a look at this! I think you're entirely correct that getting to know the project recently gives you a unique perspective we don't have, and won't realize what we don't have. 😅

[autonomousit]

Cool, happy to help. Let me checkout the env variables and the Docker deployment for CLI and headless and see if I can get all the main use cases running and documented.

[autonomousit]

@enyst - just setup my fork and looking at the docs. There is some overlap between the official website docs and the documentation files scattered through the code but its not completely 1:1. Is there a structure or method in what is in which place and what is the source of truth if they diverge? Is there a way you keep them in sync? Just trying to understand your practice so I can align with it and put things in the right place.

[enyst]

The docs on the website are deployed from this repo, /docs/modules folder.

Other than that, I don't have good answers, I'm afraid. I'd say the docs on the site are maintained well, compared to other info through the code, it's more likely that some readme is outdated, since it's less visible/used. There can be exceptions. The code itself is the source of truth. 😅 So I guess I'd suggest website first, but please, feel free to choose and ask for any detail you may want?

[neubig]

Hey @autonomousit , thanks so much for this!

IMO, ideally the documentation site should be good enough for OpenHands users to understand how to do everything.
We can have additional documentation within the code for OpenHands developers (those actually modifying the OpenHands code), but I don't think users should ever have to look at the documentation in the codebase.

@mamoodi might also have comments.

[autonomousit]

Thanks @enyst & @neubig - I just setup the docs dev environment using yarn and I get a warning regarding packages-lock.json that this is a non-yarn lock file. It's fine as it just ignores it and creates it's own package lock however I'm wondering if you know the origin of this file. If it's a legacy thing I'll just delete it and replace it with the yarn lock as part of my changes.

[mamoodi]

Thanks so much for this.

Things I would add:

• The basic "Getting Started" guides either in README, Doc website or Development mode should address getting OpenHands run with the absolute minimal and no config changes. Any additional options and configurations should be in a different doc that gets linked from the basic "Getting started" guide. The idea here is that to get it run with the default options should be easy and streamlined and that's how most people will initially run it.
• Other than the official README at the base of the project, the others ones aren't kept up to date as code changes. Not yet at least. Things are moving too fast right now.

[autonomousit]

Thanks for the extra context @mamoodi . I agree regarding sticking to the absolute minimum for Installation and Getting Started but I do think there are some customisations that need to be added here to prevent users getting stuck.

• Local Port - I have 3-4 Apps that use port 3000 in their Docker images, although a Docker setting, not an OpenHands setting, changing this should be explained to users.
• Local Storage - I am having mixed results with this but setting up local storage seems to be needed under some circumstances. If I'm wrong let me know know but this setting should be included and/or explained.
• JWT Secret - this should also be set and explained to avoid incompatible tokens across sessions/deployments when deploying and re-deploying

I've attached a draft for the Installation section (had to convert from .mdx to .md to share here). I have tried to assume very little knowledge from the User for this document and focus on the case where someone is just trying to use OpenHands, not develop it. I only focus on a Docker deployment and Web UI access mode. Other access modes and the developer workflow can be addressed in the dedicated sections.

installation.md

I also wanted to ask about the prerequisites- it says Windows users need to use WSL. If deploying via Docker that shouldn't be needed, this should only impact deploying locally from source, correct?

Let me know what you think about the approach and my general style, etc. Feedback on improvements or changes would be very helpful so I get a feeling for how you want this to look and feel. Just an FYI, if I follow these instructions I get the app deployed however it always times out when waiting for the client to start, on both 0.16 and 0.17 so there's still something unstable about this I need to work out.

It would also be helpful if you could setup a branch for this. I can then do PRs to that branch for you to review progress and give feedback instead of manually passing files here. I think this will be bigger than a simple chamge and PR and will require multiple rounds of feedback until I get it the way you want.

[enyst]

You are welcome to open a PR, @autonomousit , you don't need us with a different branch for that, a PR to main is most welcome! You can mark as draft in github UI as long as it's in progress, if you want. Am I missing something?

[autonomousit]

Thanks @enyst just wasn't sure about your preferences regarding PRs to main