libre7/gupax-docker repository overview

Self-contained with noVNC — access the Gupax GUI directly from your web browser. No X11 server or additional setup needed.

⁠✨ Features

⁠📋 Prerequisites

• Docker⁠ (v20.10+)
• Docker Compose⁠ (v2.0+)
• A Monero wallet address (for mining payouts)
• A web browser (any modern browser)

⁠🚀 Quick Start

⁠Option 1: Docker Compose (recommended)

# 1. Clone the repository
git clone https://github.com/libre-7/Gupax-docker.git
cd Gupax-docker

# 2. Copy and edit environment file
cp .env.example .env

# 3. Start the container
docker compose up -d

# 4. Open your browser
open http://localhost:6080

# Pull and run
docker run -d \
  --name gupax \
  -p 6080:6080 \
  -p 3333:3333 \
  -p 37889:37889 \
  -p 18080:18080 \
  -p 18081:18081 \
  -v gupax-data:/home/miner/.local/share/gupax \
  -v gupax-state:/home/miner/.local/state/gupax \
  -v gupax-monero:/home/miner/.bitmonero \
  libre7/gupax-docker:latest

# Open browser
open http://localhost:6080

Click Connect on the noVNC page — no password required by default.

⁠🧅 Tor (Optional)

When TOR_ENABLED=true, the container starts a Tor daemon with a SOCKS5 proxy on 127.0.0.1:9050 and a hidden service that exposes your Monero node as a .onion address:

See the Ports table⁠ in Configuration for all Tor-related ports (18081, 18084, 18086). In short:

The container uses tx-only mode — P2P blockchain sync stays on clearnet; only wallet-originated transactions are routed through Tor. This keeps bandwidth through Tor negligible (~2 KB per transaction) while still protecting transaction privacy.

⁠Why not sync blocks over Tor?

Bandwidth — the ethical concern. A synced Monero node pushes hundreds of GB to multiple TB per month through its P2P connections. The Tor network consists of ~7,000 volunteer-run relays provisioned for web browsing and messaging — low-bandwidth, bursty traffic. Monero P2P is the opposite: sustained, high-throughput, always-on. Pushing full node sync through Tor degrades the network for everyone else, analogous to torrenting over Tor.

Monero's own design acknowledges this. From official docs:

What --tx-proxy gives you instead. Only wallet-originated transactions (~2 KB) route through Tor. Your ISP sees you running a Monero node on clearnet, but individual transaction origins are hidden behind Tor circuits. Combined with --anonymous-inbound, transactions enter and leave your node through Tor while bulk sync stays efficient on clearnet.

⁠Step-by-Step: Configuring monerod to Use Tor

1. Find your .onion address in the container logs

docker logs gupax 2>&1 | grep -A5 "Monero .onion"

You'll see output like:

[+] Monero .onion: dqwj5fyc4xfjnlswv2b4xjayxo2enr5sjgwjlimlvgeejkudo6msmqqd.onion
    │ Wallet RPC:   dqwj5fyc...onion:18081
    │ P2P inbound:  dqwj5fyc...onion:18084
    │
    │ Connect wallets over Tor:
    │   monero-wallet-cli --proxy 127.0.0.1:9050 \
    │     --daemon-address dqwj5fyc...onion:18081 \
    │     --trusted-daemon
    │
    │ Mobile wallets (Cake, Monerujo): add .onion as remote node.
    │ RPC is restricted — read-only wallet operations, no admin access.

[+] Recommended monerod arguments (Gupax → Node → Arguments):
    --restricted-rpc
    --no-igd
    --tx-proxy=tor,127.0.0.1:9050
    --anonymous-inbound=dqwj5fyc...onion:18084,127.0.0.1:18086,40

2. Open the Gupax web UI at http://your-server:6080

3. Go to the Node tab and switch from Simple to Advanced mode to reveal the "Start options:" text box

4. ⚠️ Fix the --data-dir path first. Gupax's default is the relative path .bitmonero, which does not resolve correctly in this Docker setup. In the Start options box, locate --data-dir and change it to the absolute path:

--data-dir /home/miner/.bitmonero

5. Paste the four Tor arguments from the log output (after the --data-dir fix):

--restricted-rpc --no-igd --tx-proxy=tor,127.0.0.1:9050 --anonymous-inbound=dqwj5fyc...onion:18084,127.0.0.1:18086,40

The complete Start options line should look like:

