Skip to content

INSTALL.md

Latest commit

 

History

History
383 lines (275 loc) · 9.34 KB

INSTALL.md

File metadata and controls

383 lines (275 loc) · 9.34 KB

Installation Guide

This guide covers installing PrintMaster on all supported platforms.

Table of Contents

Quick Install

Server (Docker)

docker run -d \
  --name printmaster-server \
  -p 9090:9090 \
  -v printmaster-data:/var/lib/printmaster/server \
  -e ADMIN_PASSWORD=your-secure-password \
  ghcr.io/mstrhakr/printmaster-server:latest

Access at http://localhost:9090 with username admin and your chosen password.

Agent (Windows)

Download and run the MSI installer from GitHub Releases.

Agent (Linux)

# Debian/Ubuntu
curl -fsSL https://mstrhakr.github.io/printmaster/install.sh | sudo bash

# Or manual apt install
echo "deb [trusted=yes] https://mstrhakr.github.io/printmaster stable main" | \
  sudo tee /etc/apt/sources.list.d/printmaster.list
sudo apt-get update && sudo apt-get install -y printmaster-agent

Server Installation

The server provides centralized management for multiple agents. If you only need to monitor printers at a single site, you can run the agent standalone without a server.

Docker (Recommended)

Docker is the recommended deployment method for the server.

Prerequisites

  • Docker Engine 20.10 or later
  • Docker Compose (optional but recommended)

Using Docker Run

# Basic setup
docker run -d \
  --name printmaster-server \
  -p 9090:9090 \
  -v printmaster-data:/var/lib/printmaster/server \
  -v printmaster-logs:/var/log/printmaster/server \
  -e ADMIN_PASSWORD=your-secure-password \
  ghcr.io/mstrhakr/printmaster-server:latest

Using Docker Compose

Create a docker-compose.yml file:

version: '3.8'
services:
  printmaster-server:
    image: ghcr.io/mstrhakr/printmaster-server:latest
    container_name: printmaster-server
    ports:
      - "9090:9090"
    volumes:
      - printmaster-data:/var/lib/printmaster/server
      - printmaster-logs:/var/log/printmaster/server
    environment:
      - ADMIN_PASSWORD=your-secure-password
      - LOG_LEVEL=info
      - BEHIND_PROXY=false
    restart: unless-stopped

volumes:
  printmaster-data:
  printmaster-logs:

Start with:

docker compose up -d

Environment Variables

Variable Default Description
ADMIN_PASSWORD printmaster Admin password (set before first run!)
LOG_LEVEL info Logging level: debug, info, warn, error
BEHIND_PROXY false Set to true if behind a reverse proxy
BIND_ADDRESS 0.0.0.0 Address to bind to
HTTP_PORT 9090 HTTP port
HTTPS_PORT 9443 HTTPS port (when TLS enabled)

Important: Set ADMIN_PASSWORD before the first run. The password can only be set during initial database creation.

Behind a Reverse Proxy

If using Nginx Proxy Manager, Traefik, or another reverse proxy:

environment:
  - BEHIND_PROXY=true
  - BIND_ADDRESS=0.0.0.0

Configure your proxy to:

  • Forward to port 9090
  • Enable WebSocket support (required for real-time features)
  • Handle SSL termination

Unraid

  1. Using Community Applications (Easiest):

    • Install the Community Applications plugin
    • Search for "PrintMaster Server"
    • Click Install and configure

  2. Manual Docker Setup:

    • Go to Docker tab → Add Container
    • Repository: ghcr.io/mstrhakr/printmaster-server:latest
    • Port: 9090 → 9090
    • Path: /mnt/user/appdata/printmaster-server/data → /var/lib/printmaster/server
    • Path: /mnt/user/appdata/printmaster-server/logs → /var/log/printmaster/server

See Unraid Deployment Guide for detailed instructions.

Manual Server Installation

Download the server binary from GitHub Releases and run:

# Linux/macOS
./printmaster-server

# Windows
.\printmaster-server.exe

Agent Installation

Windows

MSI Installer (Recommended)

  1. Download the latest MSI from GitHub Releases
  2. Run the installer
  3. The agent will be installed as a Windows service and start automatically
  4. Access the web UI at http://localhost:8080

Manual Installation

