[Docs]:Enhanced Installation & Getting Started Docs

[autonomousit]

End-user friendly description of the problem this fixes or functionality that this introduces
This PR provides a more detailed installation and getting started workflow designed to be user friendly for a range of user skill levels and to prevent/deflect requests for setup help for the maintainers. The intended result is a reduction in variability in the deployment state and configuration across users of the OpenHands app (development workflow will be addressed separately).

It's expected that this will require some rounds of feedback so is set to Draft. There are also further changes required to other docs that are part of this effort but I wanted feedback on the general approach ASAP before making too many changes.

• Include this change in the Release Notes. If checked, you must provide an end-user friendly description for your change below

---

Give a summary of what the PR does, explaining any non-trivial design decisions

• installation.mdx - most of the changes are to this page of the docs. The changes here are designed to move the user from zero to getting started as quickly and reliably as possible. There's a huge correlation between time-to-value and product adoption so this stage is critical for growing any project or product.
  • Most steps have been made more verbose to include potential background context that the reader doesn't posses
  • Pre-requisites have links to 3rd party docs
  • It focuses exclusively on deployment by Docker and using the Web UI
  • The installation is now explicitly via a bash script
  • 2 commonly required configuration options are included by default
    • Mounting a local folder as a Docker volume for OpenHands Session State data - this appears to be a common setting that is required for stability.
    • Setting a JWT Secret - this appears to be a setting required for stability,
  • Common Docker errors are addressed inline to prevent the reader having to break out to another troubleshooting page.
  • Readers are encouraged to the Discord #setup-help channel if they fail to complete these steps
• getting-started.mdx - minor heading change
• common-use-cases.mdx - this is a new page designed to highlight common use cases and requirements and then direct users to the correct advanced documentation sections. This is designed to be more or a routing page that doesn't have any unique content but helps new users find and navigate the technical sections of the documentation at a time when they may not know the OpenHands specific terminology or may need to combine features to complete a use case. At this stage it is pretty sparse but as the feature set and documentation grows I think this will become a very useful page. It is also a good place to catch common but more difficult configuration needs that would distract or complicate users during the installation phase. It also acts as a way to advertise the more advanced capabilities of the app early on.
• troubleshooting.mdx - added additional Docker errors for consistency in case users end up here at a later time.
• sidebars.ts - added the new Common Use Cases page to the ToC nav tree

---

Feedback & Open Questions

• General feedback on approach and style would be very helpful. You can be direct and if you don't like something just say so, you don't need to worry about "hurt feelings" :-) I tend to be direct as well so things are clear, it is not meant to be disrespectful.
• If I'm trying to change or debate something that is non-negotiable to you as the maintainers please just say so and I'll accept it immediately.
• In the Installation section there are two TODO markers with questions regarding how to treat some content there. Specifically the case of Custom LLMs during Installation (I think we should skip it and address in the new Common Use Cases page) and another regarding cleanly exiting the Docker deployment when using a bash script. Feedback would be helpful.
• I can't get the start_openhands.sh method working right now, the frontend times out waiting for the backed client. This shouldn't be merged until Ican resolve that.

---

Link of any specific issues this addresses
#5878

[mamoodi]

Thanks so much for putting this together! There's definitely some great additional info on here.
The installation guide is changing quite a bit and becoming more configurable in this PR and I'm not sure it's exactly what we want (We want to keep this section super simple and basic). Though that's completely my opinion. Documentation is very personal.

Going to bring this up with folks and see what they say.

[autonomousit]

Hey @mamoodi thanks for the update and context. I agree things are subjective which is why I wanted early feedback before committing too many changes :-) I'd just like to add a few talking points for your discussion with the team. I've run support and sales engineering for a lot of vendors and spent a lot of time working on documentation and knowledge base design and I think the current focus on "simple" misses some important issues. As with your comments these are opinionated and subjective but I think they're important to the discussion. My changes might not be right but I definitely think that some kind of changes are needed.

1. Simple for who? - you're project is growing and there are lots of posts and vlogs on agentic projects right now. Your users will change from early adopters with high development and technical skills in AI to many other backgrounds. It might be a 15 yr old who just watched "How I built my app in 5 days with know programming skills" to a dev with 10+ years experience in Windows/.NET and is working with a linux system for the first time.
2. What is the intended outcome? - The current docs leave you at "hello world" but don't set you up for something that is really working well for your project. You then need to find out about things like .openhands-intructions.md, custom sandboxes and other key items needed to get a stable and productive environment. This leaves a lot of room for error and makes it frustrating trying to go from the basic installation to something that does what you really need. For me the Installation and Getting Started should leave me in a production-ready deployment that covers 90% of the use cases I'm going to need. Perhaps Installation can stay simple but then you need to pack lots more details into the new Common Use Cases.
3. Support Load Grows Fast - the current docs allow a lot of variation on the part of the reader. When they don't work you guys have a lot of work to find out why and try to correct the users state. I had things working for ~1.5 days and now I can't get any Docker instance to work and I can only get 0.16.1 to work via Development mode. However simple the current docs are, they don't work. As you grow, even if the failure rate for setup is only ~5%, that support workload is going to grow faster than you can cope with and distract from adding features.
4. Commercial Testers Aren't Patient - I see you're also trying to commercialise, this brings other issues. I was originally testing OpenHands to introduce at work but on Day 2, when I tried to put together a demo for a real internal project (not just hello world) everything fell apart and despite a lot of energy from you guys to help me, I still don't have a working environment they way I want. Commercial testers have 2-3 days to test and demo 3-5 potential options. If they can't get things working in <60 mins and put together a reasonable demo and report on why they want to introduce it in under a day then they're going to walk away. The only reason I hung around is it's summer holidays here and I want to use OpenHands for a personal project. I also think with a little more time it could be really good but at this stage it's too unstable for me to introduce at work.

[mamoodi]

Great points! Thanks for writing all that out!

My understanding was that the installation steps should have you in a working state for Ubuntu, MacOS, Windows with WSL. Unfortunately I can't confirm that myself other than on MacOS and it may not be 100% working on Ubuntu or Windows.

Lots of good points here so I'll defer this to @rbren and the rest of the maintainers on how they want this documentation to look like.