Maintenance: Server migration, backup, and restore: what must move with the project
Do not migrate a site by copying only the install folder or only the screen files. A formal migration must cover PostgreSQL data, host configuration, screen assets, screen-file history, license records, and handover notes. New hardware requires a new license request.
First decide whether this is an overwrite upgrade or a server move
An overwrite upgrade runs a new package on the same machine and preserves runtime data. A server move installs HQControl on another machine, restores the project data, and confirms licensing again.
- Same-machine upgrade: back up first, run the package for the same architecture, then verify services and screens.
- New server: install HQControl on the new machine instead of starting a copied install folder directly.
- Split deployments: confirm database / app / io roles before moving anything.
- A license file from the old machine is not reused on new hardware; export a new request from
/license.
Core data to back up
The critical data groups are PostgreSQL, host configuration, and screen assets. PostgreSQL carries sites, devices, tags, menus, permissions, alarms, trends, event records, and script configuration. Screen assets live under screens/assets; host-level settings live under config.
- PostgreSQL: the main source for master data, history, permissions, menus, alarms, trends, and script configuration.
- Config directory:
hqcontrol.env, launcher settings, install manifest, and license-service settings.
- Screen directory: exported HTML / SVG / JS / JSON / IMG runtime assets.
- Screen history: upload, publish, restore, and cleanup snapshots from Screen Files.
- Logs are optional but useful for migration diagnosis.
Windows default backup paths
The default Windows install root is D:\HQCONTROL. If D: is not a fixed local disk, the installer falls back to C:\HQCONTROL. Replace the drive letter with the actual install root.
D:\HQCONTROL\config\hqcontrol.env
D:\HQCONTROL\config\hqcontrol.launcher.json
D:\HQCONTROL\config\install.manifest.json
D:\HQCONTROL\data\postgres\
D:\HQCONTROL\data\redis\
D:\HQCONTROL\screens\assets\
D:\HQCONTROL\data\screen-file-history\
D:\HQCONTROL\logs\ # optional diagnosis archive
D:\HQCONTROL\configs\integration-scripts\integration-script\ # when file-based scripts are used
Linux default backup paths
The default Linux install root is /opt/hqcontrol. If the site used INSTALL_ROOT=/data/hqserver, replace /opt/hqcontrol with the actual install root.
/opt/hqcontrol/config/hqcontrol.env
/opt/hqcontrol/data/postgres/
/opt/hqcontrol/data/redis/
/opt/hqcontrol/screens/assets/
/opt/hqcontrol/data/screen-file-history/
/opt/hqcontrol/logs/ # optional diagnosis archive
/opt/hqcontrol/configs/integration-scripts/integration-script/ # when file-based scripts are used
Do not hot-copy the PostgreSQL data directory
Do not casually copy PostgreSQL files while the service is running. Prefer database backup tools. If a cold copy is required, stop HQControl, PostgreSQL, and Redis first, then copy the data directory after all services are fully stopped.
- On Windows, stop HQControl, HQControlPostgreSQL, and HQControlRedis from Startup Settings or Services.
- On Linux, run
sudo hqcontrolctl disable before sudo hqcontrolctl stop so the watchdog does not restart services.
- After restore, start services and confirm the database migration records and System Status.
- Record the old and target versions before migration to avoid schema/application mismatch.
Recommended server move order
Record the old site, install the new server, restore data, then complete licensing and acceptance checks. Do not treat old license files, runtime binaries, or temporary folders as project data.
- Old server: record version, install root,
/settings, /license, System Status, and the current screen root.
- Old server: back up PostgreSQL,
config, screens/assets, data/screen-file-history, and logs if needed.
- New server: install the same or target HQControl version and confirm port 8080 opens.
- New server: restore database and screens, then check PostgreSQL, Redis, public host, and licensing-service settings in
/settings.
- New server: export a new license request from
/license and complete online or offline activation.
- Delivery confirmation: verify System Status, devices, Tag Diagnostics, screen menus, alarms, trends, scripts, and APIs.
Directories that are usually not project backups
Runtime programs and offline dependencies are restored from the installer. Unless you are making a full machine image rollback, keep them out of the project backup package.
bin, web/admin/dist, and modules/packages come from the installer.runtime/python, runtime/postgresql, and runtime/redis are runtime dependencies, not business data.run, temporary folders, and expanded installer folders can be recreated.- Redis is a hot cache and realtime fan-out component; PostgreSQL remains the durable source for master data and history.
Five checks after migration
If the page opens but the project data looks wrong, check these items first. They cover most migration issues.
- The public access address in
/settings still points to the old server.
/license shows unactivated state or old-machine information.- The Screen Files runtime directory contains
screens/assets/<screen-code>/index.html.
- PostgreSQL, Redis, IO State API, Integration Script, and WebSocket are healthy in System Status.
- Key tags pass Tag Diagnostics; if only some tags are bad/stale, use Bad Check instead of marking the entire device failed.
