Docs: add a concepts-first getting started path for Core / Periphery / resources / setup flow

[joshka]

AI Disclosure

This issue draft was generated with the help of Codex and then edited by me.

I want to acknowledge the obvious concern up front: AI slop in docs/issues is a real problem.

That is not what I am trying to do here.

This is coming from a real new-user learning process. I am actively trying to get Komodo working for my own homelab setup, and I used a coding agent to help me read the source, docs, issues, and discussions while I get up to speed. Since that effort is already happening, it seemed worth turning the results into actionable docs feedback rather than keeping it private.

My intent is to validate any proposed docs changes as I actually work through setup and understanding, and to contribute improvements incrementally as I go.

Context / Motivation

I’m a new Komodo user.

A bit of background on me:

• Maintainer of ratatui. I've written a bunch of the docs for the crate and website ratatui.rs
• Current goal with Komodo: set up a dev / test / prod workflow for my homelab across my laptop and NAS

I want to get to using Komodo, but I need some of this information now in order to understand how I should set it up and operate it. I do not really want to wait until I have “fully learned Komodo” before trying to improve the onboarding path, because by then I will have lost the most valuable perspective: where a new user actually gets stuck.

I should also note one limitation of my current perspective: I have not yet checked Discord, so there may be additional community context there that I am missing.

Summary

The current docs are strong on feature coverage and reference material, but the first-time reader flow still feels too implementation-first.

Today, a new user can hit install choices like MongoDB vs FerretDB, Docker vs systemd Periphery, repo/provider settings, onboarding keys, or Actions docs before they have a solid mental model for:

• what Komodo actually is operationally
• what Core and Periphery each do
• what runs where
• which resources matter first
• which setup path they should choose
• what “good first success” looks like

I think the docs would benefit from a concepts-first onboarding path before the existing setup/reference material.

Why this feels missing

The pattern I keep running into is not “there is no documentation at all”.

It is more:

• the reference docs exist
• the feature docs exist
• but the learning order is not yet optimized for a new user trying to build a correct mental model

The external/tutorial-style material I found helpful tends to do one thing the official docs currently do less of: it starts from a concrete scenario and explains the system model before diving into configuration.

Examples:

• Skyblog’s setup/comparison guide
  • Frames Komodo through a familiar Portainer comparison and then walks into setup and Periphery.
• Christian Hollinger’s homelab writeup
  • Explains Komodo through an actual homelab workflow with dev and prod variants, and makes the resource model feel more concrete.
• Komodo Import quickstart
  • Assumes Komodo, Periphery, and a Server already exist, which highlights how important those concepts are to establish early.

Current docs pages that likely need rethinking

• What is Komodo?
  • Good feature overview, but the architecture section is too short to carry the onboarding burden.
• Setup
  • Moves quickly into MongoDB / FerretDB choice before grounding the reader in how Komodo works.
• Connect More Servers
  • This contains the first real Periphery explanation, but it comes too late in the reader journey.
• Resources
  • Useful reference, but first-time users need a “resources you need first” explanation before the full catalog.
• Community
  • Helpful link hub, but there may be room to link more tutorial-level material.

Evidence from issues and discussions

Issues

• #1360 - Where the heck do I make an onboarding key?
  • Very direct evidence that a core first-run concept/action is hard to discover in both docs and UI.
• #723 - Docs on REPO settings
  • New users do not understand GitHub accounts, repo-related settings, and the difference between repo-related concepts. This points to a missing mental model, not just missing field descriptions.
• #233 - Git File Structure
  • Closed, but useful evidence that users struggle to understand stacks vs repos vs filesystem layout and how to structure a Git-backed workflow.
• #938 - Signup process
  • Even when the issue is partly behavioral, the report explicitly calls out setup docs as not very helpful.
• #1297 - Local Komodo connection to local Periphery fails
  • Explicitly says the v2 Core / Periphery setup and missing documentation are not obvious.
• #1062 - Question: Periphery - EDGE (call home) funtion
  • Shows users are not clear on Periphery connection modes / networking model from the docs.
• #1079 - How to get Komodo CLI working? There isn't any documentation.
  • Another discoverability problem: docs may exist in some form, but users do not know where to begin.
• #193 - No documentation on alerters, sending notifications
  • Narrower scope, but still supports the broader theme that reference information is not always easy to find or contextualize.

Discussions

• #220 - To Systemd or not to Systemd
  • Extremely useful maintainer explanation of why Periphery-in-container creates filesystem/path/mount confusion. This feels like material that belongs in first-run docs, not only in a discussion reply.
• #261 - How Do I configure Git using a docker compose deploy?
  • User explicitly says they did not understand from the docs how GitHub accounts/tokens are configured.
