console

Console

Disclaimer: Production viable releases are tagged and listed under 'Releases'. Console is under development. The current available tags for download are Alpha version code and should not be used in production. For these Alpha tags, certain features may not function yet, visual look and feel may change, or bugs/errors may occur. Follow along our Feature Backlog for future releases and feature updates.

Redfish (Tech Preview): Console's DMTF Redfish API (/redfish/v1) is available as a tech preview in prerelease builds tagged -redfish-preview (for example, v1.46.0-redfish-preview.1) under Releases. Tech-preview features are not production ready, and their API and behavior may change without notice.

Overview

Console is an application that provides a 1:1, direct connection for AMT devices for use in an enterprise environment. Users can add activated AMT devices to access device information and device management functionality such as power control, remote keyboard-video-mouse (KVM) control, and more.

Quick Start for Users

1. Download Console

1. Visit the latest release page
2. Download the appropriate binary for your operating system and architecture from the Assets section

2. Run Console

Linux/macOS

# Navigate to your download directory
cd <path-to-your-download>

# Extract the archive (example for Linux x64)
tar -xzf console_linux_x64.tar.gz

# Make the binary executable
chmod +x console_linux_x64

# Run Console
./console_linux_x64

Windows

# Simply double-click the downloaded executable to run
console_windows_x64.exe

Or run from Command Prompt:

console_windows_x64.exe

3. First Run Setup

On first startup, you'll see:

Warning: Key Not Found, Generate new key? Y/N

Simply type Y and press Enter - this generates the necessary encryption keys for secure operation.

Linux Users: If you encounter "Object does not exist at path '/'" after answering 'Y', this indicates your system lacks a keychain service. Install a keychain manager (like seahorse) and restart Console binary.

For Developers

Development Environment

You’ll run two components during development:

• Console – the backend service (Go Service)
• Web UI – the frontend (for the Angular Web UI)

Local development can be done on Linux, macOS, and Windows. On Windows, WSL is recommended if you plan to use make, but it’s not required for running Console directly.

Prerequisites

Before you begin, ensure you have:

• Go 1.27+
• Git
• Node.js & npm (for the Web UI)
• Docker & Docker Compose (optional, for PostgreSQL)

1. Clone and Configure Console

# Clone Console
git clone https://github.com/device-management-toolkit/console.git
cd console

# Copy env template
cp .env.example .env

Edit .env as needed. For local dev, set:

GIN_MODE=debug
# DB_URL=postgres://postgresadmin:admin123@localhost:5432/rpsdb  # uncomment for Postgres

2. Configure Backend for Development

For local development with a separate UI, configure config/config.yml to point to your frontend:

ui:
  externalUrl: "http://localhost:4200"

This tells the backend to redirect UI requests to the separately running frontend application.

3. Running the Backend

Important: For development, use the console-noui binary or build with the noui tag. This allows the backend to work with a separately running frontend without embedding UI files.

Option A: SQLite (default, easiest)

# Install dependencies
go mod tidy && go mod download

# Run Console with noui tag
go run -tags=noui ./cmd/app/main.go

# OR use the pre-built noui binary
./bin/console-noui -config ./config/config.yml

First run: When prompted with Warning: Key Not Found, Generate new key? Y/N, type Y and press Enter.

Custom Config: You can specify a custom configuration file:

go run -tags=noui ./cmd/app/main.go --config "/absolute/path/to/config.yml"

Database Location: SQLite database is automatically created at:

• Linux/macOS: ~/.config/device-management-toolkit/console.db
• Windows: %APPDATA%\device-management-toolkit\console.db

Option B: PostgreSQL

# Start Postgres via Docker
make compose-up

# Run Console with database migrations (noui)
make run-noui

This will use the DB_URL you configured in .env.

4. Build Options

Console supports multiple build configurations optimized for different use cases:

Default Build

• Full build with embedded web UI
• Ideal for development and single-instance deployments

noui Build (Headless/API-only)

• Excludes embedded web UI from binary
• Reduces binary size by ~30MB
• All API endpoints remain fully functional
• Health checks, metrics, and API docs still available
• Optional: Configure ui.externalUrl in config.yml to redirect UI requests to separately hosted frontend
• Ideal for microservice architectures or when using a separate UI deployment

