Feature Request: Document & Validate gupax-docker on NAS Platforms (Unraid, TrueNAS, Synology, CasaOS, etc.)

[libre-7]

Feature Request: Document & Validate gupax-docker on NAS Platforms

Summary

gupax-docker works well on plain Docker hosts, but there is no documentation or validated guidance for popular NAS/home-server operating systems. This issue tracks building platform-specific guides, deployment templates, and any container adjustments needed.

Why This Matters

Most self-hosted Monero miners run their containers on NAS OSes, not bare Docker hosts. Each platform has its own Docker management UI, networking quirks, and storage conventions. Without documentation, users either do not know gupax-docker is an option, or they hit friction during setup.

Platforms to Cover (prioritized)

Priority	Platform	Docker Support	Notes
P0	Unraid	Excellent (Community Apps, templates, Docker Compose)	Most popular DIY NAS. Native Docker Compose support via UI. Template could go in Community Apps.
P0	TrueNAS SCALE 24.10+	Good (Docker Compose, custom YAML, app catalog)	Electric Eel+ migrated from Kubernetes to Docker. Portainer available in app catalog.
P1	Synology DSM 7.x	Good (Container Manager with Projects/YAML)	Most popular turnkey NAS. Only x86_64 models for mining. Container Manager supports compose YAML.
P1	CasaOS	Excellent (one-click Docker app store)	Beginner-friendly dashboard on Debian/Ubuntu. Growing user base. App listing in store would give visibility.
P2	OpenMediaVault	Decent (OMV-Extras → Docker/Portainer)	Free, runs on anything. Manual via Portainer. Lower priority.
P2	HexOS	Good (built on TrueNAS SCALE)	New paid layer on SCALE. SCALE guide applies.
P3	QNAP QTS	Decent (Container Station)	Turnkey NAS. Compose YAML supported.
P3	Proxmox VE	Via LXC/VM	Hypervisor. Docker inside LXC/VM. Linux guide applies.

Deliverables Per Platform

1. A docker-compose.yml snippet tuned for that platform (volume paths, network mode, port conventions)
2. Step-by-step setup instructions in the project README.md or a docs/platforms/ directory
3. Platform-specific notes (Unraid /mnt/user/appdata/, TrueNAS dataset paths, CasaOS app metadata, etc.)
4. Verification checklist — confirm container starts, noVNC accessible, P2Pool + XMRig mining

Container Considerations for NAS Platforms

• Port conflicts: NAS OSes often use 80/443/8080. noVNC (6901) and VNC (5900) are generally safe but should be documented.
• Volume paths: Each OS has conventions — document them.
• User/group IDs: Container runs as miner (UID/GID configurable). NAS OSes use PUID/PGID conventions.
• Resource constraints: NAS CPUs are often low-power. Document XMRig thread count recommendations.
• Networking: P2Pool needs incoming peer connections (port 37888+). Container needs host or bridge network.
• OpenGL/GPU: gupax-docker uses Xvfb (software rendering). No GPU passthrough needed.
• Privileged mode: Some NAS Docker UIs may require flags. Test and document.

Related

• gupax-docker repository: https://github.com/w111a/gupax-docker
• Upstream gupax: https://github.com/gupax-io/gupax
• This issue spawned from Hermes-assisted research across eight NAS platforms (April 2026)

[libre-7]

Start9 / StartOS Research Findings

Overview

StartOS is a Linux-based personal server OS that runs services (not apps) packaged in a proprietary .s9pk format. Users install, configure, and manage everything through a web UI — no SSH or CLI access is expected.

What's Possible

• Docker containers with web UIs are supported.
• Our noVNC-based browser access qualifies as a web interface.
• StartOS auto-generates Tor .onion addresses and LAN access for declared interfaces.
• Built-in backup/restore, health checks, and config management.
• Publishing to the StartOS marketplace is possible.

What's Required to Port

1. Create a StartOS Wrapper Repository

