Tutorial - Dimensigon

Target Audience & Prerequisites

This tutorial is for DevOps engineers, system administrators, and infrastructure teams who want to set up Dimensigon from scratch and practice distributed orchestration. You'll need:

Linux system (Ubuntu, CentOS, or similar)
Python 3.6 or newer
Sudo access or ability to configure sudoers
Docker (optional, for multi-node training environment)
Basic shell scripting knowledge

Phase 1: System Preparation

Step 1: Install Dependencies

# Update system
$ apt-get update -y

# Install build tools
$ apt-get install -y libffi-dev libssl-dev \
  autoconf build-essential python3-wheel

# Setup Python 3.6+ (if not available)
$ apt-get install -y software-properties-common
$ add-apt-repository -y ppa:deadsnakes/ppa
$ apt-get update && apt-get install -y \
  python3.6 python3.6-dev python3.6-venv python3-pip

# Install firewall tools
$ apt-get install firewalld

What This Does

libffi-dev, libssl-dev: Required by cryptography packages
autoconf, build-essential: Compile native extensions
Python 3.6+: Dimensigon's minimum requirement
firewalld: Manage network security rules

Note: For lightweight containers, also install sudo vim for editing.

Phase 2: Create Dimensigon User & Environment

Virtual Environment Setup

Create a dedicated system user and isolated Python environment:

Dedicated user prevents privilege escalation
Virtual environment isolates dependencies
Proper sudoers config enables automation
Profile activation at login

Step 2: Create User & venv

# Create dimensigon user
$ useradd -s /bin/bash -m dimensigon

# Switch to dimensigon user
$ su - dimensigon

# Create virtual environment
$ python3 -m venv --prompt dimensigon venv

# Activate on login
$ echo 'source ~/venv/bin/activate' >> .bash_profile

# Install Python prerequisites
$ pip install wheel setuptools_rust
$ pip install --upgrade pip
$ pip install pyperclip  # For DShell

Phase 3: Configure Sudoers

Step 3: Edit /etc/sudoers

# Edit sudoers file safely
$ sudo visudo

# Add these lines at the end:
# Dimensigon - DM Core
dimensigon ALL=(ALL) NOPASSWD:ALL
Defaults:dimensigon !requiretty

# Save and exit (Ctrl+X then Y then Enter in nano)

# Verify configuration
$ sudo -l -U dimensigon

Sudoers Configuration

ALL=(ALL) NOPASSWD:ALL - Run any command without password
!requiretty - Allow remote command execution
Essential for Dimensigon's distributed operations
Always use visudo to edit safely

Security: Only use NOPASSWD in isolated lab environments. Restrict in production.

Phase 4: Install Dimensigon

Package Installation

The Dimensigon Python package includes both DM Core and DShell:

Single pip install provides all components
Automatically configures dependencies
Ready for immediate use
Check pip show dimensigon for version

Step 4: Install Dimensigon Package

# Switch to dimensigon user if not already
$ su - dimensigon

# Install from PyPI
$ pip install dimensigon

# Verify installation
$ dimensigon --version
$ dshell --version

# Get help on any command
$ dimensigon -h
$ dshell -h

Phase 5: Initialize First Dimension (Master Node)

Step 5: Create New Dimension

# Only run this once on the first node
$ su - dimensigon
$ dimensigon new

# Verify successful initialization
$ ls -la ~/.dimensigon/

# Start Dimensigon in foreground
$ dimensigon

# Or as daemon
$ dimensigon --daemon

# Check logs
$ tail -f ~/.dimensigon/logs/dimensigon.log

Dimension Creation

A Dimension is a logical cluster of servers
Only one node creates it initially with dimensigon new
Other nodes join using dimensigon join
Stored in ~/.dimensigon/ directory

Watch for successful startup message: "Dimensigon running on port 20194"

Phase 6: Add Additional Nodes (Multi-Node Setup)

Token-Based Joining

Generate tokens on the master, then use them to join new nodes:

Tokens expire after 15 minutes (configurable)
One token = one node join
Available via CLI or DShell
Enables secure cluster growth

Step 6: Join Additional Nodes

# On FIRST/MASTER node, generate token
$ su - dimensigon
$ dimensigon token
Generated token: abc123def456ghi789jkl

# Or via DShell
$ dshell
root.dshell> manager token

# On ADDITIONAL nodes, repeat Steps 1-4
# Then join the dimension:
$ dimensigon join first-node abc123def456ghi789jkl

# Start the node
$ dimensigon

Phase 7: Verify Cluster Setup

Step 7: Verify Multi-Node Cluster

# List all servers in the dimension
$ dshell
root.dshell> server list

# Output:
Name           | Status  | Gates
node-1         | ONLINE  | 2
node-2         | ONLINE  | 2
node-3         | ONLINE  | 2

# Check network connectivity
root.dshell> server ping -n node-2
SUCCESS: Response time 12ms

# View cluster topology
root.dshell> manager status

Healthy Cluster Indicators

All nodes show ONLINE status
Each node has 2+ Gates (network endpoints)
Ping responses under 50ms
No "split brain" warnings

If a node shows OFFLINE, check network connectivity and firewall rules.

Hands-On Practice: Software Distribution

Exercise 1: Distribute Software

# Create test software file
$ echo "#!/bin/bash" > /tmp/my-script.sh
$ echo "echo 'Hello from node'" >> /tmp/my-script.sh
$ chmod +x /tmp/my-script.sh

# Register software in library
root.dshell> software add /tmp/my-script.sh \
  -name "hello-script" -family "demos"

# Send to specific node
root.dshell> software send \
  -name "hello-script" -dest /opt/scripts/ -n node-2

# Send to all nodes
root.dshell> software send \
  -name "hello-script" -dest /opt/scripts/ --broadcast

Software Distribution Benefits

No direct connectivity between nodes required
Transfers through mesh automatically
Tracks transfer status and progress
Perfect for deploying scripts, binaries, configs

Hands-On Practice: Create Your First Orchestration

Orchestration Creation

Define a multi-step workflow that executes across your cluster:

Steps execute sequentially or in parallel
Support shell, Python, HTTP, or nested orchestrations
Built-in variable substitution
Vault secret injection

Exercise 2: Hello World Orchestration

# Create orchestration JSON
$ cat > hello-world.json <<'EOF'
{
  "name": "hello-world",
  "version": 1,
  "steps": [
    {
      "name": "step-1",
      "action_type": "shell",
      "code": "echo 'Hello from {{server_name}}'"
    },
    {
      "name": "step-2",
      "action_type": "python",
      "code": "print('Step 2 executed')"
    }
  ]
}
EOF

# Upload orchestration
root.dshell> orch create hello-world \
  -file hello-world.json

# Execute on specific node
root.dshell> orch run -n hello-world \
  --node node-1

# Monitor execution
root.dshell> orch execution list -n hello-world

📦

Complete Setup

From bare OS to running distributed cluster in 7 phases.

🔧

Hands-On Exercises

Practice software distribution, orchestrations, and cluster management.

📖

Troubleshooting Guide

Common issues and solutions for each installation phase.

🎓

Progression Levels

Start with basics, progress to advanced multi-node scenarios.

DShell Reference Guide Back to Home

Get Started with Dimensigon