RAY Unified Installer — CS Engineer Manual

Server

The Server Agent runs on one representative PC and is the hub you configure and operate from.

1. Install the Server Agent

1. On the representative PC, run RAY-Unified-Installer-server-setup.exe (or ray-server-agent install) → start.
2. Confirm residency at http://127.0.0.1:8096/health.

2. Initial CS Console setup

1. Open http://127.0.0.1:8096/cs/ in a browser.
2. Set a fixed password (8+ characters) — used for console access thereafter (stored as a hash).
3. Set the country code — the basis for the per-country latest-version policy. If unset, auto-estimated: saved setting → IP → timezone → KR.

3. Site configuration — the key step

1. In the SW tab, review each SW's Cloud version / Local version.
2. Select the SW and versions this hospital will use — RAYTeams appears at the top of the list marked "Required" and cannot be excluded (if you leave its version unset, the latest cloud version is applied).
3. Save → done. The selection is stored on the Server and becomes the basis for all Client deployments.

The "Current version" column — this column shows the version pinned in the site configuration, not the version installed on that PC. An SW with no version pinned yet shows "Not configured" (regardless of whether it is installed).

How installation follows — saving the site configuration only decides what to use; the actual install path differs by target PC.

So the order is pick versions in the site configuration → save → (install from the SW list on the representative PC / deploy from Clients to clinical PCs). RAYTeams is no exception: being in the site configuration does not install it — you still have to run a deployment.

4. Deploy to Clients

1. In the Clients tab, select the target Client(s).
2. The SW in the site configuration is sent in sequence → the Client Agent performs a silent install.
3. Any running target app is force-closed (with warning) before install. The Server itself (self) can be an install target.

5. Deployment jobs & monitoring

Track deployment progress in the Jobs view.

What you can see

Jobs aggregation is per deployment job. To see how far the whole site has progressed (all PCs × all SW), use the SW deployment status view (added in v1.2.0). You can read the coverage rate without opening each PC one by one.

Installation progress percentages are not shown. Vendor installers report progress inconsistently, which produced unreliable numbers, so status is shown only as pending / in progress / success / failed.

6. SW install/update model

• Every managed SW is always (re)installed from a Full package.
• .exe/.msi is executed directly; .zip is extracted and the inner Setup.exe is run.
• Download integrity is verified with SHA-256 (mandatory when provided).

If a download fails

• Resume is supported (v1.2.0). When a transfer is interrupted it continues from the bytes already received, so a multi-GB package is not downloaded again from scratch.
• Short outages recover automatically (v1.2.0). On the clinical PC↔Server leg the Agent retries every 10 seconds, up to 6 times, and each attempt resumes from what is already on disk. No one has to re-run the deployment.
• If the retry limit is exceeded, that PC's deployment is marked failed → redeploy to that PC. It still resumes from the bytes already received.
• Partially downloaded temporary files are kept on purpose, so the transfer can resume. Only a verified file is renamed to its final name, so an incomplete file is never used for installation.
• The Server↔cloud leg retries automatically, up to 3 times. That leg cannot resume — the distribution CDN does not support range requests — so it re-downloads in full.
• There is no cap on total elapsed time — a multi-GB download over a slow link is never cut off for taking too long. However, if no data arrives at all, the connection is treated as dead and dropped (20 seconds on the in-clinic leg, 3 minutes on the internet leg). On the in-clinic leg the automatic retry above then takes over.

Rolling back to a lower version (downgrade)

• The Installer does not compare version order; it runs the installer for exactly the version you specify. It neither blocks a downgrade nor guarantees one.
• Whether a lower version actually installs depends on that SW's own installer policy. When a higher version is already present, many installers simply do nothing and exit (the installer window appears, but the version is unchanged).
• Recommended procedure: uninstall the existing version first, then install the target version.
• The case where nothing was actually installed but the job still showed success was corrected in v1.2.0. Even so, an installer that exits silently cannot always be distinguished, so verifying the actually installed version after a downgrade is still recommended.

Reboot after installation

• The Installer never reboots a PC automatically.
• If an installer reports "reboot required" through the standard mechanism, the Jobs view shows "Success — reboot required". However, many vendor installers never send that signal, so the absence of that message does not mean a reboot is unnecessary.
• After deploying several SW at once, we recommend rebooting the target PC once as standard procedure.

7. File deployment (added in v1.2.0)

Register the environment files from a reference PC on the server, then push them to the PCs you select in one go. This replaces the work of visiting each PC to copy files by hand.

