Operations on Rackd

Deployment Guide

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

This guide covers various deployment methods for Rackd in production environments.

Docker Deployment

Basic Docker Run

# Create data directory
mkdir -p /opt/rackd/data

# Run container
docker run -d \
 --name rackd \
 -p 8080:8080 \
 -v /opt/rackd/data:/data \
 -e DATA_DIR=/data \
 ghcr.io/martinsuchenak/rackd:latest

Docker with Environment Variables

docker run -d \
 --name rackd \
 -p 8080:8080 \
 -v /opt/rackd/data:/data \
 -e DATA_DIR=/data \
 -e LOG_LEVEL=info \
 -e LOG_FORMAT=json \
 -e ENCRYPTION_KEY=your-64-hex-char-key \
 -e INITIAL_ADMIN_USERNAME=admin \
 -e INITIAL_ADMIN_PASSWORD=your-secure-password \
 ghcr.io/martinsuchenak/rackd:latest

Docker Compose

Create docker-compose.yml:

Backup & Restore

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

This guide covers backup strategies, restore procedures, and data migration for Rackd.

SQLite Backup Strategies

1. File-Based Backup

The simplest approach is copying the SQLite database file:

# Stop Rackd service
systemctl stop rackd

# Copy database file
cp /var/lib/rackd/rackd.db /backup/rackd-$(date +%Y%m%d-%H%M%S).db

# Start Rackd service
systemctl start rackd

2. Online Backup (Recommended)

Use SQLite’s .backup command for consistent backups without stopping the service:

# Create backup while service is running
sqlite3 /var/lib/rackd/rackd.db ".backup /backup/rackd-$(date +%Y%m%d-%H%M%S).db"

3. WAL Mode Backup

If using WAL mode, backup both database and WAL files:

Security Hardening

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

Security considerations and hardening guide for production Rackd deployments.

Authentication

Rackd requires authentication on all API endpoints. Three methods are supported:

Session cookies (Web UI login)
API keys (Bearer token, tied to a user account)
OAuth 2.1 with PKCE (MCP clients)

See Authentication for details on each method.

Secure Defaults

Rackd ships with secure defaults for production use:

Setting	Default	Description
`COOKIE_SECURE`	`true`	Session cookies only sent over HTTPS
`RATE_LIMIT_ENABLED`	`true`	API rate limiting active
`RATE_LIMIT_REQUESTS`	`100`	100 requests per minute per IP
`LOGIN_RATE_LIMIT_REQUESTS`	`5`	5 login attempts per minute per IP

For local development without TLS, use --dev-mode which disables COOKIE_SECURE and RATE_LIMIT_ENABLED automatically.

Monitoring

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

Rackd provides comprehensive monitoring capabilities through Prometheus-compatible metrics, health checks, and structured logging.

Health Checks

Rackd exposes two health check endpoints for container orchestration and load balancers:

Liveness Probe (`/healthz`)

Simple endpoint that returns 200 OK if the application is running.

curl http://localhost:8080/healthz
# Response: ok

Use case: Kubernetes liveness probe to detect if the application needs to be restarted.

livenessProbe:
 httpGet:
 path: /healthz
 port: 8080
 initialDelaySeconds: 10
 periodSeconds: 30

Readiness Probe (`/readyz`)

Detailed endpoint that checks if the application is ready to serve traffic.

Rate Limiting

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

Rackd includes built-in rate limiting to prevent API abuse and ensure fair resource usage across clients.

Overview

Rate limiting is enabled by default (RATE_LIMIT_ENABLED=true). It tracks request rates per client IP and returns HTTP 429 (Too Many Requests) when limits are exceeded. Disable it with RATE_LIMIT_ENABLED=false for local development.

Configuration

Rate limiting is configured via environment variables:

# Rate limiting (enabled by default)
RATE_LIMIT_ENABLED=true

# Maximum requests per window (default: 100)
RATE_LIMIT_REQUESTS=100

# Time window for rate limiting (default: 1m)
RATE_LIMIT_WINDOW=1m

Example Configurations

Strict limits for public API:

Audit Logging

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

Rackd includes comprehensive audit logging to track all changes for compliance, security, and troubleshooting.

Overview

The audit trail captures all mutating API operations with full context including user, IP address, resource details, and changes. This provides accountability, compliance support, and troubleshooting capabilities.

Key Features:

Automatic capture of all API changes
User and IP address tracking
Request body capture for change details
Flexible filtering and querying
Export to JSON/CSV
Automatic retention management
Disabled by default (opt-in)

Configuration

Audit logging is configured via environment variables:

Troubleshooting

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

Common issues and solutions for Rackd.

Server Issues

Server Won’t Start

Port Already in Use

Symptom:

Error: listen tcp :8080: bind: address already in use

Solution:

# Find what's using the port
sudo lsof -i :8080
# or
sudo netstat -tulpn | grep :8080

# Kill the process
sudo kill <PID>

# Or use a different port
rackd server --listen-addr :8081

Permission Denied

Symptom:

Error: open /var/lib/rackd/rackd.db: permission denied

Solution:

Operations on Rackd

Deployment Guide

Docker Deployment

Basic Docker Run

Docker with Environment Variables

Docker Compose

Backup & Restore

SQLite Backup Strategies

1. File-Based Backup

2. Online Backup (Recommended)

3. WAL Mode Backup

Security Hardening

Authentication

Secure Defaults

Monitoring

Health Checks

Liveness Probe (/healthz)

Readiness Probe (/readyz)

Rate Limiting

Overview

Configuration

Example Configurations

Audit Logging

Overview

Configuration

Troubleshooting

Server Issues

Server Won’t Start

Port Already in Use

Permission Denied

Liveness Probe (`/healthz`)

Readiness Probe (`/readyz`)