mfgx/native-app-launcher repository overview

⁠Fuuz In-House Deployment

Beta — on-premises Fuuz for Docker Swarm. One container installs and runs the whole platform.

⁠TL;DR

1. Request a trial license⁠ — Fuuz will not start without one.

2. Give Docker 12 GB of memory and 4 CPUs (16 GB is better). On Windows that is .wslconfig, not the Docker Desktop sliders — see Giving Docker enough memory and CPU.

3. Start the launcher on the machine that will run Fuuz:

   docker run -d --name fuuz-launcher \
     --restart unless-stopped \
     -p 127.0.0.1:9000:9000 \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v fuuz_launcher_state:/var/lib/fuuz-launcher \
     mfgx/native-app-launcher:trial-latest
   

   Copy

   Windows: use PowerShell and the single-line form in step 3 — \ is not a line continuation there, and Git Bash breaks the Docker socket path.

4. Open the launcher. docker logs fuuz-launcher prints its address with an access token — http://localhost:9000/?token=…. The bare address will not work; take the whole line. Then paste your license key and press Start Fuuz.

The first start downloads ~32 images, so it is governed mostly by your connection. Everything below is detail.

Part of the Fuuz Industrial Intelligence Platform⁠, for on-premises deployment.

This repository holds one image of roughly 32, and you do not pull them individually. The Fuuz Launcher deploys and manages the rest — three RabbitMQ brokers and a proxy, a three-member MongoDB replica set, Redis, object storage, an nginx reverse proxy, and the Fuuz services and web app — and it is where you go afterwards to start, stop, update, back up and troubleshoot.

You do not need to know Docker Swarm: the launcher initializes it, generates every password, orders the startup so nothing starts before what it depends on, and reports what is running.

⁠1. Get a license key

Your key arrives by email from the form linked above. Copy the whole key — a partial one will not validate. Subscription customers use the key supplied with the subscription.

⁠2. What you need

⁠x86 machines only

Fuuz images are published for 64-bit x86 (linux/amd64) only — ordinary Intel and AMD hardware, which is nearly every Windows and Linux server, plus Intel Macs.

ARM is not supported: Apple Silicon Macs, ARM cloud instances, Windows on ARM. Docker there offers x86 emulation and some containers appear to start, but the databases underneath Fuuz do not run dependably that way. Use an x86 machine or cloud VM.

Check with docker info --format '{{.Architecture}}': it should report x86_64, not aarch64 or arm64.

⁠Giving Docker enough memory and CPU

Where this is configured depends on how Docker runs on your machine.

Windows, Docker Desktop with the WSL 2 backend (the default). Memory and CPU come from WSL, not from Docker Desktop, so Settings → Resources has no sliders for them. Create or edit %UserProfile%\.wslconfig:

[wsl2]
memory=16GB
processors=6

Then run wsl --shutdown and restart Docker Desktop. WSL takes only a share of host RAM by default, so on a machine with 16 GB or less you may need to add memory before Docker can have 12 GB.

Windows with the Hyper-V backend, and macOS: the sliders do apply — Settings → Resources → Advanced, then restart Docker.

Linux, Docker Engine: containers use the host's memory and CPUs directly, with no limit to raise. If the check reports too little, the machine itself needs more.

The launcher reports the figure Docker has, not the machine's total, rounded to whole gigabytes — a hypervisor keeps a few percent off the top, so 12 GB arrives as about 11.7 and is read as the 12 you asked for.

⁠3. Start the launcher

The macOS/Linux/WSL command is in the TL;DR above. On Windows, use PowerShell and this single line instead:

docker run -d --name fuuz-launcher --restart unless-stopped -p 127.0.0.1:9000:9000 -v /var/run/docker.sock:/var/run/docker.sock -v fuuz_launcher_state:/var/lib/fuuz-launcher mfgx/native-app-launcher:trial-latest

Subscription customers substitute their own channel (mfgx/native-app-launcher:production-latest) and set the launcher's Image tag setting to match, so the launcher and the platform it deploys come from one release channel. See Image tags below.

⁠What each flag does