This feature does not know anything about the SW. It moves the files you specify to the location you specify. Which parts of a given SW's settings are synchronised to a server and which are stored per PC is that SW's own concern, and this feature does not take part in it. It therefore does not perform "settings backup/restore" or "version compatibility" handling.

Procedure

1. In the CS Console File deployment menu, register a source folder. Its contents are stored on the server.
2. Select the target PC(s) and run the deployment.
3. Results are shown per PC.

Things to know

Close the apps on the target PCs before deploying and the run finishes in one pass, with no skipped PCs.

8. Per-PC SW install options (added in v1.2.0)

Specify per PC the cases where the same SW has to be installed differently on different machines (server configuration, 3D viewer, and so on).

Procedure

1. Open the target PC on the Clients screen.
2. Select the additional install options per SW and save.
3. From the next installation onward, those options apply to that PC only.

Things to know

If the option list does not appear — the list comes from the SW catalogue. It means the options for that SW are not registered in the catalogue yet; once they are, they appear automatically without reinstalling the Agent. Contact HQ (Platform Development Team).

9. Staging installers in advance (the packages folder)

When the site's internet link is slow, or you want to bring large installers with you, drop the installer files into the Server's packages folder. They then appear in the version picker as a Local · vVERSION option and are installed from that file instead of being downloaded again.

Procedure

1. Open C:\Ray\RAYSWInstaller\packages\ on the representative PC (Server).
2. Copy the installer files directly into the top level of that folder.
3. Press Refresh in the CS Console site-configuration (or setup wizard) screen.
4. When Local · vVERSION appears in that SW's version picker, select it and save.

Rules — follow these or the file will not be picked up

What about fully offline sites? This only removes the installer download. Listing the SW and resolving latest versions still requires internet on the Server. For sites with no internet at all, contact HQ (Platform Development Team). An offline bundle containing the software itself is not currently provided.

10. Existing environment (hospital with individual SW already installed)

• SW you include in the site configuration: the center (Installer) now manages the version; that SW's individual auto-update defers to central management.
• SW you do not include: leave the existing mechanism as-is.
• Deploy outside clinic hours (running apps are force-closed). File-lock/process contention is tolerated; a reboot-then-retry is most reliable.

11. Server troubleshooting

• Server PC failure (replacement) — no automatic failover. Install the Server Agent on a new representative PC, restore the site configuration → re-point each Client to the new Server IP.
• CS Console unresponsive / many "Failed to fetch" — likely browser connection-pool exhaustion, not a dead server. Check http://127.0.0.1:8096/health in another tab; if alive, refresh/clean up tabs.

Client

The Client Agent runs on each clinical PC and installs software as instructed by the Server.

1. Install the Client Agent

1. Verify connectivity: ray-client-agent ping --server=http://<ServerIP>:8096
2. Install: ray-client-agent install --server=http://<ServerIP>:8096 → start
3. The Client then polls the Server every 30 seconds.

After installation, the Client screen on that PC shows the connected Server address and connection status. If the Server address changes, re-point it with Server IP 변경 (Change Server IP) on this screen.

1-1. Giving a PC an alias (added in v1.2.0)

Give each PC a name you can recognise. Consulting room 2 instead of DESKTOP-4F8K2A means you will not pick the wrong target when deploying.

• Enter it on the initial setup screen, or set it later in the CS Console.
• It can be edited from either side; the most recent change wins.
• If no alias is set, the PC name is shown as-is.

2. Where downloaded installers are stored

Installer files the Client pulls from the Server are kept on that PC at:

C:\Ray\RAYSWInstaller\data\client-cache\binaries\<SW>\<version>\<original installer file name>

• While downloading, the file is written to the same folder as a temporary .incoming.bin; once complete and verified, it is renamed to the original file name.
• If the download fails, the temporary file is deleted automatically.
• What is currently downloading, and how far along it is, can be seen in C:\Ray\RAYSWInstaller\jobs.json.
• This folder exists so already-downloaded files can be reused. You may delete it to free disk space — the files will simply be downloaded again on the next deployment.

3. Full removal

• uninstall removes only the Windows service. The tray helper (auto-start registry), firewall rule, and data\ / packages\ / install folder remain.
• Full removal is manual (delete service → close tray & clean registry → delete firewall rule → delete folders). Request the HQ removal script if needed.

5DI (5D special environment)

New to 5D? What this work actually does

A 5D environment ties the hospital's PCs and devices (CT, RAYFace scanner) together into one clinical network so they can exchange data. Without this step, the software on each PC is merely installed — the machines do not know about one another.