Configuration for headless builds:

Edit config.yml:

ui:
  # Redirect UI requests to external frontend (optional)
  # If empty: UI requests return 404
  # If set: UI requests redirect to this URL
  externalUrl: "https://your-ui-domain.com"

Or use environment variable:

UI_EXTERNAL_URL=https://your-ui-domain.com ./console-noui

Build commands:

# Default build (with UI) for current platform
make build

# Headless build (no UI) for current platform
make build-noui

# Cross-compile for all platforms (Linux, Windows, macOS)
# Produces binaries in dist/ directory for distribution
make build-all-platforms

Manual build examples:

# Build for current platform
go build -o console ./cmd/app
go build -tags=noui -o console-noui ./cmd/app

# Cross-compilation examples (CGO_ENABLED=0 produces static binaries)
# Linux
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o console-linux ./cmd/app
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -tags=noui -o console-linux-headless ./cmd/app

# Windows
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o console.exe ./cmd/app
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -tags=noui -o console-headless.exe ./cmd/app

# macOS
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -o console-macos ./cmd/app
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -tags=noui -o console-macos-headless ./cmd/app

Note: With CGO_ENABLED=0, Go produces statically-linked binaries that are cross-platform compatible. You can build binaries for any target platform from any development machine.

5. Running the Frontend

# Clone Sample Web UI
git clone https://github.com/device-management-toolkit/sample-web-ui
cd sample-web-ui

# Install dependencies
npm install

# Build and run
npm run enterprise

Check the output of npm run enterprise to verify the port (default is 4200), then open the UI in your browser at:

http://localhost:4200

Architecture and Documentation

Before contributing code changes, familiarize yourself with:

• Console Architecture Overview
• Console Data Storage Documentation

OpenAPI Documentation

Console exposes the OpenAPI specification two ways:

1. Live HTTP endpoint (always available when the server runs):

   • http://localhost:8181/api/openapi.json

2. Regenerate doc/openapi.json on disk (used by CI to publish to SwaggerHub):

   make openapi
   

   Equivalent to go run ./cmd/openapi-gen — a standalone binary that writes doc/openapi.json and exits without starting the server.

3. To add API Documentation: Check wiki https://github.com/device-management-toolkit/console/wiki/API-Documentation-to-Console

Dev tips for passing CI Checks

• Install gofumpt go install mvdan.cc/gofumpt@latest (replaces gofmt)
• Install gci go install github.com/daixiang0/gci@latest (organizes imports)
• Ensure code is formatted correctly with gofumpt -l -w -extra ./
• Ensure all unit tests pass with go test ./...
• Ensure code has been linted with:
  • Windows: docker run --rm --pull always -v ${pwd}:/app -w /app golangci/golangci-lint:latest golangci-lint run --config=./.golangci.yml -v
  • Unix: docker run --rm --pull always -v .:/app -w /app golangci/golangci-lint:latest golangci-lint run --config=./.golangci.yml -v

Fuzz Testing

Console includes Go fuzz tests across multiple packages and targets. For full coverage details, seed corpus strategy, and CI guidance, see wiki: Fuzz Testing

Prerequisite

The Makefile includes .env, so ensure it exists before running make commands:

cp .env.example .env

List all fuzz targets

make fuzz-list

Output format:

./internal/usecase/devices FuzzParseInterval
./internal/entity/dto/v1 FuzzDeviceJSONProcessing
...

Run a single fuzz target (recommended local workflow)

Go fuzzing runs one fuzz target at a time. Use fuzz-one for focused debugging and development:

make fuzz-one PKG=./internal/usecase/devices TARGET=FuzzParseInterval FUZZTIME=30s

Run a quick all-target smoke pass

Runs each fuzz target once (-fuzztime=1x):

make fuzz-smoke

Run all fuzz targets with time budget per target

make fuzz-all FUZZTIME=2m

This executes all discovered fuzz targets sequentially and is suitable for scheduled CI jobs.

Additional Resources

• For detailed documentation and Getting Started, visit the docs site.

• Find a bug? Or have ideas for new features? Open a new Issue.

• Need additional support or want to get the latest news and events about Device Management Toolkit? Connect with the team directly through Discord.