Linux: Linux and container deployment
Select the package for the target architecture and verify persistent directories, network endpoints and runtime services.
Native Linux installation
Use the Linux package matching x86_64 or aarch64.
- Verify the package and SHA-256 sidecar, extract it and run sudo bash install.sh in the package directory.
- Specify the role and root with --profile and --install-root; defaults are full and /opt/hqcontrol. Prepare the Python interpreter required by the installation guide. The installer checks the script environment and deploys offline dependencies.
- Script execution requires the installer checks for bubblewrap, prlimit, runuser and user namespaces to pass. Install missing prerequisites reported by setup, then rerun it.
- After installation, run sudo hqcontrolctl status and sudo hqcontrolctl health to verify service and readiness states.
Service inspection and maintenance
Native Linux uses systemd to supervise the runtime services separately.
- Use sudo hqcontrolctl logs app, logs io, logs alarm, logs trend or logs script for service logs. Use ports for listening endpoints.
- Use the management commands supplied with the installation package. A whole-unit restart affects runtime and data services and requires a maintenance window.
- After startup, check Portal, Screen, license, device quality and archive recovery before resuming operations.
Container deployment and persistence
Use the release container definition and its matching image.
- On Linux/macOS, run ./hqcontrol.sh install in the release directory, then ./hqcontrol.sh status. On Windows, use hqcontrol.ps1. The offline package contains the required images.
- Prepare configuration, certificates and persistent volumes as described by the release. Persist settings, user screens, scripts and database data.
- Expose the configured Portal and Screen HTTPS endpoints. Internal data-service ports are not client addresses.
- After startup, inspect service readiness in System Status, then check device connectivity, quality and screens. Back up persistent data before image updates and preserve existing volumes according to the release instructions.
