Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
The Horizon development environment is designed to provide a comprehensive, containerized infrastructure for building and testing the self-hostable Configuration Management Database (CMDB). It leverages a Rust-based backend, a React-based frontend, and a cross-platform agent architecture supported by PostgreSQL and Redis. The setup ensures that developers have a consistent environment for managing IT infrastructure visibility, hardware discovery, and security configurations.
The environment relies on modern tooling including Rust nightly, Docker for service orchestration, and various scripts to automate the initialization of the data layer and API server.
Sources: README.md:16-24, IMPLEMENTATION_PLAN.md:27-35, AGENTS.md:5-10
Prerequisites and Environment Requirements
Horizon requires specific versions of the Rust compiler and external services to function correctly. The project follows a strict version policy, mandating the use of latest stable or nightly releases to leverage modern language features and security updates.
| Requirement | Version / Specification | Purpose |
|---|---|---|
| Rust | 1.94.0-nightly or later | Primary language for backend and agent |
| PostgreSQL | Latest stable | Primary data persistence layer |
| Redis | Latest stable | Caching and session management |
| Docker | Latest | Containerized service deployment |
| Node.js | 22-alpine (in Docker) | Frontend build environment |
Sources: README.md:118-123, IMPLEMENTATION_PLAN.md:36-39, IMPLEMENTATION_PLAN.md:1115-1120, Cargo.toml:13-14
Core Infrastructure Setup
The infrastructure is orchestrated using Docker Compose, which manages the lifecycle of the database and caching layers.
Container Orchestration
The docker-compose.yml file defines the internal network and volume persistence required for development. It establishes a dedicated bridge network named horizon-internal to isolate service communication.
The diagram shows the relationship between host directory persistence and the internal Docker network used for the database and cache.
Sources: docker-compose.yml:7-92, scripts/docker-dev.sh:70-76
Database Configuration
The development environment uses PostgreSQL as the primary store. The CLI provides tools to build the connection string dynamically based on environment variables.
| Variable | Default Value | Description |
|---|---|---|
HORIZON_DATABASE_HOST | localhost | Host address for Postgres |
HORIZON_DATABASE_PORT | 5432 | Port number for Postgres |
HORIZON_DATABASE_NAME | horizon | Name of the database |
HORIZON_DATABASE_USER | horizon | Database username |
HORIZON_DATABASE_SSL_MODE | require | SSL connection mode |
Sources: crates/cli/src/main.rs:25-50, docker-compose.yml:13-17
Development Workflow Commands
The project uses cargo for most development tasks, supplemented by a management script for Docker services.
Service Management
The scripts/docker-dev.sh script automates the setup of local directories and the validation of requirements.
./scripts/docker-dev.sh start: Checks for Docker, creates volume directories, pulls images, and starts services../scripts/docker-dev.sh logs: Streams logs from all or specific services../scripts/docker-dev.sh destroy: Removes containers and deletes all persistent data in.docker/volumes/.
Sources: scripts/docker-dev.sh:40-68, scripts/docker-dev.sh:170-195
Build and Test Commands
Developers should use the following cargo commands within the workspace for various tasks:
# Full workspace build
cargo build
# Run specific crate tests with output visibility
cargo test -p cli -- --nocapture
# Linting with all features enabled
cargo clippy --all-features
# Formatting check
cargo fmt --all
Sources: AGENTS.md:12-40, README.md:136-139
API and Migration Execution
The horizon CLI is the entry point for starting the backend and applying schema changes.
The sequence shows how the CLI automatically reconciles database state before starting the API server.
Sources: crates/cli/src/main.rs:141-168, IMPLEMENTATION_PLAN.md:144-162
Configuration Validation
The CLI includes a validate command to ensure the environment is correctly configured before execution. It checks for the existence of critical variables:
HORIZON_DATABASE_HOSTHORIZON_DATABASE_PORTHORIZON_DATABASE_NAMEHORIZON_DATABASE_USERHORIZON_DATABASE_PASSWORD
Sources: crates/cli/src/main.rs:218-245
Frontend and Desktop Setup
The frontend is a React application that can be served as a web app or bundled into a desktop application via Tauri.
- Web Development: Managed via Vite. Running
bun run devinsidecrates/uistarts the development server athttp://localhost:1420. - Desktop Development: Managed via the Tauri CLI. The configuration defines the
productNameas "horizon" and usesbun run buildas the pre-build command.
Sources: crates/ui/package.json:6-11, crates/ui/src-tauri/tauri.conf.json:7-13, IMPLEMENTATION_PLAN.md:1044-1050
Summary
The Horizon development setup provides a robust foundation for building a modern CMDB. By utilizing containerized databases (Postgres and Redis) alongside a comprehensive Rust CLI, developers can manage the entire stack from schema migrations to API serving with minimal manual intervention. The integration of Docker-based service orchestration and strict versioning policies ensures environment parity across the development lifecycle.
Sources: IMPLEMENTATION_PLAN.md:1181-1195, README.md:145-155