usulnet Features Overview: Complete Docker Management Platform Guide

Managing Docker infrastructure at scale demands more than the CLI alone can offer. When you are overseeing dozens of containers across multiple servers, tracking resource usage, enforcing access controls, and coordinating deployments, a purpose-built management platform becomes essential. usulnet is a self-hosted Docker management platform designed precisely for this scenario: a single Go binary that replaces the complexity of Portainer and similar tools with a streamlined, security-first approach to container orchestration.

This guide walks through every major feature of usulnet, from the dashboard overview to advanced multi-node management, so you can evaluate whether it fits your infrastructure needs and understand how to leverage each capability effectively.

What Is usulnet?

usulnet is a self-hosted, open-source Docker management platform written in Go. It ships as a single binary with no external runtime dependencies beyond PostgreSQL and Redis, making deployment straightforward. Unlike cloud-hosted container management platforms, usulnet runs entirely within your infrastructure, giving you complete control over your data and access patterns.

The core design philosophy centers on three principles:

• Single-binary simplicity: No Java runtimes, no Node.js servers, no microservice sprawl. One binary, one config file, one deployment.
• Security by default: RBAC, encrypted secrets, auto-generated TLS certificates, and security scanning are built in, not bolted on.
• Multi-node from day one: usulnet's master-agent architecture supports managing containers across multiple servers from a single dashboard without requiring Docker Swarm or Kubernetes.

Dashboard Overview

The usulnet dashboard provides a real-time view of your entire Docker infrastructure. Upon login, you see aggregate metrics across all connected nodes:

The dashboard uses server-side rendering with HTMX for partial page updates, which means it works reliably even on slow connections without the overhead of a heavy JavaScript framework. Charts are rendered with Chart.js, and real-time updates arrive via WebSocket connections.

Container Management

Container lifecycle management is the core of usulnet. Every operation you can perform with docker CLI commands is available through the web interface, plus additional capabilities that the CLI does not natively offer.

Container Operations

From the container list view, you can perform all standard lifecycle operations:

# These CLI operations map directly to usulnet UI actions:
docker start <container>      # Start button
docker stop <container>       # Stop button (with configurable timeout)
docker restart <container>    # Restart button
docker pause <container>      # Pause button
docker kill <container>       # Kill button (sends SIGKILL)
docker rm <container>         # Remove button (with volume cleanup option)
docker logs <container>       # Integrated log viewer with search
docker exec -it <container>   # Web-based terminal (xterm.js)

The web terminal deserves special mention. usulnet embeds xterm.js with WebSocket connectivity, providing a fully interactive shell session directly in your browser. This eliminates the need to SSH into a server just to exec into a container, and it works seamlessly across all connected nodes.

Container Creation

Creating containers through usulnet's interface provides a structured form that covers all Docker run options:

• Image selection with tag autocomplete from connected registries
• Port mapping with protocol selection (TCP/UDP)
• Volume mounts (named volumes and bind mounts)
• Environment variables with secret reference support
• Network selection and alias configuration
• Resource limits (CPU, memory, PIDs)
• Restart policies
• Health check configuration
• Labels and annotations
• Security options (capabilities, read-only root filesystem, no-new-privileges)

Multi-Node Support

One of usulnet's defining features is its built-in multi-node architecture. Unlike Portainer, which requires separate agent installations and manages each environment somewhat independently, usulnet uses a purpose-built master-agent system connected via NATS messaging.

Architecture

The system operates in two modes:

1. Master mode: Runs the full usulnet server with web UI, API, database, and NATS gateway. This is your primary management interface.
2. Agent mode: A lightweight binary that connects to the master via NATS. It has no web UI and no database. It executes Docker operations on its local host and reports back to the master.

# Start the master (primary server)
usulnet serve --mode master

# Start an agent on a remote node
usulnet-agent --master-url nats://master.example.com:4222 \
  --node-name worker-01 \
  --token <enrollment-token>

Each agent maintains a persistent connection to the master and sends heartbeats every 10 seconds. If an agent disconnects, the master marks that node as unhealthy and displays an alert on the dashboard. When the agent reconnects, it automatically resynchronizes its container inventory.

Cross-Node Operations

From the master's web interface, you can perform any container operation on any connected node. The node selector in the UI lets you target specific nodes or view an aggregated list across all nodes. Operations include:

• Deploy containers to specific nodes based on resource availability
• Move or recreate containers across nodes
• Compare resource usage across nodes side by side
• View logs and exec into containers on any node from the master UI

Role-Based Access Control (RBAC)

usulnet enforces a three-tier RBAC model throughout the application:

RBAC is enforced at the middleware level in usulnet's Chi router, which means every API endpoint and web route is protected regardless of how the request arrives. JWT tokens carry the role claim, and the middleware validates it before the handler executes.

// usulnet's RBAC middleware chain (simplified)
r.Route("/api/v1/containers", func(r chi.Router) {
    r.Use(middleware.RequireAuth)
    r.Get("/", handler.ListContainers)          // Viewer+
    r.Get("/{id}", handler.GetContainer)         // Viewer+
    r.With(middleware.RequireOperator).Post("/", handler.CreateContainer)
    r.With(middleware.RequireOperator).Delete("/{id}", handler.DeleteContainer)
    r.With(middleware.RequireAdmin).Post("/{id}/privileged", handler.SetPrivileged)
})

