Getting Started on Rackd

Installation

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers different methods to install and run Rackd.

System Requirements

Minimum Requirements

OS: Linux, macOS, or Windows
RAM: 256 MB
Disk: 100 MB (plus data storage)
CPU: Any modern CPU (x86_64 or ARM64)

Recommended Requirements

RAM: 512 MB or more
Disk: 1 GB or more for data
CPU: 2+ cores for discovery scanning

Installation Methods

1. Download Pre-built Binary (Recommended)

Download the latest release for your platform:

# Linux (x86_64)
curl -LO https://github.com/martinsuchenak/rackd/releases/latest/download/rackd-linux-amd64
chmod +x rackd-linux-amd64
sudo mv rackd-linux-amd64 /usr/local/bin/rackd

# Linux (ARM64)
curl -LO https://github.com/martinsuchenak/rackd/releases/latest/download/rackd-linux-arm64
chmod +x rackd-linux-arm64
sudo mv rackd-linux-arm64 /usr/local/bin/rackd

# macOS (Intel)
curl -LO https://github.com/martinsuchenak/rackd/releases/latest/download/rackd-darwin-amd64
chmod +x rackd-darwin-amd64
sudo mv rackd-darwin-amd64 /usr/local/bin/rackd

# macOS (Apple Silicon)
curl -LO https://github.com/martinsuchenak/rackd/releases/latest/download/rackd-darwin-arm64
chmod +x rackd-darwin-arm64
sudo mv rackd-darwin-arm64 /usr/local/bin/rackd

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/martinsuchenak/rackd/releases/latest/download/rackd-windows-amd64.exe" -OutFile "rackd.exe"

Verify installation:

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Get Rackd running in 5 minutes and perform essential operations.

1. Install and Start (1 minute)

# Download
curl -LO https://github.com/martinsuchenak/rackd/releases/latest/download/rackd-linux-amd64
chmod +x rackd-linux-amd64

# Bootstrap the first admin and start the server
export INITIAL_ADMIN_USERNAME=admin
export INITIAL_ADMIN_PASSWORD=your-secure-password
./rackd-linux-amd64 server

Open http://localhost:8080 and sign in with the admin credentials you set above — authentication is required for everything (the CLI too). For CLI convenience, create an API key in the web UI (Settings → API Keys) and export it:

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Rackd can be configured through environment variables. All configuration options have sensible defaults and can be overridden as needed.

Environment Variables

Server Options

Variable	Default	Description
`DATA_DIR`	`./data`	Directory for SQLite database and application data
`LISTEN_ADDR`	`:8080`	Address and port for the HTTP server (e.g., `:8080`, `127.0.0.1:3000`)

Security Options

Variable	Default	Description
`ENCRYPTION_KEY`	(empty)	64 hex chars (32 bytes). Encrypts stored SNMP/SSH credentials, DNS provider tokens and webhook secrets at rest. Generate with `openssl rand -hex 32`. Without it (outside `--dev-mode`) credential/DNS features are disabled
`INITIAL_ADMIN_USERNAME`	(empty)	Bootstrap admin username, applied only when the database has no users
`INITIAL_ADMIN_PASSWORD`	(empty)	Bootstrap admin password (min 8 characters)
`INITIAL_ADMIN_EMAIL`	`admin@localhost`	Bootstrap admin email
`COOKIE_SECURE`	`true`	Send session cookies only over HTTPS. Set to `false` for local dev without TLS
`SESSION_TTL`	`24h`	Duration for which a user session is valid
`SESSION_STORE_TYPE`	`sqlite`	The backend storage for sessions (`sqlite`, `valkey`, `redis`)
`VALKEY_URL`	`redis://localhost:6379/0`	The URL for Valkey/Redis if `SESSION_STORE_TYPE` is `valkey` or `redis`
`TRUST_PROXY`	`false`	Honor `X-Forwarded-For` / `X-Real-IP` headers from reverse proxies (rate limiting, audit logging)
`TRUSTED_PROXIES`	(empty)	Comma-separated IPs/CIDRs of trusted reverse proxies. Required when `TRUST_PROXY=true`: forwarded headers are honored only from these peers, otherwise ignored (fail-closed)
`SSRF_ALLOW_PRIVATE_TARGETS`	`false`	Allow webhook and DNS provider endpoints on private ranges (RFC1918/CGNAT/ULA) for intentional internal integrations. Loopback, link-local (cloud metadata) and multicast are always blocked

Rate Limiting Options

Variable	Default	Description
`RATE_LIMIT_ENABLED`	`true`	Enable API rate limiting. Set to `false` to disable for local dev
`RATE_LIMIT_REQUESTS`	`100`	Maximum requests per window
`RATE_LIMIT_WINDOW`	`1m`	Time window for rate limiting (Go duration format)

See Rate Limiting for detailed documentation.

Configuration Reference

Mon, 01 Jan 0001 00:00:00 +0000

All configuration is done via environment variables. Variables can be set directly or loaded from a .env file in the working directory.

Use --dev-mode flag on rackd server to automatically disable COOKIE_SECURE and RATE_LIMIT_ENABLED for local development.