Do not paste the multi-line form into PowerShell — \ is not a line continuation there, so you get docker: invalid reference format and The term '-p' is not recognized.... Do not run either form in Git Bash: it rewrites the leading / in /var/run/docker.sock into a path inside your Git install, so the container starts but cannot see Docker. Use PowerShell, or prefix with MSYS_NO_PATHCONV=1.

⁠4. Open the launcher

Run docker logs fuuz-launcher. Near the end it prints the address with an access token — http://localhost:9000/?token=Yk3n_9pQ... — which you open in a browser on the same machine.

• The token is generated fresh on every container start, so a bookmarked URL stops working after a restart. Re-read the log, or add -e LAUNCHER_TOKEN=<your-token> to fix it.
• It is what stops any other page in your browser from driving the Docker daemon here. Treat it like a password; do not paste the URL into a chat or a support ticket.
• "Missing or invalid launcher token" means the URL is stale. (LAUNCHER_REQUIRE_TOKEN=false turns it off entirely — only sensible on a host you fully control.)

⁠5. Enter your license key

The first screen asks for one thing. Paste the entire key and press Save and continue. Add this later gets you past it — useful if you opened the launcher just to check Docker is healthy — and you can add it under Settings → License before starting.

The key is validated by Fuuz's own initialization container during the start, not by the launcher. A wrong or truncated key stops the start at the licensing stage and shows you that container's output.

⁠6. Check your settings

Everything except the license key has a working default. The ones most installations look at, under Settings:

Press Save. Saved settings take effect on the next start or re-deploy — Docker Swarm cannot change a running container's environment, so nothing moves until the services are replaced.

⁠If ports 80 or 443 are taken

Two options:

1. Move Fuuz. Set Web port and Secure web port to free ports — 8080 and 8443 are the usual choices. Every address then carries the port (fuuz.localhost:8080, api.fuuz.localhost:8080). That works, but everyone who uses Fuuz sees the port.
2. Put Fuuz behind the web server you already run, usually the better arrangement. Move Fuuz to its own port as above, then reverse-proxy to it so addresses stay clean. Pass the Host header through unchanged — Fuuz's proxy routes on it, and api.<domain> is otherwise the same server.

Ports are checked before anything is downloaded, so a conflict is reported in seconds rather than part-way through a start.

⁠7. Start Fuuz

On Overview, press Start Fuuz. The run streams through five stages:

1. Preflight — memory, CPUs, host ports, domain resolution and your settings, all before a single image is downloaded.
2. Swarm — initializes Docker Swarm on this machine if it is not already.
3. License and credentials — validates the license key, and on a first start generates every database and broker password. Later starts re-check the licence and carry the existing passwords forward unchanged; your databases authenticate against them, so they are never replaced behind your back.
4. Core services — MongoDB, RabbitMQ, Redis, object storage and the proxy, then a wait until they are genuinely serving rather than merely started. A first run spends most of its time here downloading images; it allows up to 15 minutes.
5. Fuuz services — the platform services and the web application.

The run finishing does not mean every service is up. The final check covers the proxy and the web application, neither of which waits on a backend service, so the stream can complete while backend services are still starting. Overview → Service details lists live status for every service — read that rather than the stream.

⁠What your installation serves

MongoDB is deliberately not published to the host — backups, restores and health checks all run inside its container. Database credentials for your own tooling are on the launcher's Credentials tab.

⁠Day-to-day operations

All on the launcher's Overview tab.

Renewing or replacing a license. Paste the new key into Settings → License, Save, then Re-deploy. The license is checked on every start, so an expired key is reported at the licensing stage rather than surfacing later as services failing for no obvious reason. Data and credentials are unaffected.

Moving to a new Fuuz version. A -latest tag moves with each release, so a Re-deploy picks up the current one. To stay on a known version, pin Settings → Images → Image tag to a specific release. Take a backup first, and read the release notes.

Updating the launcher itself. A running container keeps the image it started from, so replace the container:

docker pull mfgx/native-app-launcher:trial-latest
docker rm -f fuuz-launcher