Authentication supports multiple providers: local accounts with bcrypt-hashed passwords, LDAP/Active Directory integration, and OIDC for single sign-on with providers like Keycloak, Authentik, or Azure AD. Two-factor authentication via TOTP is available for all account types.

Monitoring and Metrics

usulnet provides built-in monitoring that covers both container-level and host-level metrics without requiring an external monitoring stack:

Container Metrics

• CPU usage (percentage and core-seconds)
• Memory usage, limit, and cache
• Network I/O (bytes sent/received per interface)
• Block I/O (reads/writes)
• PID count
• Restart count and uptime

Host Metrics

• CPU utilization per core
• Memory usage and swap
• Disk usage per mount point
• Network throughput per interface
• Docker daemon metrics (container count, image count, storage driver info)

For teams that already run Prometheus and Grafana, usulnet exposes a /metrics endpoint in Prometheus exposition format. A pre-built Grafana dashboard is included in the deploy/grafana/ directory that visualizes all usulnet metrics out of the box.

Integration note: usulnet also supports OpenTelemetry for distributed tracing, which is invaluable when debugging performance issues across multi-node deployments.

Secrets Management

Handling sensitive configuration in Docker environments is a common pain point. usulnet provides an integrated secrets management system that avoids the need for external tools like HashiCorp Vault for basic use cases.

Secrets in usulnet are:

• Encrypted at rest using AES-256-GCM in the PostgreSQL database
• Access-controlled via RBAC (only admins can create/modify secrets; operators can reference them)
• Injected at runtime as environment variables or Docker secrets, depending on the deployment mode
• Audit-logged so you know who accessed which secret and when

# Creating a secret via usulnet API
curl -X POST https://usulnet.example.com/api/v1/secrets \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "database_password",
    "value": "s3cur3-p@ssw0rd",
    "scope": "stack:myapp",
    "description": "Production database password"
  }'

# Referencing in a stack deployment
# usulnet resolves {{secret:database_password}} at deploy time
environment:
  DB_PASSWORD: "{{secret:database_password}}"

Deployment Workflows

usulnet supports multiple deployment approaches to fit different team workflows:

Docker Compose Stacks

The primary deployment method is Docker Compose stacks. usulnet's stack manager provides:

• A Monaco-based in-browser editor for Compose files with YAML validation
• Stack deployment, update, and teardown with rollback support
• Environment variable management per stack
• Git repository integration for GitOps-style deployments
• Webhook endpoints for CI/CD pipeline triggers

Git-Based Deployments

For teams practicing GitOps, usulnet can connect to Git repositories (with Gitea integration built in) and automatically deploy when changes are pushed:

# usulnet Git deployment configuration
repository: https://gitea.example.com/team/myapp.git
branch: main
compose_path: docker-compose.prod.yml
auto_deploy: true
webhook_secret: ${WEBHOOK_SECRET}
environment:
  - name: production
    vars_file: .env.production

Scheduled Deployments

usulnet's built-in scheduler (powered by robfig/cron) supports timed deployments, backup jobs, and maintenance tasks. You can schedule container restarts, image pulls, and cleanup operations from the UI.

Security Scanning

usulnet integrates with Trivy for automated vulnerability scanning of container images. Scans can be triggered manually, on image pull, or on a schedule:

• CVE detection with severity classification (Critical, High, Medium, Low)
• OS package and application dependency scanning
• Scan history and trend tracking
• Policy enforcement: block deployment of images with critical vulnerabilities

API Access

Every feature in usulnet is accessible via a RESTful API. The API uses JWT authentication and supports API key-based access for automation:

# List all containers across all nodes
curl -s https://usulnet.example.com/api/v1/containers \
  -H "Authorization: Bearer $TOKEN" | jq '.[] | {name, status, node}'

# Deploy a stack
curl -X POST https://usulnet.example.com/api/v1/stacks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "webapp",
    "compose": "version: \"3.8\"\nservices:\n  app:\n    image: myapp:latest\n    ports:\n      - \"8080:8080\"",
    "node": "worker-01"
  }'

# Get container resource usage
curl -s https://usulnet.example.com/api/v1/containers/{id}/stats \
  -H "Authorization: Bearer $TOKEN"

API documentation is served via an embedded Swagger UI at /api/docs, so you can explore and test endpoints interactively.

Comparison with Alternatives

Getting Started

The fastest way to deploy usulnet is with Docker Compose:

# Clone the repository
git clone https://github.com/fr4nsys/usulnet.git
cd usulnet

# Copy and configure environment
cp deploy/.env.example .env
# Edit .env with your database credentials and settings

# Start usulnet with all dependencies
docker compose -f deploy/docker-compose.prod.yml up -d

# Access the web UI
# HTTP:  http://localhost:8080
# HTTPS: https://localhost:7443 (auto-generated TLS)

For standalone binary installation:

# Download the latest release
curl -fsSL https://usulnet.com/install.sh | bash

# Or manually download and configure
wget https://github.com/fr4nsys/usulnet/releases/latest/download/usulnet-linux-amd64
chmod +x usulnet-linux-amd64
mv usulnet-linux-amd64 /usr/local/bin/usulnet

# Initialize configuration
usulnet config init

# Run database migrations
usulnet migrate up

# Start the server
usulnet serve

usulnet is designed to grow with your infrastructure. Start with a single node managing a handful of containers, and scale to dozens of nodes with hundreds of containers without changing your management workflow. The unified interface, built-in security features, and comprehensive API make it a compelling foundation for any Docker-based infrastructure.