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.