VISULOX 5 Documentation
5.0.3 5.0.2 5.0.1
5.0.3 5.0.2 5.0.1

Repair Setup for Visulox Portal

Purpose

The repair-setup command lets a system administrator fix specific, known-bad setup configuration on a Visulox Portal host without hand-editing the database or reinstalling the server.

Use it when a wrong value captured during installation — most commonly the hostname — leaves the Portal partially or fully unreachable, so the Dashboard cannot be used to correct the configuration.

The command connects to PostgreSQL directly (like the config CLI) and works even when the Portal HTTP service is down.

Related article: For post-repair validation, see Health Check for Visulox Portal.

When to use

  • Installation or first start failed because the hostname or related setup values are wrong.

  • The Portal UI or Dashboard is unavailable, but the host and database are still reachable.

  • Emulator or session launch fails with NGINX host-resolution errors after a hostname change that was not applied everywhere.

  • You need a supported, guided recovery path instead of manual database or config edits.

Permissions

Run the command with effective user ID 0. On an installed Portal host:

Bash
sudo /opt/visulox-portal/bin/vlx-portald repair-setup update-hostname

The sudo check runs before Portal configuration is loaded or a database connection is opened.

Prerequisite: Real DNS for the new Hostname

Before repairing a hostname, ensure the new hostname has a real DNS record. The command cannot create DNS.

Bash
dig +short <new-hostname> @<your-dns-server>

An /etc/hosts entry alone is not sufficient. NGINX resolves emulator session targets through its own resolver and never reads /etc/hosts. If the name exists only in /etc/hosts, the Dashboard may look fine but sessions fail with HTTP 502 and errors such as <hostname> could not be resolved in /var/log/nginx/error.log.

The command warns when a hostname appears to resolve only via /etc/hosts. Do not ignore that warning.

Command hierarchy

  • repair-setup

    • update-hostname

      • --hostname <new-hostname>

      • --old-hostname <previous-hostname>

      • --yes

Additional repair operations may be added as sibling subcommands under repair-setup in future releases.

Bash
sudo /opt/visulox-portal/bin/vlx-portald repair-setup update-hostname --help

If the default config file is not detected, pass the global config flag:

Bash
sudo /opt/visulox-portal/bin/vlx-portald --configFile /opt/visulox-portal/configs/config.json repair-setup update-hostname

What update-hostname updates

The repair identifies stale values that still hold the previous hostname and updates every layer that duplicates hostname identity at setup time, including:

  • OS hostname (hostnamectl)

  • Visulox configuration keys in vlx-core (authoritative) and the Portal mirror

  • portal_server, connector_server, and app_server rows where hostname, DNS name, or address matched the old value

  • directory_tree entries for portal, connector, and application server objects

  • Portal and Connector config.json hostname-related fields

  • Connector NGINX includes (refresh and reload)

  • Loki log host labels when configured

  • vlx-core cluster FQDN via visulox cluster set fqdn when vlx-core is installed on the host

Each step after the confirmation prompt reports its own outcome. Non-fatal failures are warnings with guidance; fatal validation failures abort before any change is made.

Flags

Flag

Meaning

--hostname

New hostname. Skips the interactive prompt when provided.

--old-hostname

Previous hostname to match stale records against. Required to re-run safely after a partial failure (see below).

--yes

Assume yes for every confirmation prompt. Required for unattended runs: without --yes, a non-TTY invocation still blocks on Continue?.

Interactive example

Bash
sudo /opt/visulox-portal/bin/vlx-portald repair-setup update-hostname
Current hostname: vlx-old.example.com
Enter new hostname: vlx-new.example.com
Checking hostname...
✓ Hostname is valid
✓ DNS resolution successful
The following configuration will be updated:
- System hostname
- Portal configuration
- Related internal configuration
Continue? [y/N]: y
Updating configuration...
✓ Hostname updated
✓ Configuration updated
✓ Required services restarted
Setup repaired successfully.

Non-interactive usage

Bash
sudo /opt/visulox-portal/bin/vlx-portald repair-setup update-hostname --hostname vlx-new.example.com --yes

Re-running after a partial failure

Stale records are matched using the previous hostname, but the OS hostname is changed early in the run. If a later step fails, the machine may already show the new hostname, so a plain re-run would match nothing.

Bash
sudo /opt/visulox-portal/bin/vlx-portald repair-setup update-hostname --hostname vlx-new.example.com --old-hostname vlx-old.example.com

Re-running is safe: records are rewritten only when they still hold a recognized old value.

vlx-core

When vlx-core is installed on the host, the repair updates the recorded peer FQDN with:

Bash
visulox cluster set fqdn -fqdn <new-hostname>

The vlx-core logical name is never renamed; only the announced address is updated. The repair runs this step before changing the OS hostname, then restarts vlx-core.

If set fqdn fails because the new name does not yet resolve to this machine, the repair continues and prints the manual command to run once DNS is in place:

Bash
cd / && sudo visulox cluster set fqdn -fqdn <new-hostname> && sudo visulox stop && sudo visulox start

Failure behavior

  • Everything before the confirmation prompt is read-only. Validation failure or declining confirmation leaves the system untouched.

  • If rewriting a directory_tree DN would collide with an existing row, the command aborts before writing anything.

  • If configuration writes fail after the OS hostname was changed, the OS hostname change is rolled back automatically.

  • Once the OS hostname and Portal DB-backed config succeed, later steps (Connector config, NGINX, service restarts, vlx-core) are best-effort warnings and do not undo the applied fix.

Verification

After a repair:

Bash
hostname
hostname -f
/opt/visulox-portal/bin/vlx-portald health-check -c /opt/visulox-portal/configs/config.json

Confirm:

  • hostname and hostname -f show the new value.

  • The health check reports healthy sections.

  • Any warnings from the repair command (especially vlx-core or service restart) are addressed.

  • A user can launch an application or emulator session from the Dashboard — the end-to-end proof that DNS and configuration are consistent.