set up hearthssconsole quickly and reliably. This guide lists required files, installation steps, network settings, and basic tests. It gives direct commands and common fixes. The reader will finish a working HearthsConsole instance by the end.
Key Takeaways
- Setting up HearthsConsole requires a 64-bit server with at least 4 CPU cores, 8 GB RAM, 50 GB disk space, and open TCP ports 8080 and 8443 for network traffic.
- Download the latest HearthsConsole installer and prepare necessary files like the license key, Java 11 or later, and TLS certificates before starting installation.
- Run the install script as administrator, then configure the service by editing the config file with hostname, API address, database credentials, and license path before starting the service.
- Verify the HearthsConsole setup by accessing the web UI on port 8443, checking device and settings pages, and performing API health checks and device command tests.
- Common issues such as port conflicts, database errors, certificate warnings, and device command timeouts can be resolved by following specific troubleshooting steps like verifying ports, credentials, certificates, and network configurations.
- Maintain logs and configuration backups for efficient troubleshooting and seek vendor support with detailed snapshots if problems persist.
What You Need Before You Start (Prerequisites And Downloads)
Hardware and software must meet minimum needs before a user can set up hearthssconsole. The installer must run on a 64-bit Linux or Windows server. The server must have at least 4 CPU cores, 8 GB RAM, and 50 GB free disk. The network must permit TCP ports 8080 and 8443 outbound and inbound. The administrator must obtain the HearthsConsole installer package and a valid license key file.
The user must download the latest installer from the vendor portal. The user must also install Java 11 or later when the build requires it. If the installation will use TLS, the user must prepare a certificate and private key in PEM format. The operator must create a service account with local admin rights to complete configuration steps.
The user should collect these files before they set up hearthssconsole: the installer ZIP, the license file, a JVM binary if needed, and any TLS artifacts. The user should also record the target hostname and a static IP. Finally, the operator should plan a temporary maintenance window. The steps below assume the operator has these prerequisites ready.
Installing HearthsConsole And Completing Initial Configuration
The operator must extract the installer to a local path. The operator runs the included install script as an administrator. On Linux the operator runs ./install.sh. On Windows the operator runs install.bat from an elevated shell.
The installer will prompt the operator for the install directory, license file path, and service port. The operator should enter the license path and choose ports that do not conflict with existing services. The installer will install service files and create a systemd unit or Windows service. The service will not start until the operator completes the initial config file.
The config file resides in /etc/hearthsconsole or C:ProgramDataHearthsConsole. The operator must edit that file to set the external hostname, the API bind address, and database credentials. HearthsConsole supports PostgreSQL and an embedded SQLite for small test installs. The operator should supply a PostgreSQL DSN for production. The operator must add the license key value into the config key called license.path.
If the deployment uses device control commands, the operator may reference a command table for external devices. For example, the system can map M&C commands from an XDS receiver using an official command table XDS command table. The operator should confirm mapping names in the config match the device table labels.
After the operator saves the config, they start the service. The operator runs systemctl start hearthsconsole or starts the Windows service. The operator then check the service logs in /var/log/hearthsconsole or the Windows Event Viewer. The logs will report database migrations and port binding. Once the logs show “service ready” the console will accept web connections.
Connect, Test, And Troubleshoot Common Setup Issues
The tester should open a browser to https://:8443 and load the login page. The installer creates an initial admin user when the service first runs, or it prompts the operator to create one. The tester should log in and open the Devices and Settings pages. The tester should verify that the service lists the configured database connection and reports active health checks.
The tester should run an API health check. The tester calls GET /api/v1/health to confirm status: the endpoint returns code 200 and a JSON payload with status “ok”. The tester should also push a sample command to a connected device to confirm the M&C mapping. The tester should watch the device connection tab for a successful response. If the command fails, the tester should capture the error code from the response body and consult the logs for the same timestamp.
Common Errors And Quick Fixes
Error: service fails to start. Cause: port conflict or missing JVM. Fix: stop the conflicting process or install Java and restart the service. Error: db migration error. Cause: wrong credentials or missing permissions. Fix: verify the DSN, test the database connection with psql or a client, then re-run the migration command.
Error: web UI shows certificate warning. Cause: self-signed or mismatched hostname. Fix: install a certificate that matches the external hostname or add the CA to the client trust store for internal use. Error: device commands return timeout. Cause: firewall or wrong device mapping. Fix: open device ports on the firewall and verify the mapping keys match the external device command table labels.
If the logs contain repeated authentication failures, the operator should rotate keys and reset the admin password from the command line tool. If the operator needs to reinitialize the config, they should back up the config and database, restore defaults, and reapply the license file. If the operator needs vendor support, they should gather logs and configuration snapshots and send them with the service version number. The operator should test again after each change to confirm the outcome.
