lunarfront-app/planning/14_Self_Hosted_Installer_Platform_Compatibility.md

Music Store Management Platform

Self-Hosted Deployment — Installer Design & Platform Compatibility

Version 1.0 | Draft

1. Overview

The self-hosted deployment must be as simple as installing any consumer application. The target user is a music store owner or manager with no IT background. The experience should match what they expect from installing any Windows or Mac application — download, double-click, next-next-finish, done.

Under the hood the platform runs in Docker containers managed by Docker Compose. The store owner never sees Docker, never opens a terminal, and never touches a config file. All of that complexity is hidden inside a native installer and a system tray management app.

User sees

What actually happens

Download setup.exe

Downloads a bundled installer containing Docker, your stack, and the tray app

Double-click installer

Installer checks Windows edition, enables Hyper-V or WSL2, installs Docker Engine

Fill in store name + password

Generates .env config file with store settings and secure random secrets

Click Install

Docker Compose pulls images, initializes Postgres, seeds config, registers Windows service

Browser opens automatically

Nginx serves the app at localhost:3000 — first-run setup wizard shown

Tray icon appears

Management app running — monitors service health, handles updates, backup triggers

2. Virtualization Layer

Docker requires a Linux kernel to run containers. On Windows and Mac, a lightweight virtualization layer provides this. The installer detects and configures the appropriate layer automatically based on the OS.

2.1 Windows Virtualization

Windows Edition

Virtualization

Installer Action

Windows 10/11 Pro

Hyper-V

Enable Hyper-V via PowerShell silently — no user action required

Windows 10/11 Enterprise

Hyper-V

Same as Pro — Hyper-V included and licensable

Windows 10/11 Home

WSL2

Install WSL2 silently. If BIOS virtualization disabled, show friendly guide.

Windows Server 2019/2022

Hyper-V

Docker Engine direct — no Desktop needed. Most performant option.

The vast majority of music store computers will be Windows 10/11 Pro — retail businesses typically purchase Pro licenses. Home edition is handled gracefully as a fallback. Windows Server is supported for IT-managed deployments.

Hyper-V Silent Enable (PowerShell)

Installer runs this silently — requires admin elevationEnable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V -All -NoRestartEnable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart# Reboot required after enabling Hyper-V# Installer schedules resume-after-reboot via registry run key

2.2 macOS Virtualization

macOS 12+ (Monterey and later) includes Apple's Virtualization Framework built into the OS. Docker Desktop uses this transparently. No additional configuration required from the store owner.

macOS Version

Architecture

Notes

macOS 12+ (Monterey+)

Intel x86-64

Apple Virtualization Framework — fully supported

macOS 12+ (Monterey+)

Apple Silicon ARM64

Native ARM containers — best performance on M1/M2/M3

macOS 11 (Big Sur)

Intel only

Supported but approaching end of life — recommend upgrade

macOS 10.x or earlier

Not supported

Too old — installer shows friendly upgrade message

2.3 Linux

Linux deployments run Docker Engine natively — no virtualization layer required. Containers run directly on the host kernel. This is the most performant deployment option and is appropriate for IT-managed stores or dedicated server hardware.

One-line install for Ubuntu 22/24 LTScurl -fsSL https://install.platform.com/linux | bash# Script handles:# - Docker Engine installation# - Docker Compose installation# - Stack configuration# - Systemd service registration# - First-run database initialization

3. Platform Compatibility Matrix

Platform

Supported

Virtualization

Architecture

Notes

Windows 11 Pro/Enterprise

Yes

Hyper-V

x86-64

Recommended for most stores

Windows 11 Home

Yes

WSL2

x86-64

BIOS virt must be enabled

Windows 10 Pro/Enterprise

Yes

Hyper-V

x86-64

Version 1903+ required

Windows 10 Home

Yes

WSL2

x86-64

May need BIOS change

Windows Server 2022

Yes

Hyper-V