Then run the docker run command again. Settings, credentials and backups live in the fuuz_launcher_state volume and survive it. Your Fuuz installation keeps running throughout — the launcher going away does not stop it.

⁠Backups

The launcher takes a consistent snapshot of the whole Fuuz database with MongoDB's own tooling, as a single compressed archive.

Automatic backups are on by default: one a day at 02:00 UTC, keeping the 7 most recent. Change that with variables on the docker run command:

Archives land in the launcher's state volume (fuuz_launcher_state, under backups/) as fuuz-<timestamp>.archive.gz — outside the Fuuz stack's volumes, so deleting the installation does not delete its backups. Generated passwords are Swarm secrets and cannot be read back, so the Credentials tab is the only copy.

A backup on the same machine does not protect you from losing the machine. It protects you from a bad import, a dropped collection or a failed upgrade. Download a copy elsewhere on whatever schedule your data deserves.

Backups are managed over the launcher's API, using the token from docker logs fuuz-launcher:

TOKEN=<token from the launcher log>

# List backups, and the current schedule
curl -s "http://127.0.0.1:9000/api/backups?token=$TOKEN"

# Take one now
curl -s -X POST "http://127.0.0.1:9000/api/backups?token=$TOKEN"

# Download one — do this
curl -s -o fuuz-backup.archive.gz \
  "http://127.0.0.1:9000/api/backups/<name>/download?token=$TOKEN"

⁠Restoring

A restore replaces the current contents of the database with the archive's. It cannot be undone — back up the current state first.

curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"confirm":"restore"}' \
  "http://127.0.0.1:9000/api/backups/<name>/restore?token=$TOKEN"

The confirmation is required; a request without it is rejected rather than performed. A restore is also refused (HTTP 409, with an explanation) if the archive came from a different line of Fuuz images than the one you are restoring into — putting data written by one build underneath another is not recoverable. Add "force":true if you are certain.

⁠Troubleshooting

Start with the launcher's own page — the banner at the top, and the service states under Overview → Service details. docker logs fuuz-launcher is the next place to look.

⁠Reaching the launcher from another machine

The run command deliberately serves the launcher only to the machine it runs on, because anything that can reach port 9000 has root-equivalent control of Docker on that host. Prefer a VPN or an SSH tunnel to publishing the port.

If you do publish it, two changes go together: publish on a reachable interface (-p 9000:9000), and name the hostname you will use (-e LAUNCHER_ALLOWED_ORIGINS=fuuz-box:9000). That is a comma-separated list of the hostnames (with port, if not 80 or 443) you browse on; anything else is refused even if it resolves here, which stops a hostile site pointing a name it controls at your host and driving Docker through your browser.

⁠Starting over

Credentials → Danger zone → Delete everything removes the whole installation on this machine: every service, all data volumes, and the generated database and broker passwords. It asks you to type DELETE first, and keeps your license key so you can set Fuuz up again. There is no undo and it does not consult your backups — download one first if any of the data matters.

Use it rather than removing volumes by hand: the passwords and the data have to go as a set, because old data volumes paired with newly generated passwords cannot start, and that failure looks nothing like its cause.

⁠Image tags

Tags follow {channel}-{version}, with calendar versioning (YYYY.M.patch). Every channel also publishes a {channel}-latest tag pointing at its most recent release.

Pin Settings → Images → Image tag to a specific version to keep an installation on a known release; leave it on a -latest tag to move forward whenever you re-deploy. Keep the launcher's own image on the same channel as that setting.

While in-house Fuuz is in beta, trial-latest moves often — usually what you want during an evaluation, since fixes reach you without asking. Pin the version instead if a machine has to stay exactly as you left it. Take a backup before any update.

⁠Getting help

When you contact Fuuz, include:

• What the launcher's Overview page shows — the headline, and which services are not running.
• The launcher's log (docker logs fuuz-launcher), the text of any stage that failed, and the logs of any failing service.
• Your Image tag setting, and the output of docker version.

Never send your license key or the contents of the Credentials tab unless Fuuz asks for them specifically.

• Sales and licensing: [email protected]⁠
• Fuuz: www.fuuz.com⁠