• #1322 - Where do I find information on how to build actions?
  • Shows that action/API docs are not sufficiently discoverable from the main docs flow.
• #1319 - Key Exchange, Onboarding, Periphery Public Endpoint exposure
  • Good example of users needing to reason about onboarding and Periphery security model beyond what current docs make obvious.
• #180 - Are relative paths for mounting functioning?
  • Recurrent confusion around host/container filesystem expectations, which is tightly related to the Periphery deployment model and “where things actually run”.

Proposal

Add an explicit concepts-first onboarding section before the current setup reference pages.

Suggested docs changes:

1. Add a new "Mental Model" page near the top of the docs

Explain clearly:

• Core = control plane / UI / API
• Periphery = per-server agent / execution + telemetry boundary
• database = Core state storage
• Docker / Podman = underlying runtime Komodo manages
• providers = credentials/accounts used by resources
• resources = Komodo’s abstraction layer

Also include:

• one simple architecture diagram
• one "single-host" example
• one "multi-host" example
• one "Git-backed stacks" example

2. Add a "Choose Your Setup Path" page

Instead of dropping users straight into MongoDB / FerretDB pages, give them an opinionated decision page:

• Single host vs multi-host
• Periphery in systemd vs container
• MongoDB vs FerretDB
• Stack vs Deployment
• Git-backed vs UI/host-managed workflow

3. Add a "First 15 Minutes" / "First Deployment" walkthrough

A concrete, opinionated path such as:

1. Run Core
2. Create first user
3. Create onboarding key
4. Install Periphery on one server
5. Confirm Server is healthy
6. Create one Stack or Deployment
7. View logs / redeploy / update once

This would give users a first successful mental and operational loop.

4. Rework "Resources" into two layers

At the top of the page, explain only the first resources most users need:

• Server
• Stack
• Deployment
• Build
• Repo / Resource Sync only after the basics

Then keep the full catalog below for reference.

5. Pull key maintainer explanations from discussions into docs

In particular:

• why systemd Periphery is often simpler than containerized Periphery
• why containerized Periphery causes path/mount confusion
• how Git/provider configuration is expected to work
• where action/API docs live and how users discover them

6. Consider linking more tutorial-level external resources

One candidate that seems worth considering for the Community page:

• How I run and deploy docker services in my homelab with Komodo and a custom CLI
  • Practical homelab-oriented writeup
  • Explicitly discusses dev / prod variants
  • Helps make the resource model more concrete

Suggested non-goals

This is not primarily asking for:

• more exhaustive field-by-field reference docs
• more release notes
• replacing docs.rs or API reference
• removing existing setup/reference pages

The main ask is to improve the learning order and conceptual grounding.

Questions for feedback

• Does this problem statement match what maintainers/community have been seeing?
• Would a concepts-first page and a first-success walkthrough be useful?
• Should systemd be more strongly positioned as the recommended Periphery path for most users?
• What should the "default recommended setup" be for a new user in 2026?
• Are there existing docs/discussion answers or community tutorials that should be promoted into the main docs?
• Is Discord/community context likely to significantly change the proposed direction here?

Offer to help

I am likely going to work on this regardless, because I need these docs to get myself productively using Komodo.

I would be happy to turn this into multiple incremental PRs, validating the proposed path as I actually work through my own setup rather than trying to do one giant rewrite.

Possible follow-up PRs:

1. Mental Model
2. Choose Your Setup Path
3. First Deployment
4. Resources You Need First
5. Community page update with additional tutorial-level links

[thiagoalcav]

I think that would be a very good reorganization suggestion! +1

I would only add a specific topic for upgrading Periphery when installed via systemd (given that in Docker it's a simple image update).

I managed to do it after testing several times and understanding that it was no longer necessary to pass parameters like onboarding-key in the setup script after the first installation, sending it was enough to update the executable.

After that, review the service status and whether it was enabled for automatic startup... anyway, testing and self-deduction, when it would be great if it were clearly documented. ...of course, excuse me if it isn't, I didn't find it easily.

[soorano]

I also think this is a good idea. +1
To get into this certificate stuff between periphery and core gets a lot harder now.
In v1 there was just a secret to share between periphery and core, but now ....
I just don't get this thing connected with selfsigned certificates and own CA.

A step by step documentation of connecting new servers (with and without cert) would be nice.

[joshka]

There's a not yet split apart, not yet fully validated draft PR up over at #1368 for this.

Would happily add any of the info you want there.

I'll be doing the validation steps a bit more over the coming week or so, but the docs materially helped my understand Komodo much better than the existing docs do.