x86-64

Docker Engine direct

Windows Server 2019

Yes

Hyper-V

x86-64

Docker Engine direct

macOS 14 Sonoma

Yes

Apple Virt FW

ARM64 / x86-64

Intel and Apple Silicon

macOS 13 Ventura

Yes

Apple Virt FW

ARM64 / x86-64

macOS 12 Monterey

Yes

Apple Virt FW

x86-64

Intel only

macOS 11 Big Sur

Limited

HyperKit

x86-64

Approaching EOL

Ubuntu 22.04 LTS

Yes

Native

x86-64 / ARM64

Recommended Linux

Ubuntu 24.04 LTS

Yes

Native

x86-64 / ARM64

Raspberry Pi (4/5)

Yes

Native

ARM64

Pi 5 recommended — 8GB RAM

Multi-architecture Docker images are built for both linux/amd64 and linux/arm64 on every release. Docker automatically pulls the correct image for the host architecture. No platform-specific configuration required from the store.

3.1 Minimum Hardware Requirements

Component

Minimum

Recommended

CPU

4-core x86-64 or ARM64

6-core or better — handles concurrent POS terminals smoothly

RAM

8GB

16GB — headroom for Postgres query cache and API under load

Storage

100GB SSD

500GB SSD — 5+ years of transaction data with room to spare

Network

100Mbps LAN

Gigabit LAN — fast for multi-terminal stores

OS

See compatibility matrix

Windows 11 Pro or Ubuntu 24 LTS

3.2 Recommended Hardware

For most music stores a mini PC is the ideal self-hosted server. Small, quiet, low power, no moving parts, runs 24/7 reliably. Examples:

Device

Est. Cost

Notes

Intel NUC 13 Pro (i5)

$400-500

Compact, reliable, Windows 11 Pro. Popular choice for small business servers.

Beelink Mini S12 Pro

$180-220

Budget option. N100 processor handles the stack well. 16GB RAM config recommended.

Existing store PC

$0

If meets min specs — install alongside existing OS. Avoids new hardware purchase.

Raspberry Pi 5 (8GB)

$80-120

ARM64, fanless, extremely low power. Requires Ubuntu — Linux-savvy stores only.

Dell OptiPlex (refurb)

$150-250

Refurbished business desktop. Reliable, widely available, Windows Pro pre-installed.

4. Installer Design

4.1 Windows Installer (.exe)

Built with Inno Setup or NSIS — industry standard Windows installer frameworks. Produces a single signed .exe that handles the complete installation. Code signing certificate required to avoid Windows SmartScreen warnings.

Installer Contents

setup.exe (self-extracting archive) contains: ├── docker-install/ Docker Desktop or Engine MSI ├── compose/ │ ├── docker-compose.yml │ ├── nginx.conf │ └── init-db.sql ├── tray-app/ │ └── PlatformManager.exe (Electron or Go tray app) ├── scripts/ │ ├── install.ps1 PowerShell install logic │ ├── enable-hyperv.ps1 Hyper-V activation │ ├── service-register.ps1 Windows service setup │ └── first-run.ps1 Initial DB seed └── resources/ ├── icon.ico └── license.txt

Installation Steps (User Facing)

Screen

Title

What happens

1

Welcome

Intro screen, version number, Next button

2

License Agreement

EULA — must accept to continue

3

Install Location

Default: C:\Program Files\Platform — most stores leave default

4

Store Setup

Store name, admin email, admin password, timezone — generates .env

5

Installing

Progress bar — enables Hyper-V/WSL2, installs Docker, pulls images, seeds DB

6

Complete

Open Platform button — launches browser to localhost:3000

Behind the Scenes During Install Step 5