--data-dir /home/miner/.bitmonero --zmq-pub tcp://127.0.0.1:18083 --rpc-bind-ip 127.0.0.1 --rpc-bind-port 18081 --out-peers 8 --in-peers 16 --log-level 0 --sync-pruned-blocks --enable-dns-blocklist --disable-dns-checkpoints --prune-blockchain --restricted-rpc --no-igd --tx-proxy=tor,127.0.0.1:9050 --anonymous-inbound=dqwj5fyc...onion:18084,127.0.0.1:18086,40

6. Click Save (Gupax does not auto-save — if you skip this, the arguments are lost on restart)

7. Click Start to launch monerod with Tor

8. ⚠️ Fix P2Pool's ZMQ port. Gupax has a known bug where it copies the RPC port (18081) into P2Pool's --zmq-port argument. ZMQ is a different protocol on a different port (18083, set by --zmq-pub tcp://127.0.0.1:18083 on monerod). If --zmq-port 18081 is left as-is, P2Pool won't receive real-time block notifications from monerod.

Open the P2Pool tab → Advanced mode → Arguments, and change:

--zmq-port 18081

to:

--zmq-port 18083

Then click Save.

⁠Keeping the Same .onion Across Restarts

Mount the gupax-tor volume (enabled by default in docker-compose.yml) to persist the hidden service private key at /home/miner/.tor/hs_monerod/hs_ed25519_secret_key. As long as that file survives, your .onion address stays the same across container recreations.

⁠Connecting a Wallet via Tor

Once monerod is running, you can connect any Monero wallet through the same .onion address over the wallet RPC port (18081).

With a Monero wallet:

1. Go to wallet settings / nodes
2. Add a remote node: <onion>:18081 (e.g. dqwj5fyc...onion:18081)
3. The wallet syncs and submits transactions entirely through Tor

With monero-wallet-cli:

monero-wallet-cli --daemon-address <onion>:18081 --proxy 127.0.0.1:9050

⁠🖥️ Unraid Setup

This section covers installing and running Gupax-docker on Unraid.

⁠Prerequisites

• A running Unraid server (v6.12+)
• The Community Applications⁠ plugin installed

⁠Installing via Community Applications (Recommended)

1. Open the Apps tab in your Unraid web UI
2. Search for "gupax" or "monero mining"
3. Click Install
4. Set SCREEN_RESOLUTION if needed (default: 1920x1080x24)
5. Click Apply and wait for the container to start

⁠Manual Install (if not yet in Community Applications)

If Gupax-docker is not yet in the Community Applications store, you can install it manually by dropping the template XML onto your Unraid USB flash drive.

1. Download the template and place it on the flash drive:

   # From Unraid terminal, or mount the flash drive on another machine and copy it:
   wget -O /boot/config/plugins/dockerMan/templates-user/my-gupax-docker.xml \
     https://raw.githubusercontent.com/libre-7/gupax-docker/main/templates/gupax-docker.xml
   

   Copy
2. Go to the Docker tab in your Unraid web UI
3. Click Add Container
4. Select "my-gupax-docker" from the Template dropdown
5. Review the settings — adjust SCREEN_RESOLUTION if needed (default: 1920x1080x24)
6. Click Apply

⁠Accessing the GUI

Once the container is running:

1. Open your browser and go to:

   http://your-unraid-ip:6080
   

   Copy
2. Click Connect on the noVNC page — no password required
3. The Gupax GUI will appear

⁠Setting Your Wallet Address

Inside the Gupax GUI:

1. If you do not see a Node tab, go to Settings → Tabs and check Node → Save
2. Go to the Node tab and enter your Monero wallet address in the Wallet Address field
3. Save the settings

⁠Ports on Unraid

See the Ports table⁠ in Configuration for a complete list. The Unraid template maps 6080, 3333, 37889, 18080, and 18081 by default. Port 5900 (VNC) is available but disabled by default — only enable it if you have set VNC_AUTH_TOKEN.

⁠Using Your Own Blockchain on Unraid

If you have an existing Monero blockchain on your Unraid server:

1. In the template, map your blockchain directory to /home/miner/.bitmonero as a volume
2. Start the container once to ensure the path is created
3. In the Gupax GUI, go to the Node tab and set the database path to:

   /home/miner/.bitmonero
   

   Copy

⁠🔧 Configuration

⁠Environment Variables

⁠Ports

⁠Volumes

⁠Using an Existing Blockchain

If you have an existing Monero blockchain directory, you can mount it directly.

First start the container to create the volume:

docker compose up -d

Then in the Gupax GUI, go to the Node tab and set the database path to:

/home/miner/.bitmonero

Alternatively, pre-populate the volume before starting:

# Copy your blockchain to the volume
docker run --rm -v gupax-monero:/data -v /path/to/your/blockchain:/source alpine cp -r /source /data/

# Or use a host directory directly in docker-compose.yml:
# volumes:
#   - /path/to/your/blockchain:/home/miner/.bitmonero

⁠Ownership Requirements for Existing Blockchain Files

If you mount an existing blockchain from a host directory (not a fresh Docker volume), the container must have read and write permission to those files. The container runs Gupax as the user owning the gupax-data volume — auto-detected at startup or set via PUID/PGID.

If the container UID does not match the blockchain file owner, monerod will fail immediately:

Node | Stopped ... Uptime was: [1s], Exit status: [Failed]

To check and fix ownership:

# 1. Find the container's expected UID/GID
#    Check PUID/PGID env vars in docker-compose.yml or Unraid template.
#    Default on Unraid: 99:100 (nobody:users)

# 2. Check current ownership of your blockchain files
ls -ln /path/to/your/blockchain/lmdb/data.mdb

# 3. Change ownership to match the container (example for Unraid: 99:100)
chown -R 99:100 /path/to/your/blockchain

⁠🔐 Security Notes

• The noVNC interface has no password by default — set VNC_AUTH_TOKEN to enable authentication
• Only expose port 6080 to trusted networks
• For production use, consider adding authentication at the network level

⁠Unraid FUSE Filesystems (Important)

Unraid uses FUSE (fuse.shfs) for its appdata shares, which silently ignores chown. The container detects this at startup and applies world-writable permissions (chmod a+rwX) on the Gupax data volume so the container can write files regardless of the host user ID.

What this means: Any process on your Unraid host — or any other container — can read and write files in /mnt/user/appdata/gupax/. This includes:

• Mining binaries (P2Pool, XMRig, monerod) — could be replaced with a trojaned version by a compromised container
• Gupax config (wallet, node settings) — could be read or modified
• Tor hidden service keys — the keys are restricted to root in the container, but if you mount their parent directory from a host path on a FUSE share, the same world-writable concerns apply

Mitigations:

• Keep your Unraid host secure — don't run untrusted containers
• Consider mounting appdata from a non-FUSE location (e.g., an SSD cache pool with btrfs or xfs) if security is a concern
• This is a fundamental Unraid limitation, not specific to Gupax-docker — any Docker container on Unraid with persistent volumes faces the same trade-off

⁠🐛 Troubleshooting

⁠Gupax appears blank or black in the browser

Try refreshing the page and waiting 10-20 seconds for Gupax to fully initialize. If the issue persists, restart the container:

docker compose restart

⁠Connection refused on port 6080

Make sure the container is running:

docker compose logs
docker compose ps

⁠Container keeps restarting

Check the logs:

docker compose logs

⁠P2Pool spamming empty response / EBADF errors

Symptoms: Log fills with:

JSONRPCRequest uv_poll_start returned error EBADF
P2Pool get_info RPC request to host 127.0.0.1:RPC 18081:ZMQ 18083 failed: Error (empty response)

Root cause: Gupax v2.0.0+ hides the Node tab by default. If the Node was never enabled, monerod is not running — but P2Pool (and possibly XMRig/xmrig-proxy) still tries to connect to 127.0.0.1:18081, producing endless RPC failures.

Fix:

1. In the Gupax GUI → Settings → Tabs → check Node → Save
2. Go to the Node tab → ensure Node Type is Local and Port is 18081
3. In Arguments, add:

   --zmq-pub tcp://127.0.0.1:18083
   

   Copy
   (If you use Tor, also append the Tor args from the container startup banner.)
4. Click Save, then Start
5. Wait for the Node status to go green (30–120s), then verify P2Pool stops erroring

Note for auto-start users: If you previously had Node set to auto-start but the tab was hidden after a config reset or Gupax upgrade, the auto-start setting may also be reset. You must re-enable both the tab visibility AND the auto-start toggle on the Node tab.

⁠🔗 Official Resources

• Gupax⁠ — The GUI unifying P2Pool & XMRig
• P2Pool⁠ — Decentralized Monero mining pool
• XMRig⁠ — High-performance Monero miner
• Monero⁠ — Private, decentralized cryptocurrency
• noVNC⁠ — HTML5 VNC client

⁠⚠️ Disclaimer

Mining cryptocurrency consumes significant electricity and may not be profitable depending on your hardware, electricity costs, and market conditions. This project is provided as-is for educational and convenience purposes. Always do your own research before investing in mining hardware or cryptocurrency. The maintainers of this repository are not responsible for any financial losses.

⁠📄 License

This project is licensed under the GNU General Public License v3.0⁠.

Gupax, P2Pool, and XMRig are each licensed under their respective licenses — see the official repositories linked above.