At a 5D site a CS engineer has two jobs, in a fixed order.

You cannot do ② before ①. The 5DI Config screen works by talking to the local service that RAYTeams provides on each PC, so a PC only appears in the list once RAYTeams is installed and running on it.

Why RAYTeams is required: the component that actually applies the 5D configuration and licenses is the local service built into RAYTeams. The CS Console is only the screen that instructs it. The CS Console (browser) calls those local services directly — localhost:8008 for the local PC, http://{ip}:8008 for remote ones.

Step by step

Step 1 — Review the PC list

Opening the screen auto-lists the PCs on the network that are running RAYTeams. Each PC card also shows the devices (serial numbers) attached to that PC.

• A PC that should be listed is missing: check its power, network and whether RAYTeams is running, then Refresh.
• A device is not auto-detected: use Register device to enter the serial and pick the PC it is attached to.
• A wrongly registered device can be deleted from the card.

Step 2 — Assign roles (CT server / RAYFace server)

Select the PCs to group, then assign a role on each PC card.

The two roles are independent axes, so depending on the site one PC may hold both roles, or they may be different PCs. If an assignment is missing or more than one PC is assigned, the reason is shown at the top of the screen and you cannot continue.

Step 3 — Group the network

With the target PCs checked, run Group network. On a site that is already configured, the button reads Re-group.

Step 4 — Apply settings & licenses

Pressing Apply settings/license raises a second prompt, "Confirm apply?" (two-step confirmation against mis-clicks). Confirm, and the settings and licenses are applied to each PC.

Step 5 — Reboot

Once applied, each PC must be rebooted for the settings to take effect. The screen shows a reboot notice; skipping this step makes it look as though nothing was applied.

If a PC shows as unreachable — resolve that PC's connectivity/firewall problem first, then Retry. If only some PCs fail, the rest are still applied normally.

The "5DI Config" menu is not showing

The menu is conditional. It appears only when RAYTeams is installed AND its local service is running (i.e. the Console can reach localhost:8008). If RAYTeams is installed but has never been launched, that local service is not up yet, so the menu stays hidden — this is normal, not a bug.

To make it appear:

1. Launch RAYTeams once on that PC (this starts its local service on port 8008).
2. Refresh the CS Console in the browser. The "5DI Config" menu now appears.

If it still does not appear after launching RAYTeams and refreshing, the RAYTeams local service is not responding on port 8008 — check that RAYTeams is actually running and that no firewall/other software is blocking the local port.

For existing 5D Installer users

The legacy 5D Installer is no longer used — support has ended (it can still be run).

The legacy 5D Installer separated ① SW installation from ② 5D configuration / license application. From now on:

• ① SW installation — use Ray Unified Installer (this product).
• ② Configuration / license application — use this 5DI Config screen.

Step ② works exactly as it did in the legacy 5D Installer. All features are the same; only manual Client addition is not supported (use the automatic load of PCs on the network).

In short: in a 5D environment, install SW with Ray Unified Installer and apply 5D configuration/licensing in 5DI Config.

FAQ & Field Guide

Written for use on site, no technical background needed. Check this tab first when something looks wrong.

Pre-deployment checklist

Server (the designated PC)

• One PC on wired network with permanent power, fixed as the Server
• CS Console reachable and the password set
• Country set explicitly (do not rely on auto-detection)
• SW list and versions for this clinic confirmed and downloaded
• A slot outside clinic hours secured (running apps are closed during install)

Client (treatment PCs)