Server

Variable	Type	Default	Description
`DATA_DIR`	string	`./data`	Directory for SQLite database and data files
`LISTEN_ADDR`	string	`:8080`	Address and port to listen on
`REQUEST_TIMEOUT`	duration	`30s`	HTTP request timeout
`LOG_FORMAT`	string	`text`	Log format: `text` or `json`
`LOG_LEVEL`	string	`info`	Log level: `trace`, `debug`, `info`, `warn`, `error`

Security

Variable	Type	Default	Description
`ENCRYPTION_KEY`	string	(empty)	64 hex chars (32 bytes). Encrypts stored SNMP/SSH credentials, DNS provider tokens and webhook signing secrets at rest. Generate with `openssl rand -hex 32`. Without it (outside `--dev-mode`) the credentials/DNS features are disabled; with `--dev-mode` a random non-persistent key is used. Rotate with `rackd credentials rotate-key`
`COOKIE_SECURE`	bool	`true`	Set `Secure` flag on session cookies (requires HTTPS). Disable for local dev without TLS
`RATE_LIMIT_ENABLED`	bool	`true`	Enable API rate limiting
`RATE_LIMIT_REQUESTS`	int	`100`	Max requests per window per IP
`RATE_LIMIT_WINDOW`	duration	`1m`	Rate limit sliding window
`LOGIN_RATE_LIMIT_REQUESTS`	int	`5`	Max login attempts per window per IP
`LOGIN_RATE_LIMIT_WINDOW`	duration	`1m`	Login rate limit sliding window
`TRUST_PROXY`	bool	`false`	Honor `X-Forwarded-For` / `X-Real-IP` headers when determining the client IP (rate limiting, audit logging)
`TRUSTED_PROXIES`	string	(empty)	Comma-separated IPs/CIDRs of trusted reverse proxies (e.g. `127.0.0.1,10.0.0.0/8`). Required when `TRUST_PROXY=true`: forwarded headers are honored only when the direct peer matches one of these networks, otherwise ignored (fail-closed)
`SSRF_ALLOW_PRIVATE_TARGETS`	bool	`false`	Permit webhook and DNS provider endpoints on private ranges (RFC1918/CGNAT/ULA) for intentional internal integrations. Loopback, link-local (cloud metadata) and multicast targets are always blocked

Sessions

Variable	Type	Default	Description
`SESSION_TTL`	duration	`24h`	Session expiry after last activity
`SESSION_STORE_TYPE`	string	`sqlite`	Session store backend: `sqlite` or `valkey`
`VALKEY_URL`	string	`redis://localhost:6379/0`	Valkey/Redis URL (when `SESSION_STORE_TYPE=valkey`)

Initial Admin

These are only used on first startup when no users exist.

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Rackd supports multiple authentication methods: user sessions (Web UI), API keys (REST API and MCP), and OAuth 2.1 with PKCE (MCP).

Overview

All API endpoints require authentication. There is no anonymous access mode. On first startup, create an admin user via environment variables (see Configuration Reference) or the bootstrap flow.

Authentication Methods

1. Session Authentication (Web UI)

The Web UI uses session-based authentication with secure cookies.

POST /api/auth/login
Content-Type: application/json

{"username": "admin", "password": "your-password"}

Session properties:

User Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Rackd supports user authentication via environment variable bootstrapping and password-based login.

Initial Admin User

On first startup, Rackd can create an initial admin user if you provide credentials via environment variables. This follows industry standards for containerized deployments.

Environment Variables

# Required
INITIAL_ADMIN_USERNAME=admin # Username for initial admin
INITIAL_ADMIN_PASSWORD=securepass # Password (min 8 characters)

# Optional
INITIAL_ADMIN_EMAIL=admin@example.com # Email (default: admin@localhost)
INITIAL_ADMIN_FULL_NAME="Admin User" # Full name (default: System Administrator)
SESSION_TTL=24h # Session timeout (default: 24h)
SESSION_STORE_TYPE=sqlite # Session store backend (sqlite, valkey)
VALKEY_URL=redis://localhost:6379/0 # Valkey/Redis URL if used

Docker Example

docker run -d \
 -e INITIAL_ADMIN_USERNAME=admin \
 -e INITIAL_ADMIN_PASSWORD=mySecurePassword123 \
 -e INITIAL_ADMIN_EMAIL=admin@example.com \
 -p 8080:8080 \
 rackd

Kubernetes Example

apiVersion: v1
kind: Secret
metadata:
 name: rackd-admin
type: Opaque
stringData:
 username: admin
 password: mySecurePassword123
---
apiVersion: v1
kind: Pod
metadata:
 name: rackd
spec:
 containers:
 - name: rackd
 image: rackd:latest
 env:
 - name: INITIAL_ADMIN_USERNAME
 valueFrom:
 secretKeyRef:
 name: rackd-admin
 key: username
 - name: INITIAL_ADMIN_PASSWORD
 valueFrom:
 secretKeyRef:
 name: rackd-admin
 key: password

Session Management

Session Tokens

After login, users receive a session token that must be included in the Authorization header: