---
slug: setup
title: Setup
description: Install Holos and build the initial structure.
sidebar_position: 20
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import RenderPlatformDiagram from '@site/src/diagrams/render-platform-sequence.mdx';

# Setup

## Overview

This tutorial will guide you through the installation of Holos and its
dependencies, as well as the initialization of a minimal Platform that you can
extend to meet your specific needs.

## Installing Holos

Holos is distributed as a single file executable that can be installed in a
couple of ways.

### Releases

Download `holos` from the [releases] page and place the executable into your
shell path.

### Go Install

```shell
go install github.com/holos-run/holos/cmd/holos@latest
```

### Dependencies

Holos integrates with the following tools that should be installed to enable
their functionality.

- [Helm] to fetch and render Helm chart Components.
- [Kubectl] to [kustomize] components.

## Generating a Platform

Use `holos` to generate a minimal platform using the recommended directory
structure.  First, create and cd into a blank directory. Then use the `holos
generate platform` command to generate a minimal platform.

```shell
mkdir holos-tutorial
cd holos-tutorial
holos init platform v1alpha5
```

Holos creates a `platform` directory containing a `platform.gen.cue` file
serving as the entry point for your new platform configuration.  You'll register
software components with the platform using the CUE code in this `platform`
directory.

## Rendering the Platform

We usually make configuration changes with holos in the following loop:

1. Edit some CUE code.
2. Render the whole platform.
3. Review the fully rendered manifests.
4. Repeat

Rendering the platform to plain manifest files allows us to see the changes
clearly.

<Tabs groupId="66379FE3-206D-4DF1-BAF0-29C9A6C17D00">
  <TabItem value="command" label="Command">
```bash
holos render platform ./platform
```
  </TabItem>
  <TabItem value="output" label="Output">
```txt
rendered platform in 8.292µs
```
  </TabItem>
  <TabItem value="diagram" label="Diagram">
    <RenderPlatformDiagram />
  </TabItem>
</Tabs>

In this initial state `holos` doesn't do anything because no components are
registered with the platform.  You can inspect the Platform definition to get
this insight.

<Tabs groupId="218658D2-1305-46D3-8F55-8DA8EB45F114">
  <TabItem value="command" label="Command">
```bash
holos cue export --expression holos --out=yaml ./platform
```
  </TabItem>
  <TabItem value="output" label="Output">
```yaml
kind: Platform
apiVersion: v1alpha5
metadata:
  name: default
spec:
  components: []
```
Note the `spec.components` field is empty.
  </TabItem>
</Tabs>

## Next Steps

You've got the structure of your platform configuration in place. Continue on to
[Hello Holos] where you'll learn how easy it is to manage a Helm chart with
holos.

[Helm]: https://github.com/helm/helm/releases
[Kubectl]: https://kubernetes.io/docs/tasks/tools/
[kustomize]: https://kustomize.io/
[Local Cluster]: ../topics/local-cluster.mdx
[Hello Holos]: ./hello-holos.mdx
[releases]: https://github.com/holos-run/holos/releases
[k3d]: https://k3d.io/
[OrbStack]: https://docs.orbstack.dev/install
[Docker]: https://docs.docker.com/get-started/get-docker/