• Power and network stay connected (disable sleep / hibernate)
• A user is logged on (recommended — installs run on the logged-on user's desktop)
• Enough free disk space (large SW needs several GB, plus room to unpack)

Network & security (both sides)

• Is inbound TCP 8096 allowed on the Server? (added automatically at install time, but hospital security policy can override it)
• Can the Server reach the internet over HTTPS 443?
• Does ray-client-agent ping --server=http://<ServerIP>:8096 succeed from each clinical PC?
• Has C:\Ray\RAYSWInstaller\ been excluded from real-time antivirus scanning? (especially recommended where large SW is deployed)
• Does any SW you are about to install require a firewall exception of its own? (the 8096 item above covers Agent traffic; see each SW's own guidance for its requirements)
• See "Network, firewall & antivirus pre-checks" on the Overview tab for details

Recommended order on deployment day

1. Pilot on a few PCs — deploy to 1–2 PCs first and confirm Add/Remove registration and launch
2. If clean, roll out to all PCs
3. Confirm completion for every PC on the Jobs screen
4. Actually launch one or two key SW titles (install complete ≠ verified working)
5. Re-deploy only to the PCs that failed
6. Reboot each target PC once — some titles only work correctly after a reboot, even when no reboot prompt appeared

FAQ — installing and deploying

Q. How long does a deployment take?
It varies widely by SW. Small titles take tens of seconds, large ones several minutes. A 4 GB package adds download and unpack time on top. Deploying several titles at once takes the sum of them.

Q. Are SW titles installed in parallel?
No. They install one at a time, in order. The next title starts only after the previous one finishes — this prevents vendor installers from colliding.

Q. Can I deploy during clinic hours?
Not recommended. Target SW that is running will be closed, and some titles may require a reboot. Deploy outside clinic hours.

Q. Does a user have to be logged on to the PC?
Recommended. Installs run on the logged-on user's desktop with administrator rights. With nobody logged on, the install is attempted in the background and results can vary by SW. Deploy with a user logged on for predictable results.

Q. Can I deploy while connected over Remote Desktop (RDP)?
Yes. A remote session is recognised as the target session, so remote administration works as-is.

Q. Does a black command window appear during install?
No. Installs run without showing a window. If a particular SW's own installer is built to show a screen, that SW's screen may appear.

Q. Completion is not shown immediately — did it fail?
No. Completion is reported only after the installer program has fully finished. Files may appear early while the install is still running. For large SW, several minutes of "installing" is normal.

Q. The PC was shut down or rebooted mid-install.
That title may be left half-installed. Deploy to that PC again — re-installing the same title is safe.

Q. Can I re-deploy SW that is already installed?
Yes. Deployment always fetches the full package and re-installs, so re-deploying is also the repair procedure.

Q. Can I install to a single PC only?
Yes. Select just that PC on the Clients screen and deploy.

Q. What happens if a download is interrupted?
The partially downloaded temporary file is kept so the transfer can resume. Only a verified file is renamed to its final name, so an incomplete file is never used for installation. The clinical PC↔Server leg retries every 10 seconds, up to 6 times, resuming from what is already on disk (v1.2.0). If the limit is exceeded that PC's deployment is marked failed — just redeploy to that PC, and it will resume. The Server↔cloud leg retries automatically, up to 3 times.

Q. Is resume (continuing from where it stopped) supported?
Yes, from v1.2.0. It works on the in-clinic leg (clinical PC ↔ Server): after an interruption, the next transfer continues from where it stopped. Short outages are recovered by automatic retry, so in most cases no one has to intervene. However, the leg where the Server downloads from the cloud (internet) cannot resume — the distribution CDN does not support range requests. On sites with unstable internet links we still recommend staging large installers in the packages folder in advance (see the Server tab).

Q. A download has been running for hours — has it failed?
There is no cap on total elapsed time, so a multi-GB download over a slow link is normal. If no data arrives at all, the connection is dropped (20 seconds on the in-clinic leg, 3 minutes on the internet leg). The in-clinic leg then resumes via automatic retry, so a brief "retrying" followed by continued progress is normal.

Q. Can I roll back to a lower version (downgrade)?
The Installer does not compare version order; it runs the installer for exactly the version you specify. However, many vendor installers refuse a downgrade (the installer window appears but the version stays the same). Uninstall the existing version first, then install the target version. Also note the deployment job may still show success in this case, so always verify the actually installed version afterwards.

Q. Is a reboot required after installation?
The Installer never reboots a PC automatically. If an installer reports "reboot required", the Jobs view shows "Success — reboot required" — but many titles never send that signal. The absence of that message does not mean a reboot is unnecessary, so reboot each target PC once after a batch deployment.

Q. Will installation work if the clinical PC account is not an administrator?
Yes. The Agent runs with administrator rights, so installation proceeds even when the logged-on account is a standard user (it falls back to a background install). Some vendor installers need a visible desktop, though, so we recommend having an administrator logged on at least during the deployment window.

FAQ — status and display

Q. A Client shows as offline (stale).
Check that PC's power, network and Agent. If power and network are fine but it stays offline, restart the Agent service on that PC and wait about a minute.

Q. It says complete, but nothing appears in Add/Remove Programs or on the desktop.
Some titles never create a desktop icon and register only in the Start menu (RAYTeams, for example). If it is missing from the Start menu too and will not launch, contact HQ with that PC's Agent log.

Q. The version does not go up.
Check which version is actually installed on that PC first. If it stays the same after re-deploying the latest version, contact HQ with that PC's Agent log.

Q. A job stays "installing" for a long time.
Normal for large SW. If it stays that way for more than 30 minutes, contact HQ with that PC's Agent log.

Q. SW is still listed after deployment.
Refresh the screen first. If it remains, that title's install may not have finished.

Q. I uninstalled the SW, but the Clients list still shows it as installed (green).
Installed-state detection does not read Windows Add/Remove Programs. It reads a designated file belonging to that SW and takes its version. So the entry stays green when:

1. the uninstaller left that file behind,
2. another copy is installed elsewhere (for example a manual installation predating the Installer), or
3. a hotfix build carries the same version number as the official build.

The display refreshes every 30 seconds, so if it persists past that, it is one of the three above. Check whether files remain in that SW's install folder; if the cause is unclear, send HQ that PC's Agent log, the file listing of the install folder, and whether an Add/Remove Programs entry exists.

Q. Can I tell a hotfix build apart from the official build after installation?
Not when both carry the same version number. Installed-version detection reads the executable's version information, so a hotfix built with the same version looks identical on screen. If you apply a hotfix in the field, keep a separate record of it. (We are working with each SW team on giving hotfixes distinct version numbers, and considering a deployment-history display in the Installer.)

FAQ — environment and settings

Q. The Server PC's IP changed.
Every Client needs the new address. Re-point the server address on each Client PC. If the IP changes often, use a static IP for the Server PC.

Q. I forgot the console password.
It can be reset on that PC using the reset procedure (HQ-provided script). It cannot be reset remotely.

Q. The link is slow, or I want to bring large installers with me.
Copy the installer files into the top level of C:\Ray\RAYSWInstaller\packages\ on the representative PC beforehand. After a refresh they appear in the version picker as Local · vVERSION and are not downloaded again. See "Staging installers in advance" on the Server tab for the rules.

Q. The clinic has no internet at all.
The approach above only removes the installer download. Listing the SW and resolving latest versions still requires internet on the representative PC, so contact HQ for a fully offline site. An offline bundle containing the software itself is not currently provided.

Q. I want to install SW that is not in the list.
It cannot be added on site. The managed SW list is decided by HQ — raise the request with HQ.

Q. I set the wrong country.
Change it on the settings screen, then confirm the SW list and versions switched to the new baseline.

Q. Can Server and Client be installed on the same PC?
No. They cannot coexist on one PC. To install SW on the Server PC itself, use its own entry on the Clients screen.

Q. Does the Agent update itself?
Yes. Both Server and Client update automatically. Allow up to about an hour for it to take effect.

Q. What do I need to open on the firewall?
On the Server (designated PC): inbound TCP 8096 and outbound HTTPS 443. Clinical PCs need no inbound rule for the Agent — only outbound 8096 to the Server. This covers the Unified Installer's own traffic; firewall exceptions required by the managed SW are separate — check that SW's configuration guidance. The 8096 rule is added automatically when the Server is installed, but hospital security policy can override it, so verify. The list of cloud addresses to allow is on the Overview tab under "Network, firewall & antivirus pre-checks".

Q. Do I need to add antivirus exclusions?
Official release Agents are code-signed, so usually not. On sites handling large SW, however, we recommend excluding C:\Ray\RAYSWInstaller\ (especially packages\) from real-time scanning — a scanner holding an installer file open can make installs slow or fail.

Q. Where are downloaded installer files stored?
On the Server, in C:\Ray\RAYSWInstaller\packages\ under their original file names; on clinical PCs, in C:\Ray\RAYSWInstaller\data\client-cache\binaries\<SW>\<version>\. You may delete these to free disk space — they will be downloaded again on the next deployment.

Send this when contacting HQ

Accurate material makes diagnosis dramatically faster.

1. Symptom and time (e.g. "Aug 7 around 14:20, deployed RAYFace to PC A, shown complete but will not launch")
2. Target PC, SW and version (a Clients screen capture is enough)
3. Agent log file — from C:\Ray\RAYSWInstaller\logs\ on that PC, the file for that date
4. CS Console captures — the Jobs and Clients screens
5. What you already tried (re-deploy, reboot, …)
6. When the displayed status disagrees with reality — the file listing left in that SW's install folder, whether an Add/Remove Programs entry exists (and the version it shows), and the Server's C:\Ray\RAYSWInstaller\packages\index.json

The log file matters most. It records when each install started, when it ended and what the result was, so the cause can be narrowed down without guesswork.