The KOTS HelmChart custom resource provides instructions to KOTS about how to deploy the Helm chart. The name and chartVersion listed in the HelmChart custom resource must match the name and version of a Helm chart archive in the release. The optionalValues field sets the specified Helm values when a given conditional statement evaluates to true. In this case, if the application is installed with Embedded Cluster, then the Gitea service type is set to `NodePort` and the node port is set to `"32000"`. This will allow Gitea to be accessed from the local machine after deployment for the purpose of this quick start.
The HelmChart custom resource provides instructions to the installer about how to deploy the Helm chart. The name and chartVersion listed in the HelmChart custom resource must match the name and version of a Helm chart archive in the release. This HelmChart resource includes several `values` and conditional `optionalValues` that are supplied to `helm template` during deployment.
The KOTS Application custom resource enables features in the Replicated Admin Console such as branding, release notes, application status indicators, and custom graphs.
The YAML below provides a name for the application to display in the Admin Console, adds a custom status informer that displays the status of the gitea Deployment resource in the Admin Console dashboard, adds a custom application icon, and adds the port where the Gitea service can be accessed so that the user can open the application after installation.
The Replicated Application custom resource enables features in the Replicated Admin Console UI, which is used to configure, install, update, and manage applications. This Application resource provides a name for the application to display in the Admin Console, adds custom status informers that are used to display the status of the deployment in the Admin Console dashboard, and adds a custom application icon.
The Kubernetes SIG Application custom resource supports functionality such as including buttons and links on the Replicated Admin Console dashboard. The YAML below adds an Open App button to the Admin Console dashboard that opens the application using the service port defined in the KOTS Application custom resource.
+The Kubernetes SIG Application custom resource supports functionality such as including buttons and links on the Admin Console dashboard. This SIG Application resource adds an Open SlackerNews button that opens the application.
The Config custom resource defines the application configuration fields that are exposed to the user in the Admin Console. These fields can then be mapped to the `values.yaml` file for the Helm chart. This Config resource includes several fields, but you will only use a few of them when installing SlackerNews for the purpose of this tutorial.
+
+ 
- [View a larger version of this image](/images/quick-start-select-gitea-app.png)
+ [View a larger version of this image](/images/quick-start-app-dropdown-slackernews.png)
1. Click **Customers > Create customer**.
@@ -199,119 +256,220 @@ Before you begin, ensure that you have access to a VM that meets the requirement
1. For **Channel**, select **Unstable**. This allows the customer to install releases promoted to the Unstable channel.
- 1. For **License type**, select **Development**.
+ 1. For **Customer type**, select **Development**.
- 1. For **License options**, enable the following entitlements:
- * **KOTS Install Enabled**
- * **Embedded Cluster Enabled**
+ 1. For **Install types**, enable **Embedded Cluster (current generation product)** and disable the other install type options.
1. Click **Save Changes**.
+1. If you brought your own VM, SSH onto your VM. Otherwise, follow these steps to create and SSH onto a VM with Compatibility Matrix:
+
+ 1. Create an Ubuntu VM that expires after two hours:
+
+ ```bash
+ replicated vm create --distribution ubuntu --version 24.04 --instance-type r1.small --disk 50 --ttl 2h
+ ```
+ **Example output:**
+ ```bash
+ ID NAME DISTRIBUTION VERSION STATUS NETWORK CREATED EXPIRES COST
+ 97940819 practical_black ubuntu 24.04 queued c726ffff 2025-08-20 14:32 MDT - $0.69
+ ```
+
+ 1. After a few minutes, check the status of the VM to see when it is `running`:
+
+ ```bash
+ replicated vm ls
+ ```
+ **Example output:**
+ ```bash
+ ID NAME DISTRIBUTION VERSION STATUS NETWORK CREATED EXPIRES COST
+ 97940819 practical_black ubuntu 24.04 running c726ffff 2025-08-20 14:32 MDT 2025-08-20 16:33 MDT $0.69
+ ```
+
+ 1. Run the following command to use the Compatibility Matrix Forwarder to SSH onto the VM:
+
+ ```bash
+ ssh VM_ID@replicatedvm.com
+ ```
+ Where `VM_ID` is the `ID` from the output of the `replicated vm ls` command.
+
+ :::note
+ If you are prompted to add the fingerprint for replicatedvm.com, type `yes` and press Enter.
+ :::
+
+ 1. When prompted, provide the passphrase for the SSH key in your linked GitHub account. Compatibility Matrix uses GitHub SSH to provide access to the VM.
+
1. Install the application with Embedded Cluster:
- 1. On the page for the customer that you created, click **Install instructions > Embedded Cluster**.
+ 1. In the Vendor Portal, on the page for the customer that you created, click **Embedded Cluster install instructions**.
- 
+ 
- [View a larger image](/images/customer-install-instructions-dropdown.png)
+ [View a larger version of this image](/images/quick-start-slackernews-customer-install-instructions-button.png)
- 1. On the command line, SSH onto your VM and run the commands in the **Embedded cluster install instructions** dialog to download the latest release, extract the installation assets, and install.
+ 1. On your VM, run the commands in the **Embedded cluster install instructions** dialog to download the latest release, extract the installation assets, and install SlackerNews.
- 
+
[View a larger version of this image](/images/embedded-cluster-install-dialog-latest.png)
- 1. When prompted, enter a password for accessing the Admin Console.
+ 1. When prompted by the `install` command, set a password for accessing the Admin Console. You will use this password to log in to the Admin Console in a later step.
The installation command takes a few minutes to complete.
**Example output:**
```bash
- ? Enter an Admin Console password: ********
- ? Confirm password: ********
- ✔ Host files materialized!
- ✔ Running host preflights
- ✔ Node installation finished!
- ✔ Storage is ready!
- ✔ Embedded Cluster Operator is ready!
- ✔ Admin Console is ready!
- ✔ Additional components are ready!
- Visit the Admin Console to configure and install gitea-kite: http://104.155.145.60:30000
+ ? Set the Admin Console password (minimum 6 characters): ********
+ ? Confirm the Admin Console password: ********
+
+ ✔ Initialization complete
+ ✔ Host preflights passed
+ ✔ Node is ready
+ ✔ Storage is ready
+ ✔ Runtime Operator is ready
+ ✔ Admin Console is ready
+ ✔ Additional components are ready
+
+ -----------------------------------------------------------------
+ Visit the Admin Console to configure and install slackernews-gnu:
+
+ http://10.0.0.11:30000
+ -----------------------------------------------------------------
```
At this point, the cluster is provisioned and the Admin Console is deployed, but the application is not yet installed.
- 1. Go to the URL provided in the output to access to the Admin Console.
-
- 1. On the Admin Console landing page, click **Start**.
+ 1. Do one of the following to access the Admin Console:
+ * If you brought your own VM, go to the URL provided in the output of the install command.
+ :::note
+ The IP address in the provided URL might be the private IP address of your VM. You might need to edit the URL to use the public IP address.
+ :::
+ * If you created the VM with Compatibility Matrix:
+ 1. In the Vendor Portal, go to [**Compatibility Matrix**](https://vendor.replicated.com/compatibility-matrix/overview).
+ 1. Open the dot menu for your VM and click **Edit VM**.
+
+ 
+
+ [View a larger version of this image](/images/compatibility-matrix-edit-vm.png)
+
+ 1. Under **Ingress & Ports**, for **Add DNS record**, click **Add** to create a DNS record using the default settings. This will provide a hostname where you can access the Admin Console.
+
+ 1. Add another DNS record with a **Target Port** of **443**. This will provide a hostname where you can access SlackerNews after it's installed.
+
+ The following shows an example of both of these DNS records added to a VM:
+
+ 
+ [View a larger version of this image](/images/compatibility-matrix-dns-record.png)
- 1. On the **Secure the Admin Console** screen, review the instructions and click **Continue**. In your browser, follow the instructions that were provided on the **Secure the Admin Console** screen to bypass the warning.
+ 1. (Optional) Copy the URL for the DNS record with a target port of 443 and save it somewhere on your local machine. You will be asked to provide this hostname in the Admin Console as part of the installation process for SlackerNews.
+
+ 1. In a browser, navigate to the URL for the DNS record with a target port of 30000.
- 1. On the **Certificate type** screen, either select **Self-signed** to continue using the self-signed Admin Console certificate or click **Upload your own** to upload your own private key and certificacte.
+ The Admin Console opens.
+
+ 1. If you are directed to the Admin Console landing page:
+ 1. Click **Start**.
+ 1. On the **Secure the Admin Console** screen, review the instructions and click **Continue**. In your browser, follow the instructions that were provided on the **Secure the Admin Console** screen to bypass the warning.
+ 1. On the **Certificate type** screen, either select **Self-signed** to continue using the self-signed Admin Console certificate or click **Upload your own** to upload your own private key and certificacte. By default, a self-signed TLS certificate is used to secure communication between your browser and the Admin Console. You will see a warning in your browser every time you access the Admin Console unless you upload your own certificate.
+
+ :::note
+ If you created the VM with Compatibility Matrix, you might not see these pages. Instead, your browser might automatically redirect to the Admin Console login screen.
+ :::
+
+ 1. On the login screen, enter the Admin Console password that you set and click **Log in**.
- By default, a self-signed TLS certificate is used to secure communication between your browser and the Admin Console. You will see a warning in your browser every time you access the Admin Console unless you upload your own certificate.
+ 
- 1. On the login page, enter the Admin Console password that you created during installation and click **Log in**.
+ [View a larger version of this image](/images/quick-start-slackernews-admin-console-login.png)
1. On the **Configure the cluster** screen, you can view details about the VM where you installed, including its node role, status, CPU, and memory. Users can also optionally add additional nodes on this page before deploying the application. Click **Continue**.
- The Admin Console dashboard opens.
+ 
+
+ [View a larger version of this image](/images/quick-start-slackernews-configure-the-cluster.png)
+
+ 1. On the **Configure SlackerNews** screen, complete the following fields:
+
+ * For **Hostname**:
+ * If you created the VM with Compatibility Matrix, enter the URL that you copied for the DNS record with a target port of 443. For example, `pensive-keldysh.ingress.replicatedcluster.com`.
+
+ * If you are using your own VM, provide the public IP address for your VM. You can copy the IP address from your browser's address bar where you are currently accessing the Admin Console. Alternatively, if you have a hostname for your VM's IP address, you can provide that instead.
- 1. On the Admin Console dashboard, next to the version, click **Deploy** and then **Yes, Deploy**.
+ * For **Application Access > Service Type**, ensure that **NodePort** is selected. Leave the **Node Port** field blank to use the default port of 443.
+
+ * For **Postgresql**, ensure that **Deploy Postgresql Database** is enabled to deploy the built-in Postgresql database.
- The application status changes from Missing to Unavailable while the `gitea` Deployment is being created.
+ Leave the other fields on the **Configure SlackerNews** screen empty. They are not applicable for this quick start.
- 1. After a few minutes when the application status is Ready, click **Open App** to view the Gitea application in a browser.
+ 
+
+ [View a larger version of this image](/images/quick-start-slackernews-configure-slackernews.png)
- For example:
+ 1. Click **Continue**.
+
+ The Admin Console dashboard opens. The application status changes from Missing to Unavailable while the application is being deployed. You can click **Details** next to the status for more information about the status of specific application resources.
+
+ After a few minutes, the status changes to Ready when the application is deployed:
+
+ 
+
+ [View a larger version of this image](/images/quick-start-slackernews-adm-dashboard-ready.png)
+
+ 1. After a few minutes when the application status is Ready, click **Open SlackerNews** to view SlackerNews in a browser.
- 
+ 
- [View a larger version of this image](/images/gitea-ec-ready.png)
+ [View a larger version of this image](/images/slackernews-landing-page.png)
- 
+1. View telemetry for the instance that you just deployed:
- [View a larger version of this image](/images/gitea-app.png)
+ 1. Return to the Vendor Portal, select the SlackerNews application, and go to **Customers**. Under the name of the customer, confirm that you can see an active instance.
-1. Return to the Vendor Portal and go to **Customers**. Under the name of the customer, confirm that you can see an active instance.
+ 
- This instance telemetry is automatically collected and sent back to the Vendor Portal by both KOTS and the Replicated SDK. For more information, see [About Instance and Event Data](/vendor/instance-insights-event-data).
+ [View a larger version of this image](/images/quick-start-slackernews-customer-instance.png)
-1. Under **Instance ID**, click on the ID to view additional insights including the versions of Kubernetes and the Replicated SDK running in the cluster where you installed the application. For more information, see [Instance Details](/vendor/instance-insights-details).
+ This instance telemetry is automatically collected and sent back to the Vendor Portal by Embedded Cluster and the Replicated SDK. For more information, see [About Instance and Event Data](/vendor/instance-insights-event-data).
+
+ 1. (Optional) Under **Instance ID**, click on the ID to view additional insights including the versions of Kubernetes and the Replicated SDK running in the cluster where you installed the application.
1. Create a new release that adds preflight checks to the application:
- 1. In your local filesystem, go to the `gitea` directory.
+ 1. In your local filesystem, go to the `quick-start/chart/slackernews` directory.
- 1. Create a `gitea-preflights.yaml` file in the `templates` directory:
+ 1. Create a `preflights.yaml` file in the `templates` directory for the chart:
```
- touch templates/gitea-preflights.yaml
+ touch templates/preflights.yaml
```
- 1. In the `gitea-preflights.yaml` file, add the following YAML to create a Kubernetes Secret with a simple preflight spec:
+ 1. In the `preflights.yaml` file, add the following YAML to create a Kubernetes Secret with a simple preflight spec:
```yaml
apiVersion: v1
kind: Secret
metadata:
+ name: slackernews-preflight
labels:
troubleshoot.sh/kind: preflight
- name: "{{ .Release.Name }}-preflight-config"
stringData:
- preflight.yaml: |
+ preflight.yaml: |-
apiVersion: troubleshoot.sh/v1beta2
kind: Preflight
metadata:
- name: preflight-sample
+ name: slackernews-preflight
spec:
collectors:
+ - clusterInfo: {}
+ - clusterResources: {}
- http:
collectorName: slack
get:
url: https://api.slack.com/methods/api.test
+ timeout: 20s
analyzers:
+ # verify that slack is accessible
- textAnalyze:
checkName: Slack Accessible
fileName: slack.json
@@ -324,41 +482,54 @@ Before you begin, ensure that you have access to a VM that meets the requirement
when: "false"
message: "Cannot access the Slack API. Check that the server can reach the internet and check [status.slack.com](https://status.slack.com)."
```
+
The YAML above defines a preflight check that confirms that an HTTP request to the Slack API at `https://api.slack.com/methods/api.test` made from the cluster returns a successful response of `"status": 200,`.
- 1. In the `Chart.yaml` file, increment the version to 1.0.7:
+ 1. In the `Chart.yaml` file, increment the version to 1.0.1:
```yaml
# Chart.yaml
- version: 1.0.7
+ version: 1.0.1
```
1. Update dependencies and package the chart to a `.tgz` chart archive:
```bash
- helm package -u .
+ helm package --dependency-update .
```
- 1. Move the chart archive to the `manifests` directory:
+ 1. Move the `slackernews-1.0.1.tgz` chart archive to the `manifests` directory:
```bash
- mv gitea-1.0.7.tgz manifests
+ mv slackernews-1.0.1.tgz ../../manifests
```
- 1. In the `manifests` directory, open the KOTS HelmChart custom resource (`gitea.yaml`) and update the `chartVersion`:
+ 1. Change to the `manifests` directory.
+
+ 1. In the `manifests` directory, open the HelmChart custom resource (`slackernews.yaml`) and update the `chartVersion` to match the new archive:
```yaml
- # gitea.yaml KOTS HelmChart
- chartVersion: 1.0.7
+ # slackernews.yaml HelmChart
+ chartVersion: 1.0.1
```
- 1. Remove the chart archive for version 1.0.6 of the Gitea chart from the `manifests` directory:
+ 1. Remove the unused chart archive for version 1.0.0 from the `manifests` directory:
```
- rm gitea-1.0.6.tgz
+ rm slackernews-1.0.0.tgz
```
- 1. From the `manifests` directory, create and promote a new release, setting the version label of the release to `0.0.2`:
+ 1. From the `manifests` directory, lint the release manifests:
+
+ ```bash
+ replicated release lint --yaml-dir .
+ ```
+
+ :::note
+ If you see a `helm-archive-missing` error, confirm that you have only one chart archive in `manifests` for version 1.0.1, and that the `chartVersion` in the HelmChart resource is also set to `1.0.1`. If you notice that any of the errors are from files in your `.history/` directory, run `rm -rf .history` and then lint the files again.
+ :::
+
+ 1. Create and promote a new release, setting the version label of the release to `0.0.2`:
```bash
replicated release create --yaml-dir . --promote Unstable --version 0.0.2
@@ -378,32 +549,41 @@ Before you begin, ensure that you have access to a VM that meets the requirement
The new version is displayed automatically.
- 1. Click **Deploy** next to the new version.
+ 
- The Embedded Cluster upgrade wizard opens.
+ [View a larger version of this image](/images/quick-start-slackernews-available-updates.png)
- 1. In the Embedded Cluster upgrade wizard, on the **Preflight checks** screen, note that the "Slack Accessible" preflight check that you added was successful. Click **Next: Confirm and deploy**.
+ 1. Click **Deploy** next to the new version.
- 
+ The Embedded Cluster upgrade wizard opens. Follow the steps until you see the **Preflight checks** screen.
- [View a larger version of this image](/images/quick-start-ec-upgrade-wizard-preflight.png)
+ 1. On the **Preflight checks** screen, note that the "Slack Accessible" preflight check that you added was successful. Click **Next: Confirm and deploy**.
- :::note
- The **Config** screen in the upgrade wizard is bypassed because this release does not contain a KOTS Config custom resource. The KOTS Config custom resource is used to set up the Config screen in the KOTS Admin Console.
- :::
+ 
+
+ [View a larger version of this image](/images/quick-start-slackernews-preflight.png)
1. On the **Confirm and Deploy** page, click **Deploy**.
-1. Reset and reboot the VM to remove the installation:
+1. Clean up the installation:
- ```bash
- sudo ./APP_SLUG reset
- ```
- Where `APP_SLUG` is the unique slug for the application.
-
- :::note
- You can find the application slug by running `replicated app ls` on your local machine.
- :::
+ * If you created the VM with Compatibility Matrix, delete the VM:
+
+ ```bash
+ replicated vm rm VM_ID
+ ```
+ Where VM_ID is the ID of the VM. You can run `replicated vm ls` to get the ID.
+
+ * If you brought your own VM, use Embedded Cluster to reset and reboot the VM to remove the installation:
+
+ ```bash
+ sudo ./APP_SLUG reset
+ ```
+ Where `APP_SLUG` is the unique slug for the application.
+
+ :::note
+ You can find the application slug by running replicated app ls on your local machine.
+ :::
## Next Steps
@@ -413,7 +593,7 @@ Congratulations! As part of this quick start, you:
* Installed the release on a VM with Embedded Cluster
* Viewed telemetry for the installed instance in the Vendor Portal
* Created a new release to add preflight checks to the application
-* Updated the application from the Admin Console
+* Updated the application to the new version using Embedded Cluster
Now that you are familiar with the workflow of creating, installing, and updating releases, you can begin onboarding your own application to the Replicated Platform.
@@ -423,18 +603,9 @@ To get started, see [Onboard to the Replicated Platform](replicated-onboarding).
For more information about the Replicated Platform features mentioned in this quick start, see:
-* [About Distributing Helm Charts with KOTS](/vendor/helm-native-about)
+* [Embedded Cluster Overview](/vendor/embedded-overview)
+* [About Compatibility Matrix](/vendor/testing-about)
* [About Preflight Checks and Support Bundles](/vendor/preflight-support-bundle-about)
* [About the Replicated SDK](/vendor/replicated-sdk-overview)
-* [Introduction to KOTS](/intro-kots)
-* [Managing Releases with the CLI](/vendor/releases-creating-cli)
-* [Packaging a Helm Chart for a Release](/vendor/helm-install-release)
-* [Using Embedded Cluster](/vendor/embedded-overview)
-
-## Related Tutorials
-
-For additional tutorials related to this quick start, see:
-
-* [Deploying a Helm Chart on a VM with Embedded Cluster](/vendor/tutorial-embedded-cluster-setup)
-* [Adding Preflight Checks to a Helm Chart](/vendor/tutorial-preflight-helm-setup)
-* [Deploying a Helm Chart with KOTS and the Helm CLI](/vendor/tutorial-kots-helm-setup)
\ No newline at end of file
+* [Manage Releases with the CLI](/vendor/releases-creating-cli)
+* [Package a Helm Chart for a Release](/vendor/helm-install-release)
\ No newline at end of file
diff --git a/static/images/compatibility-matrix-dns-record.png b/static/images/compatibility-matrix-dns-record.png
new file mode 100644
index 0000000000..a6fdfba9e9
Binary files /dev/null and b/static/images/compatibility-matrix-dns-record.png differ
diff --git a/static/images/compatibility-matrix-edit-vm.png b/static/images/compatibility-matrix-edit-vm.png
new file mode 100644
index 0000000000..486a29af11
Binary files /dev/null and b/static/images/compatibility-matrix-edit-vm.png differ
diff --git a/static/images/create-customer.png b/static/images/create-customer.png
index 59c7f5b767..d001231e9d 100644
Binary files a/static/images/create-customer.png and b/static/images/create-customer.png differ
diff --git a/static/images/embedded-cluster-install-dialog-latest.png b/static/images/embedded-cluster-install-dialog-latest.png
index 1b21a38e64..abf9d80141 100644
Binary files a/static/images/embedded-cluster-install-dialog-latest.png and b/static/images/embedded-cluster-install-dialog-latest.png differ
diff --git a/static/images/quick-start-app-dropdown-slackernews.png b/static/images/quick-start-app-dropdown-slackernews.png
new file mode 100644
index 0000000000..323c8c9937
Binary files /dev/null and b/static/images/quick-start-app-dropdown-slackernews.png differ
diff --git a/static/images/quick-start-slackernews-adm-dashboard-ready.png b/static/images/quick-start-slackernews-adm-dashboard-ready.png
new file mode 100644
index 0000000000..536c239f7d
Binary files /dev/null and b/static/images/quick-start-slackernews-adm-dashboard-ready.png differ
diff --git a/static/images/quick-start-slackernews-admin-console-login.png b/static/images/quick-start-slackernews-admin-console-login.png
new file mode 100644
index 0000000000..aae5f144d0
Binary files /dev/null and b/static/images/quick-start-slackernews-admin-console-login.png differ
diff --git a/static/images/quick-start-slackernews-available-updates.png b/static/images/quick-start-slackernews-available-updates.png
new file mode 100644
index 0000000000..6ae14b6834
Binary files /dev/null and b/static/images/quick-start-slackernews-available-updates.png differ
diff --git a/static/images/quick-start-slackernews-configure-slackernews.png b/static/images/quick-start-slackernews-configure-slackernews.png
new file mode 100644
index 0000000000..f3a7b8eabd
Binary files /dev/null and b/static/images/quick-start-slackernews-configure-slackernews.png differ
diff --git a/static/images/quick-start-slackernews-configure-the-cluster.png b/static/images/quick-start-slackernews-configure-the-cluster.png
new file mode 100644
index 0000000000..db389ea904
Binary files /dev/null and b/static/images/quick-start-slackernews-configure-the-cluster.png differ
diff --git a/static/images/quick-start-slackernews-customer-install-instructions-button.png b/static/images/quick-start-slackernews-customer-install-instructions-button.png
new file mode 100644
index 0000000000..accf0a7d3f
Binary files /dev/null and b/static/images/quick-start-slackernews-customer-install-instructions-button.png differ
diff --git a/static/images/quick-start-slackernews-customer-instance.png b/static/images/quick-start-slackernews-customer-instance.png
new file mode 100644
index 0000000000..2cd9c9284e
Binary files /dev/null and b/static/images/quick-start-slackernews-customer-instance.png differ
diff --git a/static/images/quick-start-slackernews-preflight.png b/static/images/quick-start-slackernews-preflight.png
new file mode 100644
index 0000000000..abe5f57e3a
Binary files /dev/null and b/static/images/quick-start-slackernews-preflight.png differ
diff --git a/static/images/slackernews-landing-page.png b/static/images/slackernews-landing-page.png
new file mode 100644
index 0000000000..9742d8f1aa
Binary files /dev/null and b/static/images/slackernews-landing-page.png differ