1. Before you start

What the server needs, the accounts this guide uses, and what to know if OpenHDS runs on the same machine.

1.1 The server machine

The tablets are given the server's address once, so it must not change. The tablets and the console reach the server over plain HTTP, which is not encrypted: keep it on a network you trust and never open it to the internet.

1.2 Accounts and passwords

Every site uses the same accounts for the user acceptance test:

Before the server holds real data, change every one of these passwords.

1.3 What you need ready

• A Windows account on the server that is a member of Administrators.
• The server's fixed address.
• The setup program of chapter 2 and the release pack of chapter 3. Both download in a browser.

1.4 Installing next to OpenHDS

Setup leaves OpenHDS untouched. Install as in chapter 2, then open OpenHDS as the site always does and sign in.

If a port HDS-Explorer wants is taken, setup picks the next free one, for example 8082 instead of 8081. To see or change the ports, tick Change advanced settings on the Site details page. If yours differ from this guide, use yours in every address.

2. Install

One program installs Java 17, Tomcat 9, MySQL 8.4, the HDS-Explorer server and the tablet app the server gives to tablets. Tomcat and MySQL run as Windows services that start with the machine.

2.1 Download setup

In a browser, download HDS-Explorer-Setup-1.0.0-build7.exe (344 MB) and copy it to the server. The server needs no internet during the install.

2.2 Run it

Sign in to Windows as a member of Administrators and double-click the file.

1. Windows asks whether setup may make changes: Yes.
2. If Windows says it protected the PC, choose More info › Run anyway.
3. The machine check lists what is already on the computer, such as OpenHDS. Nothing is changed. Next.
4. On Database, keep Install a separate MySQL for HDS-Explorer. Next.
5. On Site details, fill in:

1. Next, check the choices, then Install. It takes 5 to 10 minutes.

If a step fails, run setup again: it continues from there. If it stops again, send C:\hdsx\logs\install.log to your support contact.

2.3 Finish

The last page shows the address for the console and the tablets. Write it down. Keep Open the console now ticked and choose Finish.

If the page says the network is Public, tablets cannot reach the server yet. In PowerShell opened as Administrator, change it to Private, using the InterfaceAlias the first line prints:

Get-NetConnectionProfile | Format-Table InterfaceAlias, NetworkCategory
Set-NetConnectionProfile -InterfaceAlias Ethernet -NetworkCategory Private

3. First sign-in

3.1 Download the release pack

In a browser, download release-pack-standard-2.zip and keep it where you can find it. It holds the standard forms, which chapter B of Using HDS-Explorer imports.

3.2 Check the server is up

On the server, open http://localhost:8081/hds-explorer-server/health. When the server is ready it shows "status":"UP" and 1.0.0 build 7. After a restart this takes a few minutes.

3.3 Sign in

On any computer of the site network, open http://<server address>:8081/hds-explorer-server and sign in as admin with Change-me-1.

The console asks for a new password. Type Change-me-1 in Current password, then Hdsx-admin-1 twice, and choose Save. The console opens on the Dashboard.

The next step is Using HDS-Explorer, chapter B (Site setup).

4. Running the server

4.1 Stop and start

The server is two Windows services, MySQL84 and Tomcat9. Both start with the machine. To restart one, open Services (services.msc), right-click the service and choose Stop, Start or Restart. Stop Tomcat9 first and start MySQL84 first.

The server takes a few minutes to come back. The health address of chapter 3.2 says when it is ready.

4.2 If the server does not come back

If every address answers 404 Not Found, or the Tomcat service fails with Error 1068, Tomcat started before MySQL was ready. Start MySQL84 if it is stopped, then restart Tomcat9. If MySQL does not start, read the newest .err file in its data folder under C:\hdsx.

4.3 What to send when asking for help

1. C:\hdsx\data\logs\server.log. It holds only errors, so an empty file is good news.
2. The newest tomcat9-stderr file in C:\hdsx\tomcat-9\logs.
3. What was done, on which page or tablet, and at what time.

5. Backup and upgrade

Run every command in PowerShell opened as Administrator.

5.1 A daily backup

Run this once. It backs up the database every night at 22:00 into C:\hdsx\backups and keeps 14 days.

New-Item -ItemType Directory -Force C:\hdsx\backups | Out-Null
$pw = (Select-String -Path C:\hdsx\credentials.txt -Pattern '^database_password=(.*)').Matches.Groups[1].Value
"[client]`r`nhost=127.0.0.1`r`nport=3307`r`nuser=hdsx_app`r`npassword=$pw`r`n" | Set-Content -Encoding ASCII C:\hdsx\backups\backup.cnf
icacls C:\hdsx\backups\backup.cnf /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F"
@'
$dir  = 'C:\hdsx\backups'
$file = Join-Path $dir ("hds_explorer_db-" + (Get-Date -Format yyyy-MM-dd_HHmm) + ".sql")
& C:\hdsx\mysql-8.4\bin\mysqldump.exe --defaults-extra-file="$dir\backup.cnf" --single-transaction --routines --triggers --no-tablespaces --default-character-set=utf8mb4 --result-file="$file" hds_explorer_db
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
Get-ChildItem $dir -Filter 'hds_explorer_db-*.sql' | Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-14) } | Remove-Item
'@ | Set-Content -Encoding ASCII C:\hdsx\backups\backup.ps1
$action  = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument '-NoProfile -ExecutionPolicy Bypass -File C:\hdsx\backups\backup.ps1'
$trigger = New-ScheduledTaskTrigger -Daily -At 22:00
Register-ScheduledTask -TaskName 'HDS-Explorer backup' -Action $action -Trigger $trigger -User 'SYSTEM' -RunLevel Highest
Start-ScheduledTask -TaskName 'HDS-Explorer backup'

After a minute, C:\hdsx\backups holds a .sql file. At least once a week, copy the newest file to another machine or an external disk.

5.2 Bring a backup back

This replaces the whole database: everything recorded after the backup is lost.

1. Fill in the backup's file name. The second command asks for mysql_admin_password from C:\hdsx\credentials.txt.

   $file = 'C:\hdsx\backups\hds_explorer_db-<date>_<time>.sql'
   Stop-Service Tomcat9
   & C:\hdsx\mysql-8.4\bin\mysql.exe -h 127.0.0.1 -P 3307 -u root -p -e "DROP DATABASE hds_explorer_db; CREATE DATABASE hds_explorer_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
   cmd /c "C:\hdsx\mysql-8.4\bin\mysql.exe --defaults-extra-file=C:\hdsx\backups\backup.cnf --default-character-set=utf8mb4 hds_explorer_db < `"$file`""
   Start-Service Tomcat9
   

2. When the server is up (chapter 3.2), sign in and run Tablets › Tablet export › Execute all.

5.3 Upgrade

Choose a time when no tablets are synchronising. The server stops for 5 to 10 minutes.

1. Download the new setup program in a browser and run it on the server, as in chapter 2.
2. Setup sees the older version. Press Upgrade.
3. When it finishes, sign in as before.
4. If a new release pack came with it, import it as in Using HDS-Explorer, chapter F (Forms).
5. Run Tablets › Tablet export › Execute all.

Setup backs up the database first and keeps your settings, passwords and data. If the new version does not start, setup puts the old version back and says so.