# Download the binary
Invoke-WebRequest -Uri "https://github.com/mstrhakr/printmaster/releases/latest/download/printmaster-agent-windows-amd64.exe" -OutFile "printmaster-agent.exe"

# Install as service (requires Administrator)
.\printmaster-agent.exe --service install

# Start the service
.\printmaster-agent.exe --service start

Service Management

# Check status
Get-Service PrintMasterAgent

# Stop service
.\printmaster-agent.exe --service stop

# Uninstall service
.\printmaster-agent.exe --service uninstall

Linux (Debian/Ubuntu)

APT Repository (Recommended)

# Add repository
echo "deb [trusted=yes] https://mstrhakr.github.io/printmaster stable main" | \
  sudo tee /etc/apt/sources.list.d/printmaster.list

# Install
sudo apt-get update
sudo apt-get install -y printmaster-agent

# The service starts automatically
systemctl status printmaster-agent

With GPG Signature Verification (Recommended for Production)

# Import GPG key
curl -fsSL https://mstrhakr.github.io/printmaster/gpg.key | \
  sudo gpg --dearmor -o /usr/share/keyrings/printmaster.gpg

# Add repository with signature verification
echo "deb [signed-by=/usr/share/keyrings/printmaster.gpg] https://mstrhakr.github.io/printmaster stable main" | \
  sudo tee /etc/apt/sources.list.d/printmaster.list

# Install
sudo apt-get update
sudo apt-get install -y printmaster-agent

Manual Installation

# Download
wget https://github.com/mstrhakr/printmaster/releases/latest/download/printmaster-agent-linux-amd64

# Make executable
chmod +x printmaster-agent-linux-amd64
sudo mv printmaster-agent-linux-amd64 /usr/local/bin/printmaster-agent

# Install as service
sudo printmaster-agent --service install
sudo systemctl start PrintMasterAgent

Linux (Fedora/RHEL)

DNF Repository (Recommended)

# Import GPG key (recommended)
sudo rpm --import https://mstrhakr.github.io/printmaster/gpg.key

# Add repository
sudo dnf config-manager addrepo --from-repofile=https://mstrhakr.github.io/printmaster/printmaster.repo

# Install
sudo dnf install -y printmaster-agent

# The service starts automatically
systemctl status printmaster-agent

Important Linux Paths

Path Description
/usr/bin/printmaster-agent Agent binary
/etc/printmaster/agent.toml Configuration file
/var/lib/printmaster Data directory (SQLite DB)
/var/log/printmaster Log files

macOS

# Download
curl -LO https://github.com/mstrhakr/printmaster/releases/latest/download/printmaster-agent-darwin-amd64

# Make executable
chmod +x printmaster-agent-darwin-amd64
sudo mv printmaster-agent-darwin-amd64 /usr/local/bin/printmaster-agent

# Install as service
sudo printmaster-agent --service install

# Start service
sudo launchctl load /Library/LaunchDaemons/com.printmaster.agent.plist

Docker Agent

The agent can also run in Docker for specialized deployments:

docker run -d \
  --name printmaster-agent \
  --network host \
  -v printmaster-agent-data:/var/lib/printmaster/agent \
  ghcr.io/mstrhakr/printmaster-agent:latest

Note: --network host is required for SNMP discovery to work properly.

First-Time Setup

Accessing the Web UI

Component Default URL Default Port
Agent http://localhost:8080 8080
Server http://localhost:9090 9090

Server First Login

  1. Open http://your-server:9090
  2. Log in with:
    • Username: admin
    • Password: The password you set via ADMIN_PASSWORD (default: printmaster)
  3. Change the default password immediately if you didn't set one during installation

Connecting an Agent to the Server

  1. Open the agent's web UI at http://agent-ip:8080
  2. Go to Settings → Server Connection
  3. Enter your server URL: http://your-server:9090
  4. Click Save

Or edit the agent's config file:

[server]
enabled = true
url = "http://your-server:9090"

Next Steps

Upgrading

Docker

docker pull ghcr.io/mstrhakr/printmaster-server:latest
docker compose down
docker compose up -d

Linux (APT)

sudo apt-get update
sudo apt-get upgrade printmaster-agent

Linux (DNF)

sudo dnf upgrade printmaster-agent

Windows

Run the new MSI installer - it will upgrade the existing installation.

Auto-Updates

Agents support automatic updates. See Configuration Guide for setup instructions.