1. Check Windows edition → select Hyper-V or WSL22. Enable virtualization layer (may require reboot — handled automatically)3. Install Docker Desktop silently (--quiet flag)4. Wait for Docker daemon to start (poll /var/run/docker.sock)5. Pull Docker images (progress shown per image)6. Generate SSL certificate (self-signed, 10yr validity)7. Write .env file with store config and generated secrets8. docker compose up -d9. Wait for Postgres health check to pass10. Run database migrations11. Seed initial config (store name, admin user, chart of accounts)12. Register PlatformManager.exe as Windows startup item13. Register docker compose as Windows service (auto-start on boot)14. Open browser to localhost:3000

4.2 macOS Installer (.dmg)

Standard macOS disk image containing a drag-to-Applications app bundle. The app bundle is a macOS app that includes Docker Desktop and manages the compose stack. Code signed and notarized with Apple Developer certificate to avoid Gatekeeper warnings.

Platform.dmg └── Platform.app (drag to /Applications) └── Contents/ ├── MacOS/ │ └── PlatformManager (menu bar app binary) ├── Resources/ │ ├── docker-compose.yml │ ├── Docker.dmg (Docker Desktop bundled) │ └── icon.icns └── Info.plist

On first launch the menu bar app detects if Docker Desktop is installed, installs it if not, pulls images, and starts the stack. Subsequent launches just start the menu bar icon — stack starts automatically via launchd.

4.3 Linux Install Script

Single bash script handles the complete Linux installation. Appropriate for IT-managed deployments and technically capable store owners on Ubuntu.

curl -fsSL https://install.platform.com/linux | sudo bash# Script actions:# 1. Detect distro (Ubuntu 22/24 supported)# 2. Install Docker Engine via official apt repo# 3. Install Docker Compose plugin# 4. Create /opt/platform/ directory# 5. Download docker-compose.yml and config files# 6. Prompt for store name, admin email, password# 7. Generate .env and SSL cert# 8. docker compose up -d# 9. Register systemd service for auto-start# 10. Print access URL and admin credentials

5. System Tray & Menu Bar Management App

The management app is the store owner's window into the platform's health. It runs silently in the background and provides a simple interface for the most common management tasks without requiring any technical knowledge.

5.1 Tech Stack

The tray app is built as a small standalone binary using one of the following approaches — final choice based on development effort vs capability tradeoff:

Option

Size

Notes

Go + systray lib

~10MB

Recommended — small binary, cross-platform, easy Docker API calls, fast startup

Rust + tray-icon

~5MB

Smallest binary, great performance, steeper development curve

Electron

~150MB

Easiest to build, heaviest — uses same stack as desktop app so reusable code

Python + pystray

~50MB

Quick to develop but large bundled size

5.2 Tray Icon States

Icon State

Color

Meaning

Running

Green

All services healthy — API, Postgres, Redis all responding

Starting

Yellow

Services starting up — normal after boot, takes 30-60 seconds

Update available

Blue badge

New version available — click to view changelog and update

Warning

Orange

One service degraded but platform partially operational

Stopped / Error

Red

Platform not running or critical service down

5.3 Tray Menu

Right-click tray icon: ┌─────────────────────────────┐ │ ● Platform Manager │ │ Version 1.5.2 │ ├─────────────────────────────┤ │ Open Platform → │ Opens localhost:3000 in browser ├─────────────────────────────┤ │ Status │ │ ✓ API Running │ │ ✓ Database Running │ │ ✓ Cache Running │ ├─────────────────────────────┤ │ 🔵 Update Available (1.6.0) │ Shows when update exists │ View Changelog │ │ Install Update │ ├─────────────────────────────┤ │ Backup Now │ Triggers manual backup │ View Last Backup │ Shows last backup time ├─────────────────────────────┤ │ Restart Services │ docker compose restart │ View Logs │ Shows last 100 API log lines ├─────────────────────────────┤ │ Stop Platform │ docker compose down └─────────────────────────────┘

5.4 Update Flow via Tray App

