Help & operator guide

Set it up with the boundaries intact.

Practical guidance for identity, RouterOS adoption, worker VPS setup, movement, deletion, and account security. Commands that contain one-time credentials must be generated inside your authenticated Master dashboard.

Getting started

The normal installation location on the master is /opt/user-manager. Keep the environment file, named Docker volumes, certificates, backups, DDNS data, host-control state, and tenant configuration outside any public source archive.

  1. Prepare the master VPS, public domain, DNS, and Firebase project.
  2. Install or update User Manager using the package’s documented master commands.
  3. Confirm that the public panel loads through the configured HTTPS domain.
  4. Set the administrator email list in the deployment environment, then sign in with that Firebase identity.
  5. Create a normal user account separately when you want to verify tenant isolation.

Do not run worker-only /opt/um-worker commands on the master unless that machine also has a deliberately separate worker installation.

Firebase accounts

In Firebase Authentication, enable Google and Email/Password sign-in. Add the public panel domain to Firebase Authorized domains. The browser Firebase configuration identifies the project; it is not a substitute for server-side ID-token verification.

Account creation and verification

Choose Create Account, enter an email address and password, and submit the form. Firebase sends the verification email. Open that link, return to Login, and sign in. No custom SMTP server or custom OTP authentication service is required.

Forgot password

Enter the account email on the Login page and choose Forgot password. Firebase sends its official password-reset email. Check spam and follow the Firebase link rather than sending a password to an operator.

Persistent login

A successful sign-in creates a persistent panel session. Suspension, explicit logout, session revocation, account deletion, or a security-setting change can still end access. Clearing browser storage also removes the local login cookie.

MikroTik adoption

  1. Sign in to the workspace that should own the router.
  2. Open Advanced MikroTik Connect and generate the one-line adoption command for that account.
  3. Paste the command into the intended MikroTik terminal and review any RouterOS errors.
  4. Wait for the router to register and establish a fresh WireGuard handshake.
  5. Confirm that the router appears only in the owning workspace and, for Master, under the expected tenant.

Do not reuse an adoption command to move a router between accounts. Tenant ownership and network allocation are part of the adoption record. Existing tunnel addresses must remain unchanged during migration, failover, and worker-reboot restoration.

Connection architecture

The public request path is Cloudflare → master domain/nginx → authenticated FastAPI application. Device Web access then follows the private master-to-worker WireGuard transport and the worker relay to MikroTik. This is separate from direct raw WinBox access.

Standard Cloudflare HTTP proxying does not forward arbitrary WireGuard UDP traffic. Use the deployment’s documented direct endpoint for router and worker tunnels, and do not assume an orange-cloud DNS record supplies UDP forwarding.

The Web button’s current private architecture is intentional. Do not replace it with a public worker relay as an unrelated optimization.

Workers and OVH Cloud VPS

  1. In the Master Command Center, create a worker and generate its one-time join command.
  2. Create a suitable Ubuntu or Debian OVH Cloud VPS with a public IPv4 address.
  3. Run the generated join command as root on that worker, unchanged. It contains worker-specific credentials and must not be posted publicly.
  4. The installer configures the operating-system firewall, WireGuard interfaces, forwarding/NAT settings, and systemd service. It detects and allows SSH before enabling UFW; if SSH cannot be identified safely, UFW enablement is skipped.
  5. Confirm the worker heartbeat, private master transport, capacity, and public UDP reachability in the Master dashboard before moving routers.

Direct public IP

A normal OVH VPS with a direct public IP does not need NAT-style manual port forwarding. The default internal WireGuard UDP ports are 51820 for routers and 51830 for master transport. Existing NAT-style workers remain supported through their explicit mappings.

External OVH Security Groups

The script cannot change OVH Security Groups without provider API access. If you attach an OVH Security Group, allow your SSH port and the required UDP ports there as well. Keep the private relay range closed publicly unless you deliberately enable direct WinBox exposure with the documented option.

Worker movement and recovery

Manual move

On the Master dashboard, find the router, choose Move, select an online owned target worker, and enter an operational reason. The request returns a pending movement state; it does not claim immediate completion.

All adopted siblings in that tenant’s /24 on the source worker move together. The target must have normal capacity available, a healthy heartbeat, and ready private transport. The tenant subnet, tunnel IP addresses, and WireGuard security material are preserved.

Automatic recovery

When a worker exceeds the dead heartbeat threshold, the master evaluates online workers and available recovery capacity. Each router receives its own movement record. Target preparation, tenant assignment, registration, and handshake are separate milestones.

Movement history is retained for one month. For a multi-router tenant group, one recovered router does not mark the entire group recovered.

Verified RouterOS deletion

Deleting an online Advanced Connect router starts a one-shot RouterOS cleanup. The task removes User Manager-managed configuration, reads back the managed artifact inventory, and sends an authenticated completion result only when that inventory is zero.

The dashboard removes the router only after verified cleanup. If the router is offline, unreachable, times out, returns a nonzero remaining count, or cannot provide a valid proof, the router stays in the panel.

  1. Confirm that the router has a healthy Advanced Connect tunnel.
  2. Wait for an active worker movement to finish or resolve before deleting.
  3. Retry only after checking RouterOS reachability and worker/master connectivity.
  4. If cleanup remains incomplete, inspect the managed artifacts on that specific router; do not delete another tenant’s state to clear the error.

Two-step verification

Open Security from your authenticated dashboard. Start authenticator setup, scan the QR code or enter the setup key manually, and confirm a current six-digit code. Store the one-time recovery codes offline before leaving the page.

Email verification proves control of the email address. TOTP two-step verification proves access to the authenticator or an unused recovery code after Firebase authentication. They are separate protections.

Changing or disabling two-step verification revokes other panel sessions. If every recovery method is lost, use the deployment’s controlled administrative recovery process rather than disabling password or token verification.

Safe updates

Use the versioned package’s update.sh from the new source directory and target the existing /opt/user-manager installation. Do not rerun the fresh installer over an established deployment.

The updater is designed to preserve .env, config.py, named volumes, certs/, backups/, ddns/, and host-control state. Never use docker compose down -v as an update step: -v removes named volumes.

Worker agent 0.8.1 is unchanged in this release. No worker-agent refresh is required solely for the v1.9.0 panel and master changes.

The safest next step is the one you can verify.

Return to your dashboard to generate account-specific adoption or worker commands and follow their live proof states.

Login to User Manager