Skip to content

Installation Guide

This guide covers installing Machineuse on your system.

System Requirements

Requirement Minimum Recommended
OS Ubuntu 20.04+ / Debian 11+ Ubuntu 22.04
CPU 2 cores 4+ cores
RAM 4 GB 8+ GB
Disk 20 GB 50+ GB
Python 3.11+ 3.11+

Prerequisites

  • systemd-nspawn support (for container runtime)
  • Root/sudo access for container management
  • Network connectivity between nodes (for distributed deployment)

Installation Methods

The easiest way to get started is with Docker:

# Clone the repository
git clone https://github.com/dotcommoners/machineuse.git
cd machineuse

# Start services
docker-compose up -d

# Verify installation
curl http://localhost:8000/health

Method 2: Manual Installation

Step 1: Clone the Repository

git clone https://github.com/dotcommoners/machineuse.git
cd machineuse

Step 2: Install Poetry

If you don't have Poetry installed:

curl -sSL https://install.python-poetry.org | python3 -
export PATH="$HOME/.local/bin:$PATH"

Step 3: Install Python Dependencies

cd machineuse-api
poetry install

Step 4: System Setup (Requires Root)

The deployment script installs system dependencies, sets up the base container template, configures nginx, and sets up systemd services:

sudo ./scripts/deploy.sh

Step 5: Verify Installation

# Check services
sudo systemctl status container-manager
sudo systemctl status nginx

# Test API
curl http://localhost:8000/health

# Test CLI
machineuse-cli health

Configuration

DNS Configuration

For subdomain-based access to container instances, configure DNS to point *.yourdomain.com to your server IP address.

SSL/TLS (Production)

For production deployments, configure SSL certificates:

# Install certbot
sudo apt install certbot python3-certbot-nginx

# Obtain certificates
sudo certbot --nginx -d yourdomain.com -d *.yourdomain.com

Firewall

The deployment script configures UFW rules automatically. Verify with:

sudo ufw status

Default ports:

Port Service
80 HTTP
443 HTTPS
8000 API
5555 NNG (control plane)
9222-9500 Debug ports
5000-5500 Stream ports

Troubleshooting

Common Issues

Issue Solution
Permission Denied Ensure user has sudo privileges
Port Conflicts Check if ports 8000, 80, 443 are available
systemd-nspawn Not Found Install systemd-container package
Container Creation Fails Check disk space and permissions

Log Files

# Container Manager logs
sudo journalctl -u container-manager

# Nginx logs
sudo journalctl -u nginx

# System logs
sudo journalctl -f

Service Management

# Restart services
sudo systemctl restart container-manager
sudo systemctl restart nginx

# Check service status
sudo systemctl status container-manager

Next Steps