Skip to main content

Environment Setup

This guide provides instructions for setting up a development environment and contributing to the homelab project.

Prerequisites​

Before getting started, ensure you have:

  • Node.js (22.21.0 recommended)
  • Git for version control
  • Make for development automation
  • Docker (optional, if using devcontainers)
  • A code editor (VSCode recommended)

Quick Start​

The project includes a devcontainer configuration that sets up a complete development environment.

  1. Open the project in VSCode with the Dev Containers extension

  2. Reopen in Container: Press Ctrl+Shift+P (or Cmd+Shift+P on macOS) and select "Dev Containers: Reopen in Container"

  3. Wait for setup: The devcontainer will automatically run the post-create.sh script which installs dependencies and tooling

Option 2: Local Development Setup​

If you prefer local development without devcontainers:

  1. Install Node.js and Make

  2. Install project dependencies:

make install-project

This installs npm dependencies and links the homelab CLI globally.

  1. Install tooling (required for some operations):
Non-standard PATH

By default, this Makefile target installs to the /usr/local/bin folder. This directory will need to be added to your system PATH.

Alternatively, use BIN=[path] make install-tools to install tools to another location.

make install-tools
  1. Install documentation dependencies (if working on docs):
make install-docs

Running the CLI​

Use the homelab CLI command:

homelab [command] [options]

View all available commands:

homelab --help

Documentation Development​

The project uses Docusaurus for documentation.

Local Documentation Server​

Start the development server:

make dev-docs

This starts a local server on localhost:3000 with live reloading.

Code Formatting​

The project uses Prettier for code formatting. Format on save is configured automatically in devcontainers.

Next Steps​

Once your environment is set up:

  • See Architecture docs to understand the project structure and design decisions
  • See Configuration docs to learn about configuration files and options
  • See Operations docs for cluster administration tasks