Redefine Cozystack tutorial flow #262
Conversation
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughThis update restructures and expands the Cozystack documentation, introducing a step-by-step tutorial flow with new and revised pages. It adds requirements and cluster deployment guides, condenses installation instructions, updates internal links, and revises metadata and content for clarity and navigation across the getting-started and Talos-related docs. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Docs
participant Cluster (Talos/K8s)
participant Cozystack
User->>Docs: Start at "Tutorial" overview
User->>Docs: Review "Requirements and Toolchain"
User->>Docs: Follow "Deploy Talos Linux and bootstrap Kubernetes cluster"
User->>Cluster (Talos/K8s): Install Talos, bootstrap K8s
User->>Docs: Proceed to "Install Cozystack"
User->>Cluster (Talos/K8s): Apply Cozystack configuration
Cluster (Talos/K8s)->>Cozystack: Deploy Cozystack components
User->>Docs: Continue with "Create Tenant" and "Deploy Managed Applications"
Estimated code review effort3 (~45 minutes) Possibly related PRs
Suggested labels
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Summary of Changes
Hello @NickVolynkin, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request significantly redefines the Cozystack documentation, primarily by overhauling the 'Getting Started' experience into a structured, step-by-step tutorial. It also involves a major reorganization of Talos Linux-related guides into a dedicated top-level section and general refinement of other documentation areas, all aimed at improving clarity and ease of navigation for users deploying and operating Cozystack.
Highlights
- Tutorial Flow Redefinition: The primary 'Getting Started' documentation has been completely restructured into a comprehensive, multi-step tutorial titled 'Cozystack Tutorial: Deploying Private Cloud from Scratch'. This new flow guides users from preparing infrastructure (Step 0) through deploying Talos Linux and Kubernetes (Step 1), installing Cozystack (Step 2), creating user tenants (Step 3), and finally deploying managed applications (Step 4).
- Talos Linux Documentation Reorganization: All documentation related to Talos Linux installation and cluster bootstrapping has been moved from the 'Operations' section to a new top-level 'Talos Linux' section (
/docs/talos/). This includes dedicated sub-sections for 'Installing Talos' and 'Cluster Bootstrap', making these crucial setup guides more discoverable and logically grouped. - Documentation Structure Refinement: Several other documentation sections have been reorganized for better clarity and navigation. The 'Cozystack API' documentation has been moved out of the 'development' sub-section, and the main 'Development' guide has been renamed and reordered. 'Hardware Requirements' has been moved to the 'Reference' section, and the weights of 'Operations Guides' and 'Reference Documentation' have been adjusted to reflect their new positions in the navigation hierarchy.
- Extensive Internal Link Updates: Numerous internal links across various documentation files, including blog posts, guides, and FAQs, have been updated to reflect the new file paths and content organization, ensuring a consistent and navigable user experience throughout the Cozystack documentation.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Code Review
This pull request refactors the Cozystack documentation, focusing on redefining the tutorial flow. The changes are extensive and improve the user experience. I've identified several critical issues related to broken links and a typo that should be addressed.
content/en/blog/2024-04-05-diy-create-your-own-cloud-with-kubernetes-part-1/index.md
Outdated
Show resolved
Hide resolved
| @@ -152,8 +153,7 @@ reboot | |||
|
|
|||
| Now, when it is booted to Talos Linux maintenance mode, you can use [talos-bootstrap](https://github.com/cozystack/talos-bootstrap) or [Talm](https://github.com/cozystack/talm) to bootstrap the cluster | |||
|
|
|||
|
|
|||
| Just follow **Get Started** guide starting from the [**Bootstrap cluster**](/docs/getting-started/first-deployment/#bootstrap-cluster) section, to continue the installation. | |||
| Just follow the **Cozystack Tutorial** starting from the [**Bootstrap cluster**](/docs/getting-started/deploy-cluster/#bootstrap-cluster) section, to continue the installation. | |||
There was a problem hiding this comment.
This link points to a broken anchor #bootstrap-cluster. The correct anchor for the "Bootstrap Talos Cluster" section in deploy-cluster.md is #12-bootstrap-talos-cluster.
| Just follow the **Cozystack Tutorial** starting from the [**Bootstrap cluster**](/docs/getting-started/deploy-cluster/#bootstrap-cluster) section, to continue the installation. | |
| Just follow the **Cozystack Tutorial** starting from the [**Bootstrap cluster**]({{% ref "/docs/getting-started/deploy-cluster#12-bootstrap-talos-cluster" %}}) section, to continue the installation. |
| @@ -17,4 +18,4 @@ Click **<F3>** and fill your network settings: | |||
|
|
|||
| Now you can use [talos-bootstrap](https://github.com/cozystack/talos-bootstrap) or [Talm](https://github.com/cozystack/talm) for connecting to the node and bootstrap the cluster | |||
|
|
|||
| Just follow **Get Started** guide starting from the [**Bootstrap cluster**](/docs/getting-started/first-deployment/#bootstrap-cluster) section, to continue the installation. | |||
| Just follow **Get Started** guide starting from the [**Bootstrap cluster**](/docs/getting-started/deploy-cluster/#bootstrap-cluster) section, to continue the installation. | |||
There was a problem hiding this comment.
This link points to a broken anchor #bootstrap-cluster. The correct anchor for the "Bootstrap Talos Cluster" section in deploy-cluster.md is #12-bootstrap-talos-cluster.
| Just follow **Get Started** guide starting from the [**Bootstrap cluster**](/docs/getting-started/deploy-cluster/#bootstrap-cluster) section, to continue the installation. | |
| Just follow **Get Started** guide starting from the [**Bootstrap cluster**]({{% ref "/docs/getting-started/deploy-cluster#12-bootstrap-talos-cluster" %}}) section, to continue the installation. |
| --- | ||
|
|
||
| ## Introduction | ||
|
|
||
| This guide explains how to install Talos on Oracle Cloud Infrastructure and deploy a Kubernetes cluster that is ready for Cozystack. | ||
| After completing the guide, you will be ready to proceed with | ||
| [installing Cozystack itself]({{% ref "/docs/getting-started/first-deployment#install-cozystack" %}}). | ||
| [installing Cozystack itself]({{% ref "/docs/getting-started/install-cozystack#install-cozystack" %}}). |
There was a problem hiding this comment.
This link contains a broken anchor #install-cozystack. The correct anchor for the "Install Cozystack" section in the target file is #2-install-cozystack.
| [installing Cozystack itself]({{% ref "/docs/getting-started/install-cozystack#install-cozystack" %}}). | |
| After completing the guide, you will be ready to proceed with | |
| [installing Cozystack itself]({{% ref "/docs/getting-started/install-cozystack#2-install-cozystack" %}}). |
| @@ -378,4 +380,4 @@ The next stage is to initialize Talos nodes and bootstrap a Kubernetes cluster. | |||
|
|
|||
| Now you have a Kubernetes cluster prepared for installing Cozystack. | |||
| To complete the installation, follow the deployment guide, starting with the | |||
| [Install Cozystack]({{% ref "/docs/getting-started/first-deployment#install-cozystack" %}}) section. | |||
| [Install Cozystack]({{% ref "/docs/getting-started/install-cozystack#install-cozystack" %}}) section. | |||
There was a problem hiding this comment.
This link contains a broken anchor #install-cozystack. The correct anchor for the "Install Cozystack" section in the target file is #2-install-cozystack.
| [Install Cozystack]({{% ref "/docs/getting-started/install-cozystack#install-cozystack" %}}) section. | |
| To complete the installation, follow the deployment guide, starting with the | |
| [Install Cozystack]({{% ref "/docs/getting-started/install-cozystack#2-install-cozystack" %}}) section. |
| @@ -77,4 +78,4 @@ Start your servers, now they should automatically boot from your PXE server. | |||
| Now, when they are booted to Talos Linux maintenance mode, you can use [talos-bootstrap](https://github.com/cozystack/talos-bootstrap) or [Talm](https://github.com/cozystack/talm) to bootstrap the cluster | |||
|
|
|||
|
|
|||
| Just follow **Getting Started** guide starting from the [**Bootstrap cluster**](/docs/getting-started/first-deployment/#bootstrap-cluster) section, to continue the installation. | |||
| Just follow **Getting Started** guide starting from the [**Bootstrap cluster**](/docs/getting-started/deploy-cluster/#bootstrap-cluster) section, to continue the installation. | |||
There was a problem hiding this comment.
This link points to a broken anchor #bootstrap-cluster. The correct anchor for the "Bootstrap Talos Cluster" section in deploy-cluster.md is #12-bootstrap-talos-cluster.
| Just follow **Getting Started** guide starting from the [**Bootstrap cluster**](/docs/getting-started/deploy-cluster/#bootstrap-cluster) section, to continue the installation. | |
| Just follow **Getting Started** guide starting from the [**Bootstrap cluster**]({{% ref "/docs/getting-started/deploy-cluster#12-bootstrap-talos-cluster" %}}) section, to continue the installation. |
| You will need a running Cozystack installation. | ||
| Follow the [installation guide]({{% ref "/docs/getting-started/first-deployment" %}}) to deploy it. | ||
| Complete the previous steps of the tutorial to get a [Cozystack cluster]({{% ref "/docs/getting-started/" %}}) running, | ||
| with storage, networking, and management dashbord configured. |
There was a problem hiding this comment.
There's a typo in "dashbord". It should be "dashboard".
| with storage, networking, and management dashbord configured. | |
| with storage, networking, and management dashboard configured. |
28159e4 to
ad5a298
Compare
Signed-off-by: Nick Volynkin <nick.volynkin@gmail.com>
There are two separate steps with a different toolset: 1. Installing Talos Linux, then bootstrapping it to install Kubernetes 2. Installing Cozystack on top, configuring it This commit is the first step to split them, preserving git history along the way Signed-off-by: Nick Volynkin <nick.volynkin@gmail.com>
8ff2c7c to
5bbbd00
Compare
Remove the duplicate content and fix numbering in the tutorial steps Signed-off-by: Nick Volynkin <nick.volynkin@gmail.com>
It's also easier to link to them on a single page. And the image fits well. And the tutorial intro is just one page with a description of steps. Nice. Signed-off-by: Nick Volynkin <nick.volynkin@gmail.com>
…ptions Signed-off-by: Nick Volynkin <nick.volynkin@gmail.com>
- allow bare metal - explain extra requirements - provide link to full requirements - instead of a management host, just require a workstation with CLIs Signed-off-by: Nick Volynkin <nick.volynkin@gmail.com>
5bbbd00 to
b2baa40
Compare
Signed-off-by: Nick Volynkin <nick.volynkin@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
content/en/docs/getting-started/requirements.md (2)
12-14: Unify compound-adjective & wording style in bullet listSmall consistency tweaks will prevent style lint from flagging the doc:
-**Cluster nodes:** three bare metal servers or virtual machines in the following minimal configuration: +**Cluster nodes:** three **bare-metal** servers or virtual machines with the following minimal configuration: @@ - - Located in the same L2 network segment.<br> - Cozystack can be deployed with a variety of networking options, but for this tutorial it's best to use a simple configuration. + - Located in the same L2 network segment.<br> + Cozystack can be deployed with various networking options, but for this tutorial it's best to keep the layout simple.Also applies to: 20-24
16-18: Fix spacing around capacities for visual parity (“16 GiB” vs “32GiB/100GiB”)- - HDD1: 32GiB<br>Primary disk, used for Talos Linux, etcd storage, and downloaded images. - - HDD2: 100GiB<br>Secondary disk, used for user application data. + - HDD1: 32 GiB<br>Primary disk, used for Talos Linux, etcd storage, and downloaded images. + - HDD2: 100 GiB<br>Secondary disk, used for user application data.content/en/docs/getting-started/install-cozystack.md (1)
12-19: Number the high-level stages explicitly (1-6) for easier referencingUsing repeated
1.Markdown auto-numbering is fine when rendered, but the raw file is often copied into issues or chat and the duplicate1.items become confusing. Suggest switching to explicit numbering:-1. Prepare a Cozystack configuration file -1. Install Cozystack by applying configuration -1. Configure storage -1. Configure networking -1. Deploy etcd, ingress and monitoring stack in the root tenant -1. Finalize deployment and access Cozystack dashboard +1. Prepare a Cozystack configuration file +2. Install Cozystack by applying the configuration +3. Configure storage +4. Configure networking +5. Deploy etcd, ingress, and the monitoring stack in the root tenant +6. Finalize deployment and access the Cozystack dashboardcontent/en/docs/getting-started/deploy-cluster.md (1)
31-34: Avoid repetitive sentence starts in the install-methods list-- [Install using temporary DHCP and PXE servers](/docs/talos/install/pxe/) running in Docker containers. -- [Install using ISO](/docs/talos/install/iso/). -- [Install on Hetzner servers](/docs/talos/install/hetzner/). +- **PXE/DHCP:** [Install via temporary DHCP & PXE servers](/docs/talos/install/pxe/) running in Docker containers. +- **ISO:** [Install from an ISO image](/docs/talos/install/iso/). +- **Hetzner:** [Install on Hetzner dedicated servers](/docs/talos/install/hetzner/).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
content/en/docs/getting-started/_index.md(1 hunks)content/en/docs/getting-started/create-tenant.md(2 hunks)content/en/docs/getting-started/deploy-app.md(2 hunks)content/en/docs/getting-started/deploy-cluster.md(1 hunks)content/en/docs/getting-started/install-cozystack.md(2 hunks)content/en/docs/getting-started/requirements.md(1 hunks)content/en/docs/talos/install/hetzner.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (4)
- content/en/docs/getting-started/create-tenant.md
- content/en/docs/talos/install/hetzner.md
- content/en/docs/getting-started/_index.md
- content/en/docs/getting-started/deploy-app.md
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: nbykov0
PR: cozystack/website#165
File: content/en/docs/getting-started/first-deployment.md:475-476
Timestamp: 2025-04-21T19:21:40.546Z
Learning: In the Cozystack documentation, bold text like "**OIDC**" before a final note is used as a label/callout rather than a formal section heading, which typically use markdown heading syntax (## or ###).
Learnt from: NickVolynkin
PR: cozystack/website#242
File: content/en/docs/operations/faq.md:0-0
Timestamp: 2025-07-08T12:26:13.298Z
Learning: In the Cozystack documentation, 4-character indents are used for markdown lists (e.g., `- list item`) to maintain consistent indentation between numbered and ordered lists, especially when they're nested with paragraphs and sub-lists.
content/en/docs/getting-started/install-cozystack.md (2)
Learnt from: nbykov0
PR: #165
File: content/en/docs/getting-started/first-deployment.md:475-476
Timestamp: 2025-04-21T19:21:40.546Z
Learning: In the Cozystack documentation, bold text like "OIDC" before a final note is used as a label/callout rather than a formal section heading, which typically use markdown heading syntax (## or ###).
Learnt from: NickVolynkin
PR: #242
File: content/en/docs/operations/faq.md:0-0
Timestamp: 2025-07-08T12:26:13.298Z
Learning: In the Cozystack documentation, 4-character indents are used for markdown lists (e.g., - list item) to maintain consistent indentation between numbered and ordered lists, especially when they're nested with paragraphs and sub-lists.
🪛 LanguageTool
content/en/docs/getting-started/deploy-cluster.md
[style] ~33-~33: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...sing ISO](/docs/talos/install/iso/). - [Install on Hetzner servers](/docs/talos/install...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
content/en/docs/getting-started/requirements.md
[uncategorized] ~12-~12: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...lowing setup: Cluster nodes: three bare metal servers or virtual machines in the foll...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[style] ~22-~22: Consider using a more concise synonym.
Context: ... Cozystack can be deployed with a variety of networking options, but for this tutori...
(A_VARIETY_OF)
| This tutorial assumes that you deploy a Cozystack cluster on virtual machines, | ||
| which is the most universal and simple way. | ||
| Make sure you have VMs and a management host that match the [requirements]({{% ref "/docs/getting-started/requirements" %}}). | ||
|
|
There was a problem hiding this comment.
Contradictory guidance: VMs vs. bare-metal – pick one
Lines 13-16 say the tutorial “assumes … virtual machines”, while lines 70-73 “strongly recommend … bare metal”.
This is likely to confuse newcomers and complicate hardware planning.
Please align the recommendation in one direction (e.g. “virtual machines for the tutorial, bare-metal for production”) or split the advice clearly.
Also applies to: 70-73
🤖 Prompt for AI Agents
In content/en/docs/getting-started/deploy-cluster.md around lines 13 to 16 and
70 to 73, the document gives conflicting recommendations by stating the tutorial
assumes virtual machines but later strongly recommends bare-metal. To fix this,
clarify the guidance by explicitly stating that the tutorial uses virtual
machines for simplicity and learning purposes, while bare-metal deployment is
recommended for production environments. Adjust the text in both sections to
clearly separate these use cases and avoid confusion for readers.
Summary by CodeRabbit
New Features
Documentation