Quick Start Guide

Get SysManage up and running in minutes with Docker Compose. Perfect for evaluation, development, and small-scale deployments.

Overview

This quick start guide will have you running SysManage in under 10 minutes using Docker Compose. This method provides a complete, self-contained SysManage installation perfect for testing, development, or small production environments.

⏱️ 5-10 min

Setup Time

🐳 Docker

Requirements

🖥️ 1 Server

Infrastructure

📊 Full Features

Functionality

Prerequisites

System Requirements

Linux server or VM with 4GB RAM minimum (8GB recommended)
2 CPU cores minimum (4+ recommended)
20GB available disk space (50GB+ recommended)
Network access on ports 80, 443, and 8443

Software Requirements

Docker Engine 20.10+ installed
Docker Compose 2.0+ installed
Git (for cloning the repository)
Administrative/sudo access

Network Requirements

Internet access for downloading Docker images
Firewall configured to allow inbound connections
Static IP or DNS name (recommended)

Installing Docker (if needed)

If you don't have Docker installed, here are quick installation commands for common platforms:

Ubuntu/Debian

# Update package index
sudo apt update

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt install docker-compose-plugin

# Verify installation
docker --version
docker compose version

RHEL/CentOS/Fedora

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Start and enable Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo dnf install docker-compose-plugin

# Verify installation
docker --version
docker compose version

Installation Steps

Clone the Repository

Clone the SysManage repository to get the Docker Compose configuration:

# Clone the repository
git clone https://github.com/bceverly/sysmanage.git
cd sysmanage

# Switch to the latest stable release (recommended)
git checkout main

Note: The main branch contains the latest stable release. Use specific version tags for production deployments.

Configure Environment

Copy and customize the environment configuration:

# Copy the example environment file
cp .env.example .env

# Edit the configuration (optional for quick start)
nano .env

Key Configuration Options

Setting	Default	Description
`POSTGRES_PASSWORD`	sysmanage	Database password (change for production)
`SECRET_KEY`	auto-generated	Application secret key
`LISTEN_PORT`	8443	Web interface port
`DOMAIN_NAME`	localhost	Server domain name or IP

For Quick Start: The default configuration works fine for testing. You can start with defaults and modify later.

Generate SSL Certificates

SysManage requires SSL certificates for secure communication. Generate self-signed certificates for testing:

# Create SSL directory
mkdir -p ssl

# Generate self-signed certificate (valid for 365 days)
openssl req -x509 -newkey rsa:4096 -keyout ssl/server.key -out ssl/server.crt \
    -days 365 -nodes -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost"

# Set proper permissions
chmod 600 ssl/server.key
chmod 644 ssl/server.crt

Production Note: Use proper SSL certificates from a trusted CA for production deployments. Let's Encrypt certificates work well with SysManage.

Start SysManage

Use Docker Compose to start all SysManage services:

# Start SysManage in detached mode
docker compose up -d

# Check that all services are running
docker compose ps

# View logs if needed
docker compose logs -f

You should see output similar to:

✅ Container sysmanage-postgres-1  Started
✅ Container sysmanage-redis-1     Started
✅ Container sysmanage-backend-1   Started
✅ Container sysmanage-worker-1    Started
✅ Container sysmanage-nginx-1     Started

Create Admin User

Create your first administrator account:

# Create admin user
docker compose exec backend python manage.py create-admin

# Follow the prompts to set:
# - Username (e.g., admin)
# - Email address
# - Password (choose a strong password)

Security: Choose a strong password for the admin account. You can create additional users later through the web interface.

Access the Web Interface

Open your web browser and navigate to SysManage:

# Local access
https://localhost:8443

# Remote access (replace with your server's IP)
https://your-server-ip:8443

Certificate Warning: Since we're using self-signed certificates, your browser will show a security warning. This is expected for the quick start setup. Click "Advanced" and "Proceed to localhost" to continue.

Verify Installation

Health Checks

Verify that all components are working correctly:

1. Service Status

# Check all containers are running
docker compose ps

# Should show all services as "Up"

2. API Health Check

# Test the API endpoint
curl -k https://localhost:8443/api/health

# Should return: {"status": "healthy"}

3. Database Connection

# Check database connectivity
docker compose exec backend python manage.py check --database default

# Should show: System check identified no issues

4. Web Interface

Login page loads correctly
Can authenticate with admin credentials
Dashboard displays without errors
Navigation menu is functional

Quick Troubleshooting

Container Won't Start

# Check container logs
docker compose logs [service-name]

# Common services: backend, postgres, redis, nginx

Can't Access Web Interface

Check firewall settings allow port 8443
Verify Docker port mapping: docker compose ps
Try accessing via HTTP first: http://localhost:8080

SSL Certificate Issues

# Regenerate certificates if needed
rm ssl/*
openssl req -x509 -newkey rsa:4096 -keyout ssl/server.key -out ssl/server.crt \
    -days 365 -nodes -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost"

# Restart nginx
docker compose restart nginx

Next Steps

🌐 Explore the Interface

Get familiar with the SysManage web interface and its features.

Web Interface Tour →

🤖 Install Your First Agent

Add monitoring agents to your hosts to start collecting data.

Agent Installation →

⚙️ Basic Management

Learn essential management tasks and workflows.

Management Basics →

🏗️ Production Deployment

Scale up to a production-ready deployment with HA and security.

Production Setup →

Common Post-Installation Tasks

Configure Email Notifications

Set up email settings for alerts and notifications:

Navigate to Settings → Email Configuration
Enter SMTP server details
Test email delivery
Configure alert notifications

Create Additional Users

Add team members with appropriate permissions:

Go to Administration → Users
Click "Create User"
Set username, email, and role
Configure permissions as needed

Set Up Host Groups

Organize your infrastructure logically:

Navigate to Hosts → Groups
Create groups by environment, function, or location
Set group-specific permissions
Configure group-based monitoring

Configure Monitoring Thresholds

Set up alerting for your environment:

Go to Monitoring → Alerts
Create alert rules for CPU, memory, disk
Set appropriate thresholds
Test alert delivery

Useful Commands

Docker Compose Operations

# Start services
docker compose up -d

# Stop services
docker compose down

# View logs
docker compose logs -f [service-name]

# Restart a service
docker compose restart [service-name]

# Update to latest images
docker compose pull
docker compose up -d

# View resource usage
docker compose top

Backup and Maintenance

# Backup database
docker compose exec postgres pg_dump -U sysmanage sysmanage > backup.sql

# Backup configuration
tar -czf config-backup.tar.gz .env ssl/ docker-compose.yml

# View system status
docker compose exec backend python manage.py health_check

# Update admin password
docker compose exec backend python manage.py change_password admin

Log Management

# View application logs
docker compose logs backend

# View nginx access logs
docker compose logs nginx

# Follow logs in real-time
docker compose logs -f --tail=100

# Clear log files (if they get too large)
docker compose exec backend truncate -s 0 /var/log/sysmanage/*.log