[GH-ISSUE #20667] feat: Add beginner-friendly first-time setup guide #138983

New Issue

GiteaMirror · 2026-05-25T12:01:45-05:00

GiteaMirror commented

2026-05-25 12:01:45 -05:00

Originally created by @MargusG on GitHub (Jan 14, 2026).
Original GitHub issue: https://github.com/open-webui/open-webui/issues/20667

Check Existing Issues

I have searched for all existing open AND closed issues and discussions for similar requests. I have found none that is comparable to my request.

Verify Feature Scope

I have read through and understood the scope definition for feature requests in the Issues section. I believe my feature request meets the definition and belongs in the Issues section instead of the Discussions.

Problem Description

New users often struggle to reach “first success” (a working chat or document-based chat) during initial setup.

Common friction points observed:

Users are unsure what “working” looks like
Model selection is required before chat works, but no default path is obvious
Document ingestion can be silent or slow on first run
Users must make several correct choices before seeing any result

In addition, users who try to extend Open WebUI (for example, by building pages or routes) often get stuck because:

file and folder names (e.g. page, route) are unfamiliar
failures do not clearly indicate where in the project structure the issue is
there is no clear reference structure showing what files belong together

This makes it hard for new users to orient themselves when something fails.

Desired Solution you'd like

Starter Templates

Add a small set of built-in starter templates that users can choose from on first use (or from a “New Session” action).

Proposed minimal set:

Chat only (no documents)
- Preconfigured to confirm basic chat works
- Intended as the fastest “it responds” success
Chat with documents (local folder)
- Guides the user to upload a folder
- Emphasizes waiting for indexing to complete
- Includes a simple verification prompt
Advanced (manual configuration)
- For experienced users
- Keeps current flexibility unchanged

Templates would not limit functionality — only provide a starting point.

Reference Folder Structure (Beginner Aid)

For users who want to build or extend functionality (e.g. pages or routes), provide:

a simple reference folder tree
minimal explanation of what each folder is responsible for
no requirement to follow it strictly

Example (illustrative only):
/project-root
/pages # user-facing pages
/routes # backend or API routes
/components # reusable UI components
/config # configuration files

Alternatives Considered

No alternatives proposed yet.
The goal is to gather feedback on whether starter templates and lightweight structural guidance would be useful before exploring other approaches.

Additional Context

Why This Helps

Reduces cognitive overload during first use
Makes failures easier to diagnose
Helps users mentally map the system
Lowers frustration when experimenting or extending features
Reduces repeated “where do I put this?” questions

Scope

UX / onboarding only
No change to underlying behavior
No removal of advanced options
Templates and folder references are optional

Success Criteria (examples)

New users can reach a successful chat in <5 minutes
New users can verify document-based chat with a simple test
New users can identify where to look when something breaks
Reduced onboarding and “nothing works” questions

Originally created by @MargusG on GitHub (Jan 14, 2026). Original GitHub issue: https://github.com/open-webui/open-webui/issues/20667 ### Check Existing Issues - [x] I have searched for all existing **open AND closed** issues and discussions for similar requests. I have found none that is comparable to my request. ### Verify Feature Scope - [x] I have read through and understood the scope definition for feature requests in the Issues section. I believe my feature request meets the definition and belongs in the Issues section instead of the Discussions. ### Problem Description New users often struggle to reach “first success” (a working chat or document-based chat) during initial setup. Common friction points observed: - Users are unsure what “working” looks like - Model selection is required before chat works, but no default path is obvious - Document ingestion can be silent or slow on first run - Users must make several correct choices before seeing any result In addition, users who try to extend Open WebUI (for example, by building pages or routes) often get stuck because: - file and folder names (e.g. `page`, `route`) are unfamiliar - failures do not clearly indicate *where* in the project structure the issue is - there is no clear reference structure showing what files belong together This makes it hard for new users to orient themselves when something fails. ### Desired Solution you'd like ### Starter Templates Add a small set of built-in starter templates that users can choose from on first use (or from a “New Session” action). Proposed minimal set: 1. **Chat only (no documents)** - Preconfigured to confirm basic chat works - Intended as the fastest “it responds” success 2. **Chat with documents (local folder)** - Guides the user to upload a folder - Emphasizes waiting for indexing to complete - Includes a simple verification prompt 3. **Advanced (manual configuration)** - For experienced users - Keeps current flexibility unchanged Templates would not limit functionality — only provide a starting point. --- ### Reference Folder Structure (Beginner Aid) For users who want to build or extend functionality (e.g. pages or routes), provide: - a simple reference folder tree - minimal explanation of what each folder is responsible for - no requirement to follow it strictly Example (illustrative only): /project-root /pages # user-facing pages /routes # backend or API routes /components # reusable UI components /config # configuration files ### Alternatives Considered No alternatives proposed yet. The goal is to gather feedback on whether starter templates and lightweight structural guidance would be useful before exploring other approaches. ### Additional Context ### Why This Helps - Reduces cognitive overload during first use - Makes failures easier to diagnose - Helps users mentally map the system - Lowers frustration when experimenting or extending features - Reduces repeated “where do I put this?” questions ### Scope - UX / onboarding only - No change to underlying behavior - No removal of advanced options - Templates and folder references are optional ### Success Criteria (examples) - New users can reach a successful chat in <5 minutes - New users can verify document-based chat with a simple test - New users can identify where to look when something breaks - Reduced onboarding and “nothing works” questions

GiteaMirror closed this issue

2026-05-25 12:01:45 -05:00

GiteaMirror commented

2026-05-25 12:01:47 -05:00

@Classic298 commented on GitHub (Jan 14, 2026):

Don't open docs issues in the main repository

@Classic298 commented on GitHub (Jan 14, 2026): Don't open docs issues in the main repository

GiteaMirror commented

2026-05-25 12:01:47 -05:00

@MargusG commented on GitHub (Jan 14, 2026):

Thanks for the clarification

I’ll follow up in the docs repository and continue the discussion there, since this is primarily about onboarding and documentation-driven first success.

Appreciate the guidance.

@MargusG commented on GitHub (Jan 14, 2026): Thanks for the clarification I’ll follow up in the docs repository and continue the discussion there, since this is primarily about onboarding and documentation-driven first success. Appreciate the guidance.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/open-webui#138983