1. Tray app polls update registry daily on startup GET https://updates.platform.com/check?version=1.5.2&key=LICENSE2. If update available — tray icon shows blue badge Tooltip: 'Platform 1.6.0 available'3. Store owner right-clicks → View Changelog Simple window shows what's new in plain language 'Fixed rental billing date issue, improved school batch reports'4. Store owner clicks Install Update Progress window appears: [=====> ] Backing up database... [=========> ] Downloading update... [=============>] Applying update... [==============] Done!5. Browser refreshes automatically — new version running If update fails — automatic rollback to previous version Error message: 'Update failed, your previous version has been restored'

6. Auto-Start & Service Management

The platform starts automatically when the server boots. Store owners should never need to manually start the software — it should just be running when they arrive in the morning.

6.1 Windows Service

Platform Manager registered as Windows Service: Name: PlatformService Startup: Automatic (delayed) Recovery: Restart on failure (3 attempts) Action: Runs 'docker compose up -d' on startDocker Desktop also set to start with Windows.Sequence on boot: 1. Windows starts 2. Docker Desktop starts (Hyper-V/WSL2 VM initializes) 3. PlatformService starts (waits for Docker daemon) 4. docker compose up -d (starts all containers) 5. Tray app launches (shows starting state) 6. ~60 seconds after boot — platform ready

6.2 macOS launchd

LaunchAgent plist registered in ~/Library/LaunchAgents/ com.platform.manager.plist RunAtLoad: true KeepAlive: trueSame sequence as Windows — Docker starts, then compose stack.

6.3 Linux systemd

/etc/systemd/system/platform.service[Unit]Description=Platform Music StoreAfter=docker.serviceRequires=docker.service[Service]WorkingDirectory=/opt/platformExecStart=docker compose upExecStop=docker compose downRestart=alwaysRestartSec=10[Install]WantedBy=multi-user.target

7. Backup — Self-Hosted

Backup is the store's responsibility on self-hosted deployments. The platform provides automated local backup tooling and an optional cloud backup add-on. Store owners should be clearly informed during installation that they are responsible for their own data.

7.1 Local Backup (Included)

• Automated daily Postgres dump to local backup directory

• Default location: install directory /backups/

• Retains last 30 daily backups — older automatically pruned

• Backup integrity verified after each dump — corrupt backup flagged in tray app

• Tray app shows last backup time and status

• Manual backup available via tray menu at any time

• Store strongly recommended to copy backups to external drive or NAS regularly

7.2 Cloud Backup Add-On ($29/month)

• Encrypted backup uploaded to vendor S3 after each local backup

• Encryption key held by customer — vendor cannot read backup data

• 30-day retention in cloud — point-in-time restore available

• Restore wizard available in admin panel — no technical knowledge required

• Ideal for stores without IT staff or dedicated backup infrastructure

7.3 Backup Responsibility Notice

During installation the store owner must acknowledge the following before completing setup:

IMPORTANT — DATA BACKUP RESPONSIBILITYYou are responsible for backing up your data.This software includes automated local backups but theseare stored on the same machine as your data.We strongly recommend: • Enabling cloud backup ($29/month add-on), OR • Regularly copying backups to an external drive or NASHardware failure can result in permanent data lossif backups are not stored separately.[ ] I understand I am responsible for my data backups (checkbox — must check to proceed)

8. Network Access

The platform runs on the store's local network. The Electron desktop app, iOS app, and any browser on the local network can access it by IP address or hostname.

• Default access: http://[server-ip]:3000 or http://platform.local (mDNS)

• HTTPS available with self-signed cert — browser warning expected, staff instructed to accept

• Optional Let's Encrypt cert if store has a domain name pointed at their server

• Remote access via VPN — store uses existing VPN infrastructure

• No ports need to be opened to the internet for core operation

• Cloud backup and update checker are the only outbound internet connections required

For stores that want remote access without a VPN, Cloudflare Tunnel is a free option that creates a secure tunnel without exposing ports. The tray app can optionally configure this during setup.