OpenCHAMI · alexlovelltroy · Jun 5, 2026 · Jun 5, 2026
diff --git a/content/blog/booting-badger/part2-deploying.md b/content/blog/booting-badger/part2-deploying.md
@@ -57,7 +57,9 @@ This approach allowed us to take advantage of systemd's service management while
 
 At LANL, we leverage Ansible for a lot of our sysadmin tasks.  In order for our sysadmins to deploy OpenCHAMI without developer support, we needed to meet them where they were, not force them to learn a new technology.  We built on our work with quadlets and created a set of ansible roles using the [podman container module](https://docs.ansible.com/ansible/latest/collections/containers/podman/podman_container_module.html)that set up each of the microservices in the right order using a simple ansible command to create and start the unit files.
 
-> [Our Ansible Repository](https://github.com/OpenCHAMI/deployment-recipes/tree/trcotton/podman-quadlets/lanl/podman-quadlets)
+> [Our Ansible Repository (legacy LANL-specific)](https://github.com/OpenCHAMI/deployment-recipes/tree/trcotton/podman-quadlets/lanl/podman-quadlets)
+
+**Note**: This blog post describes a legacy LANL-specific deployment. For current instructions, see the [OpenCHAMI Tutorial](https://openchami.org/docs/tutorial/).
 
 Once created and started, the Units behave like any others on the system.  Our admins could troubleshoot them with tools they understand and even trace dependencies as they would any other system in the datacenter.
 

diff --git a/content/blog/inventory-service/index.md b/content/blog/inventory-service/index.md
@@ -278,7 +278,7 @@ docker stop inventory-service
 
 ### Run in the quickstart
 
-This shows how to run in the [quickstart guide](https://github.com/OpenCHAMI/deployment-recipes/tree/main/quickstart)
+This shows how to run in the [legacy quickstart guide](https://github.com/OpenCHAMI/deployment-recipes/tree/main/quickstart) (deprecated - see the [OpenCHAMI Tutorial](/docs/tutorial/) for current instructions).
 
 Replace the `SMD Init and Server Containers` with the following
 

diff --git a/content/blog/mini-bootcamp/index.md b/content/blog/mini-bootcamp/index.md
@@ -37,12 +37,15 @@ You want to see OpenCHAMI running today, not next month. This mini bootcamp is t
 
 ## Configure once, then run
 
-The deployment recipes use a small, readable inventory and a few group_vars files. You’ll set your hostname, cluster shortname, and one or two items like an SSH pubkey if you plan to use cloud‑init to inject keys later. Everything else is sane defaults for a local install.
+The deployment recipes use a small, readable inventory and a few group_vars files. You'll set your hostname, cluster shortname, and one or two items like an SSH pubkey if you plan to use cloud‑init to inject keys later. Everything else is sane defaults for a local install.
+
+**Note**: This blog post describes a legacy LANL-specific deployment. For current instructions, see the [OpenCHAMI Tutorial](https://openchami.org/docs/tutorial/).
 
 The only commands you need (≤4)
 We keep this tight. Clone the recipes, apply configs, then bring everything up.
 
 ```bash
+# Legacy LANL deployment (deprecated - see tutorial for current instructions)
 git clone https://github.com/OpenCHAMI/deployment-recipes.git && cd deployment-recipes/lanl/podman-quadlets
 ansible-playbook -l $HOSTNAME -c local -i inventory -t configs ochami_playbook.yaml
 ansible-playbook -l $HOSTNAME -c local -i inventory ochami_playbook.yaml
@@ -101,7 +104,8 @@ This isn’t image building or full cluster operations. It’s the shortest path
 
 ## References
 
-- Recipes: https://github.com/OpenCHAMI/deployment-recipes
+- Tutorial (recommended): https://openchami.org/docs/tutorial/
+- Recipes (legacy): https://github.com/OpenCHAMI/deployment-recipes
 - Org: https://github.com/OpenCHAMI
 - Docs: https://openchami.org/docs
 

diff --git a/content/blog/smd-jwtauth/index.md b/content/blog/smd-jwtauth/index.md
@@ -13,7 +13,7 @@ tags = ["SMD", "JWT", "Hydra", "OIDC"]
 
 Since we're pushing to use OpenCHAMI for Supercomputing Institute 2024, we needed to have both authentication and authorization implemented in our microservices to only allow students to access hardware assigned to them. Therefore, we found an off-the-shelf OAuth2 and OIDC implementation for handling this: [Ory Hydra](https://github.com/ory/hydra). We also had to make some *more* changes to SMD to inject middleware that made verifying the public key retrieved from the Hydra server trivial.
 
-For this post, I will be referring to [this commit of our deployment recipes](https://github.com/OpenCHAMI/deployment-recipes/commit/a243ddfcbf5e40f709daa37167c41e4fc851662a) and [this commit of our custom SMD](https://github.com/OpenCHAMI/smd/commit/802123c620559ac365b8855b8a5540b0aaf5e4b8).
+For this post, I will be referring to [this commit of our deployment recipes](https://github.com/OpenCHAMI/deployment-recipes/commit/a243ddfcbf5e40f709daa37167c41e4fc851662a) (legacy) and [this commit of our custom SMD](https://github.com/OpenCHAMI/smd/commit/802123c620559ac365b8855b8a5540b0aaf5e4b8). For current deployment instructions, see the [OpenCHAMI Tutorial](https://openchami.org/docs/tutorial/).
 
 ## Replacing the HTTP Router
 

diff --git a/content/blog/turnkey-ochami/index.md b/content/blog/turnkey-ochami/index.md
@@ -20,11 +20,14 @@ You will run a handful of services with docker-compose. You will have inventory,
 
 ## Key repos
 
-- Deployment recipes: https://github.com/OpenCHAMI/deployment-recipes
+- **Tutorial (recommended)**: https://openchami.org/docs/tutorial/
+- Deployment recipes (legacy): https://github.com/OpenCHAMI/deployment-recipes
 - SMD (inventory): https://github.com/OpenCHAMI/smd
 - BSS (boot scripts): https://github.com/OpenCHAMI/bss
 - Magellan (discovery): https://github.com/OpenCHAMI/magellan
 
+**Note**: This blog post describes a legacy Docker Compose deployment. For current instructions, see the [OpenCHAMI Tutorial](https://openchami.org/docs/tutorial/).
+
 ## Before you start
 
 Pick a small test area. One head node or VM host is enough. A couple of bare-metal nodes or VMs help you test power and boot. Make sure your user can run Docker.
@@ -77,7 +80,8 @@ This weekend deploy is not a full site. It is a small, safe start. It helps you
 
 ## References
 
-- Deployment recipes: https://github.com/OpenCHAMI/deployment-recipes
+- Tutorial (recommended): https://openchami.org/docs/tutorial/
+- Deployment recipes (legacy): https://github.com/OpenCHAMI/deployment-recipes
 - SMD: https://github.com/OpenCHAMI/smd
 - BSS: https://github.com/OpenCHAMI/bss
 - Magellan: https://github.com/OpenCHAMI/magellan

diff --git a/content/docs/guides/getting_started.md b/content/docs/guides/getting_started.md
@@ -14,9 +14,7 @@ seo:
   noindex: false # false (default) or true
 ---
 
-  In the guide below, we'll show you how to install and run the OpenCHAMI services with all the containers you need to generate an inventory of your compute nodes and boot them.
-
-  Things move quickly, so the official guide on GitHub may have updated information. See the [quickstart README on GitHub](https://github.com/OpenCHAMI/deployment-recipes/tree/main/quickstart#readme) for the most current documentation.
+  For the most up-to-date instructions on deploying OpenCHAMI, follow the **[OpenCHAMI Tutorial](/docs/tutorial/)**. It provides step-by-step guidance for setting up OpenCHAMI in a controlled environment using Podman Quadlets.
 
 Happy HPC!
 
@@ -25,91 +23,37 @@ Happy HPC!
 
 ## Start OpenCHAMI Services
 
-All the OpenCHAMI services come pre-configured to work together using docker-compose.  Using the directions below, you can clone the repos and run the containers in about five minutes without any external dependencies.  See [What's Next](#whats-next) for customization options and running jobs.
-
-{{< callout context="note" title="Quickstart" icon="rocket" >}}
-The quickstart is meant to be used on a dedicated node or VM running an RPM-based Linux system with an x86 processor.
-
-The minimum tested configuration is 4 vCPUs and 8 Gigabytes of memory
-
-```bash {title="Download, Configure, and Run the Quickstart…"}
-# Clone the repository
-git clone https://github.com/OpenCHAMI/deployment-recipes.git
-# Enter the quickstart directory
-cd deployment-recipes/quickstart/
-# Create the secrets in the .env file.  Do not share them with anyone. 
-# This also sets the system name for your certificates.  The system will be called "foobar" and the full url will be https://foobar.openchami.cluster which can be set in /etc/hosts to make life easier for you later
-./generate-configs.sh
-# Start the services
-docker compose -f base.yml -f postgres.yml -f jwt-security.yml -f haproxy-api-gateway.yml -f  openchami-svcs.yml -f autocert.yml -f configurator.yml up -d
-# This shouldn't take too long.  A minute or two depending on how long pulling containers takes.
-```
-
-Once you get the prompt back, you can download the public certificate from your ca and generate your access token.
-```bash {title="Obtain your rootca and tokens"}
-# Assuming you're using bash as your shell, you can use the included functions to simplify interactions with your new OpenCHAMI system.
-source bash_functions.sh
-# Download the root ca so you can validate the ssl certificates included with your system
-get_ca_cert > cacert.pem
-# Create a jwt access token for use with the apis.
-ACCESS_TOKEN=$(gen_access_token)
-# If you're curious about that token, you can safely copy and paste it into https://jwt.io to learn more.
-# Add an entry to /etc/hosts for the cluster
-echo '127.0.0.1  foobar.openchami.cluster' | sudo tee -a /etc/hosts
-# Use curl to confirm that everything is working
-curl --cacert cacert.pem -H "Authorization: Bearer $ACCESS_TOKEN" https://foobar.openchami.cluster:8443/hsm/v2/State/Components
-# This should respond with an empty set of Components: {"Components":[]}
-```
-
-Explore the environment on [GitHub](https://github.com/openchami/deployment-recipes/tree/main/quickstart/).
-
-Also, take a look at the [`ochami` command line tool](https://github.com/OpenCHAMI/ochami) for interacting with OpenCHAMI beyond using cURL.
+The **[OpenCHAMI Tutorial](/docs/tutorial/)** provides the most current and detailed instructions for deploying OpenCHAMI. Follow the tutorial to set up your environment and start the services using Podman Quadlets and the [Release RPM](https://github.com/OpenCHAMI/release).
+
+{{< callout context="note" title="Legacy Docker Compose" icon="rocket" >}}
+For legacy Docker Compose deployments, see the [deployment-recipes repository](https://github.com/OpenCHAMI/deployment-recipes/tree/main/quickstart). Note that these recipes are deprecated and not recommended for new users.
 {{< /callout >}}
 
 ### Dependencies and Assumptions
 
-The OpenCHAMI services themselves are all containerized and tested running under `docker compose`.  It should be possible to run OpenCHAMI services on any system with Docker installed.
+The **[OpenCHAMI Tutorial](/docs/tutorial/)** uses Podman Quadlets for container management and is tested on Rocky Linux 9 with x86 processors.
 
-This quickstart makes a few assumptions about the target operating system and is only tested on Rocky Linux 9.3 running on x86 processors.  Feel free to file bugs about other configurations, but we will prioritize support for systems that we can directly test at LANL.
+For Docker Compose deployments (legacy), the OpenCHAMI services are containerized and tested running under `docker compose`. See the [deployment-recipes repository](https://github.com/OpenCHAMI/deployment-recipes/tree/main/quickstart) for details (not recommended for new users).
 
 #### Assumptions
 
-* Linux - The quickstart automation makes several assumptions about the behavior Unix tools and their operation under bash from Rocky Linux 9.3.
-* x86_64 - Some of the containers involved are built and tested for alternative operating systems and architectures, but the solution as a whole is only tested with x86 containers.
-* Dedicated System - The `docker compose` setup assumes that it can take control of several TCP ports and interact with the host network for DHCP and TFTP.  It is tested on a dedicated virtual machine.
-* Local Name Registration - The quickstart bootstraps a Certificate Authority and issues an SSL certificate with a predictable name.  For access, you will need to add that name/IP to /etc/hosts on all clients or make it resolvable through your site DNS.
+See the **[OpenCHAMI Tutorial](/docs/tutorial/)** for current system requirements and assumptions.
 
 #### Dependencies
 
-* Docker - This quickstart assumes that the target operating system is Rocky Linux 9.3, which by default does not come pre-installed with Docker. Rocky also does not by default have access to Docker's repositories, and will install an alternaitve that's incompatible with OpenCHAMI, Podman, when a user attempts to install `docker` from yum. We've provided steps from [Docker's installation guide](https://docs.docker.com/engine/install/rhel/) to make sure you can get your containers up and running with ease:
-
-Install yum-utils and point your machine at Docker's repo:
-```bash {title="Install yum-utils"}
-sudo yum install -y yum-utils
-```
-```bash {title="Add Docker's repository to your machine"}
-sudo yum-config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
-```
-Install Docker and start Docker's service:
-```bash {title="Install Docker and related utilities"}
-sudo yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
-```
-```bash {title="Start the Docker daemon"}
-sudo systemctl start docker
-```
-Additional verification and troubleshooting steps available at the page linked above if needed.
+See the **[OpenCHAMI Tutorial](/docs/tutorial/)** for current dependencies and installation instructions.
 
 
 
 ## What's next
 
-Now that you've got a set of containers up and running that provide OpenCHAMI services, it's time to use them.  We've got a set of administration guides and user guides for you to choose from.
+Now that you know where to find the current OpenCHAMI deployment instructions, explore the tutorial and related guides.
 
 {{< card-grid >}}
 {{< link-card
-  title="Docker Compose Tour"
-  description="Learn just enough docker compose to explore our quickstart files"
-  href="/guides/docker_tour/"
+  title="OpenCHAMI Tutorial"
+  description="Step-by-step guide for deploying OpenCHAMI"
+  href="/docs/tutorial/"
 >}}
 {{< link-card
   title="Run a job"
@@ -126,9 +70,9 @@ Now that you've got a set of containers up and running that provide OpenCHAMI se
 {{< /card-grid >}}
 
 
-## Helpful docker compose cheatsheet
+## Helpful references
 
-This quickstart uses `docker compose` to start up services and define dependencies.  If you have a basic understanding of Docker, you should be able to work with the included services.  Some handy items to remember for when you are exploring the deployment are below.
+For Docker Compose deployments (legacy), this quickstart uses `docker compose` to start up services and define dependencies. If you have a basic understanding of Docker, you should be able to work with the included services. Some handy items to remember for when you are exploring the deployment are below.
 
 
 * `docker volume list` This lists all the volumes.  If they exist, the project will try to reuse them.  That might not be what you want.

diff --git a/content/docs/handbook/1-installation.md b/content/docs/handbook/1-installation.md
@@ -13,45 +13,40 @@ homepage: false
 <!-- vi: set tw=80 sw=2 sts=2: -->
 
 Since OpenCHAMI is composable and adaptable, it can be installed and deployed in
-a variety of ways: bare-metal, via Docker/Docker Compose, via [Podman
-Quadlets](https://www.redhat.com/en/blog/quadlet-podman), and even Kubernetes.
-This page provides an index to some of them.
+a variety of ways. The best method for you depends on your environment and use
+case.
 
-## 1.1. Deployment Recipes
+We recommend starting with the **[OpenCHAMI Tutorial](/docs/tutorial/)**, which
+provides a standardized way to learn OpenCHAMI using Podman Quadlets. Once you
+are familiar with the basics, you can explore other deployment methods.
 
-The OpenCHAMI organization maintains a Git repository containing [deployment
-recipes](https://github.com/OpenCHAMI/deployment-recipes) used by various sites.
-It is ever-evolving, but currently it has recipes for Docker Compose, Podman
-Quadlets, and Helm for Kubernetes.
+## 1.1. Recommended for New Users
 
-## 1.2. Release RPM
+- **Tutorial (Podman Quadlets)** -- The best way to learn OpenCHAMI. Uses the
+  [Release RPM](https://github.com/OpenCHAMI/release) for a unified deployment.
+  - [**Guide**](/docs/tutorial/)
 
-There is also an official [release](https://github.com/OpenCHAMI/release) Git
-repository that houses an RPM package that installs OpenCHAMI services as Podman
-Quadlets and installs configuration files in standard filesystem locations. It
-is meant to be a "quickstart for quadlets" on Red Hat systems since, by
-installing the package and running an additional command, it configures and
-starts a base OpenCHAMI installation that is ready to boot nodes.
+## 1.2. Alternative Deployment Methods
 
-Currently, only RPM is supported and there is only one package that contains all
-of the necessary services. This is obviously not very composable, so future work
-entails supporting more packaging options. Contributions are welcome!
-
-To fill any gaps, the deployment recipes repository mentioned above is a good
-starting point.
-
-## 1.3. Deployment Guide Index
-
-Here is an index of common OpenCHAMI deployment strategies with links to
-guides/resources:
-
-- **Docker Compose (Quickstart)** -- Use Docker Compose to quickly get started
-  with OpenCHAMI by setting up base services.
-  - [**Guide/Repo**](https://github.com/OpenCHAMI/deployment-recipes/tree/main/quickstart)
-- **Podman Quadlets (Release RPM)** -- Use the OpenCHAMI release RPM to run
-  OpenCHAMI services using Podman Quadlets.
-  - [**Guide**](/docs/tutorial/#14-install-openchami)
+- **Release RPM (Quadlet-Based)** -- Deploy OpenCHAMI as Podman Quadlets on Red
+  Hat-based systems. Companion to the tutorial.
   - [**Repo**](https://github.com/OpenCHAMI/release)
+- **Kubernetes (kube-deploy)** -- Deploy OpenCHAMI on Kubernetes using Helm
+  charts.
+  - [**Repo**](https://github.com/OpenCHAMI/kube-deploy)
+- **Kubernetes Operator (openchami-operator)** -- Use the OpenCHAMI operator for
+  advanced Kubernetes orchestration.
+  - [**Repo**](https://github.com/OpenCHAMI/openchami-operator)
+- **Integration Sandbox** -- Test OpenCHAMI in a sandbox environment.
+  - [**Repo**](https://github.com/OpenCHAMI/integration-sandbox)
 - **Libvirt Virtual Machines** -- Boot Libvirt VMs using OpenCHAMI and Podman
   Quadlets.
   - [**Guide**](/docs/guides/libvirt)
+
+## 1.3. Organization-Specific Recipes
+
+The OpenCHAMI organization maintains a Git repository containing
+[deployment recipes](https://github.com/OpenCHAMI/deployment-recipes) with
+organization-specific patterns (e.g., Dell, LBNL). These are **not officially
+supported** for general use and may require customization. New users should
+start with the tutorial instead.
diff --git a/content/docs/software/_index.md b/content/docs/software/_index.md
@@ -13,7 +13,7 @@ sidebar:
 ---
 
 {{< callout context="tip" title="Did you know?" icon="rocket" >}}
-The [OpenCHAMI quickstart](https://github.com/openchami/deployment-recipes/) has been used to boot over 600 compute nodes in about five minutes, including POST!.
+The [OpenCHAMI Tutorial](/docs/tutorial/) has been used to boot over 600 compute nodes in about five minutes, including POST!
 {{< /callout >}}
 
 

diff --git a/content/docs/tutorial.md b/content/docs/tutorial.md
@@ -17,9 +17,18 @@ toc: true
 
 ### 0.1. Overview
 
-This tutorial focuses on setting up OpenCHAMI in a virtual environment such that
-the reader may become familiar with the basics of using OpenCHAMI and apply
-learned concepts to real deployments.
+This tutorial is the **recommended starting point** for new users. It focuses on
+setting up OpenCHAMI in a virtual environment such that the reader may become
+familiar with the basics of using OpenCHAMI and apply learned concepts to real
+deployments.
+
+OpenCHAMI supports multiple deployment methods. This tutorial uses Podman
+Quadlets and the [Release RPM](https://github.com/OpenCHAMI/release), but you
+can also deploy using:
+
+- [Kubernetes (kube-deploy)](https://github.com/OpenCHAMI/kube-deploy)
+- [Kubernetes Operator (openchami-operator)](https://github.com/OpenCHAMI/openchami-operator)
+- Organization-specific recipes in [deployment-recipes](https://github.com/OpenCHAMI/deployment-recipes) *(not recommended for new users)*
 
 ### 0.2. Setup