// TUTORIAL & INSTALLATION

Get Started with Dimensigon

Step-by-step installation guide and hands-on practice exercises to master distributed automation.

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)
CPython 3.9.23 with development headers, in a disposable lab
An administrator with root access for system setup; the new automation account needs no administrative grant
Docker (optional, for multi-node training environment)
Basic shell scripting knowledge

Phase 1: System Preparation

Step 1: Install Dependencies

# Start an administrator root shell. Remain here between installation phases.
$ sudo -i

# Update system
$ apt-get update -y

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

# Provision CPython 3.9.23 and matching headers from your lab image.
# This legacy runtime is for disposable documentation labs.
$ python3.9 --version
# Continue only when the interpreter reports Python 3.9.23.

# Install firewall tools
$ apt-get install firewalld

What This Does

libffi-dev, libssl-dev: Required by cryptography packages
autoconf, build-essential: Compile native extensions
CPython 3.9.23: the tested documentation runtime
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 separates automation from your personal files
Virtual environment isolates dependencies
Proper sudoers config enables automation
Explicit activation after each login-shell transition

Step 2: Create User & venv

# As the administrator in the root shell from Phase 1
$ useradd -s /bin/bash -m dimensigon

# Switch to dimensigon user
$ su - dimensigon

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

# Activate for this lab shell
$ source ~/venv/bin/activate

# Pin packaging tools inside this virtual environment
$ python -m pip install 'pip==23.0.1' 'setuptools==58.1.0' 'wheel==0.45.1'

# Return to the administrator root shell before Phase 3
$ exit

Phase 3: Optional Administrator-Only Sudoers Configuration

Step 3: Edit /etc/sudoers

# As the administrator root shell; skip this phase for the greeting lab
$ visudo

# Add these lines at the end:
# Dimensigon - DM Core
# Optional isolated-lab rule only; no sudo is needed for the greeting fixture.
# dimensigon ALL=(ALL) NOPASSWD:ALL
# Production alternative: allow only an operator-owned, no-argument wrapper.
dimensigon ALL=(root) NOPASSWD: /usr/local/sbin/dm-check-nginx ""
Defaults:dimensigon !requiretty

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

# Verify configuration
$ visudo -c
$ sudo -l -U dimensigon

Sudoers Configuration

ALL=(ALL) NOPASSWD:ALL - Run any command without password
!requiretty - Allow remote command execution
Not required for the first-success examples
Always use visudo to edit safely

Administrator responsibility: The automation account cannot run visudo. Skip this phase for the first-success examples. For the optional restricted rule, first install a root-owned, non-writable wrapper at /usr/local/sbin/dm-check-nginx that rejects all arguments and runs only /usr/sbin/nginx -t. Review the exact path for your OS; grant no shell or service restart.

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
Initialize only disposable lab nodes after installation
Check pip show dimensigon for version

Step 4: Install Dimensigon Package

# From the administrator root shell, enter a fresh automation login shell
$ su - dimensigon

# Login shells do not retain activation from Phase 2
$ source ~/venv/bin/activate
$ python -m pip --version

# Download the published pins into this account's home, then install
$ curl --fail --show-error --location --output product-requirements.txt https://dimensigon.com/product-requirements.txt
$ python -m pip install -r product-requirements.txt

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

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

# Return to the administrator; use a new lab terminal for Phase 5
$ exit

Phase 5: Initialize First Dimension (Master Node)

Step 5: Create New Dimension

# Only run this once on the first node
$ su - dimensigon
$ source ~/venv/bin/activate
$ dimensigon new

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

# Start Dimensigon in foreground
$ dimensigon

# Or as daemon
$ dimensigon --help
# For supervised operation, use your lab service manager; 0.3.5 has no --daemon flag.

# 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

# In a new administrator terminal on the FIRST/MASTER lab node
$ su - dimensigon
$ source ~/venv/bin/activate
$ dimensigon token --expire-time 15
Generated token: <your expiring lab token>

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

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

# 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> ping node-2
SUCCESS: Response time 12ms

# View cluster topology
root.dshell> status --detail

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 the disposable lab library
root.dshell> software add hello-script 1 /tmp/my-script.sh --family demos
root.dshell> software list --name hello-script --detail

# Substitute the returned software UUID and lab destination UUIDs.
root.dshell> software send SOFTWARE_ID LAB_NODE_ID --dest_path /tmp/ --foreground

# Send to each lab node explicitly; 0.3.5 has no --broadcast option.
root.dshell> software send SOFTWARE_ID LAB_NODE_2_ID --dest_path /tmp/ --foreground

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
The tested first workflow invokes the lab Python interpreter through a shell action
Built-in variable substitution
Vault secret injection

Exercise 2: Hello World Orchestration

# Documentation baseline: Dimensigon 0.3.5, Python 3.9
# Non-destructive first-success fixture
cat > hello-world.json <<'EOF'
{
  "name": "hello-world",
  "stop_on_error": true,
  "steps": [
    {
      "id": "1",
      "undo": false,
      "name": "greeting",
      "action_type": "SHELL",
      "code": "printf \"Hello from Dimensigon\\n\"",
      "expected_rc": 0,
      "target": "all",
      "parent_step_ids": []
    },
    {
      "id": "2",
      "undo": false,
      "name": "python-greeting",
      "action_type": "SHELL",
      "code": "python3.9 -c \"print('Step 2 executed')\"",
      "target": "all",
      "parent_step_ids": [
        "1"
      ],
      "expected_rc": 0
    }
  ]
}
EOF

# Batch import (run inside your synthetic lab)
dshell orch create hello-world.json
# Obtain its ID with the supported batch list command
dshell orch list --name hello-world --detail
# Substitute the returned orchestration ID and your lab node name
dshell orch run ORCHESTRATION_ID --target all=LAB_NODE

📦

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

Reviewed examples and runtime

The documentation contract is Dimensigon 0.3.5 on Python 3.9. The package declares Python ≥3.6; this guide uses one explicit test baseline. These are lab instructions. Use a separate virtual environment and synthetic data.

Install using the pinned documentation requirements. Import hello-world.json first. Then review variable substitution (input.visitor) and rollback in a disposable lab. The rollback fixture intentionally fails its second step and removes only the marker it created. Its first step refuses to overwrite an existing marker; undo after failed creation preserves that file. Native PYTHON is an import type in 0.3.5 but has no execution factory in that release, so the tested example invokes python3.9 through SHELL.

# In a disposable lab, download both examples from the links above.
# Import rollback, list it, and use its returned ID below.
dshell orch create lab-rollback.json
dshell orch list --name lab-rollback --detail
# Make a fresh synthetic directory; retain its path for inspection after failure.
lab_directory=$(mktemp -d /tmp/dm-tutorial-XXXXXXXX)
dshell orch run ORCHESTRATION_ID --target all=LAB_NODE --param "lab_directory:$lab_directory"
# Expected: step 2 fails, undo removes marker, directory remains empty.
# For substitution, embed greet-visitor as an inline step or action-template
# reference in a lab workflow, then run with --param visitor:Ada.