A separate repo (e.g. gupax-startos-wrapper) with this structure:

├── Dockerfile                 # Single consolidated image
├── docker_entrypoint.sh       # Replaces start.sh, handles SIGTERM
├── manifest.ts                # Service metadata, ports, volumes
├── manifest/i18n.ts           # Translated UI strings
├── startos/
│   ├── main.ts               # Lifecycle, health checks, daemons
│   ├── init.ts               # First-run setup
│   ├── actions/              # UI buttons (e.g., "Download Binaries")
│   └── file-models/          # Config form schemas
├── Makefile                   # Builds the .s9pk
├── icon.png
├── instructions.md
└── LICENSE

2. Consolidate into One Dockerfile

StartOS only supports one Dockerfile per service (no Docker Compose). Everything must be in a single image. Must also consider switching from Ubuntu to Alpine to save space.

3. Rewrite start.sh as docker_entrypoint.sh

Must handle SIGTERM gracefully, create required directories on startup, and exit cleanly for StartOS restarts/upgrades.

4. Declare Interfaces in manifest.ts

All network access must be declared:

Interface	Purpose	Port
main	noVNC Web UI	6080
p2pool	P2Pool Stratum	3333
moneroP2p	Monero P2P	18080

5. Expose Config Through StartOS UI

StartOS replaces manual file editing with web forms. Config fields needed (mapped to Gupax's TOML state files):

• Wallet Address (required string)
• P2Pool mini/sidechain (boolean)
• XMRig threads (number)
• Monero node URL (string)
• Tor enabled (boolean)

This requires TypeScript config spec files.

6. Add Health Checks

• Check noVNC port 6080 is listening
• Check monerod RPC responds
• Check P2Pool is running

Blockers & Challenges

Blocker	Details
No ARM64 build of Gupax	Biggest issue. StartOS supports x86_64 and aarch64 (Raspberry Pi). Gupax upstream only releases linux-x64. Would need to build Gupax from Rust source for ARM64 — non-trivial.
Image size limit	StartOS recommends under 1 GB. Our image estimate: ~660 MB–1.2 GB compressed (Ubuntu + Xvfb + GTK + noVNC + Gupax + binaries). Tight fit.
GTK/config complexity	Mapping StartOS config forms to Gupax's internal TOML files is non-trivial.
No Docker Compose	Must flatten everything into one container (doable but requires refactoring).
Mining over Tor	StartOS auto-Tor is outgoing proxy only. Incoming P2Pool peer connections over Tor would need hidden service config (similar to our feat/tor-node work).

Architecture Support

Arch	Status
x86_64	Supported by upstream
aarch64	No upstream ARM64 build. Excludes Raspberry Pi users (big chunk of StartOS base).
riscv64	Unsupported

Image Size Estimate

Component	Approx Size
Ubuntu 22.04 base	~80 MB
Xvfb + GTK + GLib	~300 MB
noVNC + websockify + Python	~150 MB
Gupax binary	~30 MB
Downloaded P2Pool/XMRig/monerod	~80 MB
Tor (optional)	~20 MB
Total	~660 MB–1.2 GB

Verdict

Technically possible but requires a substantial dedicated effort to create a StartOS wrapper package. The biggest question is whether the user base justifies the work vs. documenting manual Docker installation for StartOS users (who can run Docker containers outside the .s9pk ecosystem).

Recommendation

Consider adding StartOS as a P2 platform in this issue's priority matrix. It should sit between P1 (Synology/CasaOS) and P2 (OpenMediaVault/HexOS) because:

• The privacy/self-hosting alignment is stronger than traditional NAS platforms.
• However, the packaging burden (.s9pk, TypeScript configs, ARM64 build) is much higher.

Alternatively, a short section in README/docs for manual Docker install on StartOS (bypassing .s9pk) could serve the community with far less effort.

---

This research was conducted on May 2, 2026 from the official Start9 developer documentation.