oxidecomputer / oxidecomputer/voxel

Add operator-facing documentation

Open
#64 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
8
Forks
0
Avg merge
1d 20h
Merged PRs (30d)
17

Description

Voxel is incredibly useful internally at Oxide. That being said, it must be run on bare-metal hardware, running our Helios operating system. It also has a large number of features detailed in the README, not all of which will be immediately useful to Oxide enthusiasts and potential/current customers.

Therefore, a standalone file for guiding operators on how to get Voxel running might be useful, with the audience being the greater public, along with Oxide prospects and customers who want to stand up a virtual rack on their own hardware.

This guide would cover:

  • Hardware requirements: See https://github.com/oxidecomputer/voxel/issues/18
  • Host preparation: installing Helios, post-install steps, remote access.
  • Installation and configuration: building from source, modifying voxel.toml settings.
  • Building images: control-plane images from Omicron source or TUF repos, FRR router images.
  • Launching a rack: launch/destroy, topology inspection.
  • Accessing the rack: host route setup, reaching services from other devices.
  • Interacting with the Voxel deployment: CLI/API usage, telemetry collection.
  • Multi-rack deployments: configuration and resource considerations.
  • Any additional reading.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the README and issue #18 for the hardware requirements, then review the existing Voxel setup, voxel.toml settings, and documented CLI/API usage. The finished standalone guide should cover host preparation, installation, image building, rack lifecycle and access, telemetry, and multi-rack considerations for public operators.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation, infrastructure
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.