One-Click Web RUM Integration with Rumable¶

Rumable injects the Web RUM script into the HTML returned by a website through Nginx or IIS. It is suitable for websites that can manage their web servers and prefer not to modify front-end source code. The SDK runs in the visitor's browser and reports data directly to Guance OpenWay or a DataKit you configure. The CLI exits after completing the integration; it is not a resident collection service.

For first-time integration, we recommend One-Click Integration, which requires no hand-written configuration. For offline environments or when you want to review each step, use Offline or Manual Installation. See SDK Sources and Loading Modes for SDK sources, loading modes, and a complete TOML example, and Operations for updating and recovering integrated sites. Git, Go, Node.js, and databases are not required for installation or daily use.

One-Click Integration (Recommended)¶

Open the configuration page → Fill in application parameters → Copy the installation command → Run it on the web server → Select the website → Validate the data. You do not need to write TOML yourself or install the CLI in advance. The command downloads, verifies, and installs the CLI for the corresponding platform, then integrates the website. The server must be able to reach the download URL and meet the server requirements below.

Step 1: Fill in the Parameters on the Page¶

First, create a Web application in RUM > Application List to obtain the application ID and reporting parameters, and review the server requirements.

Open the one-click configuration page, fill in the application parameters, and select the platform. Start with the default same-origin asynchronous mode to complete validation. For the first validation, we recommend 100% session sampling and Session Replay disabled.

Using "Linux / Nginx + same-origin + asynchronous" as an example, fill in the following on the page:

The same flow supports all four combinations of same-origin/CDN and synchronous/asynchronous without hand-written TOML. When selecting CDN, fill in the HTTPS script URL of the SDK. Select "Synchronous" when the SDK must be initialized before subsequent business scripts run. See SDK Sources and Loading Modes for the differences.

Step 2: Read the Release Version and Copy the Command¶

1. Click "Read release version" and confirm that the page displays the Rumable and Web SDK versions.
2. Download the TOML and keep it for later modification and recovery. You do not need to edit it manually.
3. Switch to "Install command" and copy the complete command generated on the page. Copying the command alone does not change the server; integration begins only after it is executed.

The command contains the configuration you filled in; you cannot use someone else's command. The following shows only the structure of the one-click command for auto-discovery integration. The installer URL, release directory, and encoded configuration are all filled in by the page. Do not run the placeholder examples directly. When executing for real, copy the complete command generated on the page; you do not need to modify version numbers manually.

Step 3: Run the One-Click Command on the Server¶

Linux / Nginx: Log in to the server running Nginx, use a terminal with sudo privileges, and paste the Bash command generated on the page. The command has the following form:

bash -o pipefail -c 'curl --proto "=https" --proto-redir "=https" -fsSL "INSTALLER_URL_FROM_PAGE" | sudo sh -s -- --base-url "ARTIFACT_BASE_FROM_PAGE" --config "CONFIG_FROM_PAGE" --discover'

Windows / IIS: Open Windows PowerShell 5.1+ as an administrator and paste the PowerShell command generated on the page. Do not run it in cmd.exe. The command has the following form:

Before running, confirm that the target application uses a started exclusive application pool and that child applications each have their own pool. The integration recycles the target pool and waits for old worker processes to exit. In-process sessions may be lost, so perform this operation in a maintenance window where the impact of recycling is acceptable.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
& ([scriptblock]::Create((Invoke-WebRequest -UseBasicParsing 'INSTALLER_URL_FROM_PAGE').Content)) -BaseUrl 'ARTIFACT_BASE_FROM_PAGE' -Config 'CONFIG_FROM_PAGE' -Discover

The installer automatically selects the package matching the system and CPU, verifies the archive checksum, installs the CLI, reads the configuration, and discovers websites. It auto-selects when there is only one candidate. With multiple sites or bindings, choose the target according to the terminal prompts and, if necessary, provide the access URL or confirm compression adjustments. The one-click installer includes an integration confirmation, so running the command means you agree to apply the changes. After the target is selected and the required prompts are completed, the tool directly performs injection and HTTP validation.

One-click integration still requires you to select a website when ambiguity exists. It does not modify the first site by default, nor does it automatically install Nginx, IIS, or URL Rewrite. If you need a custom target, select "Manually specify site and path" on the page and continue generating the one-click command. For complex configurations or offline servers, use step-by-step installation.

Step 4: Save the Results and Validate¶

After the terminal displays RUM setup complete, record the site ID and URL from the output. In advanced manual mode, use the id and publicURL values from the configuration. Save the selected version, the downloaded TOML, and the CLI path and state directory determined in the table below. Back up the entire state directory; when Nginx outputs Backup:, record that path separately. Then confirm browser collection and real data ingestion by following Verifying the Integration. Once validation passes, the first-time integration is complete and no further step-by-step installation is needed.

The page generates the configuration in the local browser and does not submit application configuration to the download site. The Base64 in the command is encoding, not encryption. Do not expose complete commands that contain a Client Token. The one-click installer cleans up temporary TOML files, so keep the configuration downloaded from the page.

Default installation locations:

The version in the table is the version selected on the configuration page for this run. One-click installation does not add the CLI to PATH automatically. The state directory stores deployment, recovery, and ownership information; keep it and back it up. For subsequent operations, continue using the original site ID and state directory, and choose an update method based on the original configuration type.

Fixed Entry Points and Installation Package Selection¶

• Online configuration page: Fill in the configuration and generate an installation command.
• Release manifest: Read the recommended installation package, bundled SDK, download files, and verification information.

After reading the manifest once, the configuration page points the command to the installer and package of that release and verifies them with the matching checksum. The documentation entry always uses latest. The specific version, package name, and verification information are updated by the release process; you do not need to replace version numbers in the documentation.

Reading latest only determines which installation package is selected for this run; it does not automatically upgrade integrated websites. Integrated sites continue to use the CLI path and state directory recorded at installation time. To upgrade, proactively select and apply a new package by following the upgrade steps.

Prerequisites and Server Requirements¶

1. Create a Web application in RUM > Application List and obtain the applicationId.
2. Select a reporting method: use site and the browser clientToken for OpenWay, or datakitOrigin for direct DataKit connections. See Web Application Integration for details. Do not use a management API Key.
3. Confirm that the website does not have the same SDK integrated more than once. Integrations bundled in business code also require manual review.
4. Prepare a validation endpoint that directly returns HTML with HTTP 200. The page needs a standard <head> start tag. Do not use redirect pages, login pages, or download URLs instead.
5. Back up the web server configuration and confirm operation permissions and a maintenance window. Enabling checks the configuration and reloads Nginx, or modifies the managed rules of the target IIS application and recycles its exclusive application pool.

Browsers must be able to reach the reporting endpoint; HTTPS websites should use an HTTPS reporting endpoint. The CSP needs to allow the same-origin initialization script, the actual SDK URL, the reporting target, and any required workers. Rumable does not relax CSP automatically and does not inject inline JavaScript.

Linux / Nginx Requirements¶

• The minimum supported Nginx technical version is 1.9.4 and must include http_sub_module. Prefer a maintained version.
• Linux x86, x64, and ARM64 packages are provided. One-click installation selects a modern package; older systems use the matching legacy package.
• Use root or sudo. The one-click command requires Bash, curl, CA certificates, and common extraction and verification tools.
• The HTML entering the replacement stage should be uncompressed. Automatic hooking adjusts source compression, conditional requests, and caching at the target processing location, so review the actual impact. Output gzip can be preserved.
• Nginx auto-discovery, automatic hooking, and hook rollback are currently supported only on Linux.

Windows / IIS Requirements¶

• IIS 7.5+, URL Rewrite 2.x, Static Content, and anonymous static file access must be ready. The tool does not install these components automatically.
• One-click installation requires administrator privileges and Windows PowerShell 5.1+. The CLI's IIS management bridge requires native 64-bit PowerShell 3.0+ on the system.
• Windows 10 / Server 2016+ use the modern package; older Windows uses the corresponding legacy package. True 32-bit Windows cannot manage IIS.
• The target application pool must be started and serve only that application. Parent and child applications each use their own pools. Verify ownership in IIS Manager under Application Pools > View Applications. Shared pools must be adjusted by operations first; the tool does not assign or start pools, does not recycle shared pools, and does not restart the entire IIS server.
• The /__rumable__/ resources under the application must not be intercepted by business routes, inbound rewrite rules, or application handlers, and the JavaScript MIME type must be valid.
• Allow disabling IIS static and dynamic compression for the target application; the original settings are restored when disabled. This affects compression of other responses within that application. Backends behind dynamic applications or reverse proxies must also return uncompressed HTML.

Visitors' browsers must meet the Web SDK compatibility requirements.

Offline or Manual Installation¶

On a machine with internet access, select an archive from the release manifest that matches the operating system, CPU, and modern/legacy type, and also obtain the SHA256SUMS for the same version. Verify the SHA-256 for the file name before extracting. On the offline server, receive the raw archive and checksum manifest and verify again. The complete archive contains the CLI, examples, usage guide, and version information.

After installation, run rumable version first. Create a UTF-8 TOML file, fill in actual values by referring to the complete site configuration, then run setup. The following paths and site IDs are only examples. Do not overwrite existing configuration files:

rumable="/replace-with-your-actual-install-directory/rumable"
sudo "$rumable" setup \
  --config /etc/rumable/website.toml \
  --state-dir /var/lib/rumable --site website

On Windows, use an administrator terminal and replace the paths with your actual installation location:

$rumable = Read-Host 'Enter the full path of the installed rumable.exe'
& $rumable setup `
  --config 'C:\Rumable\website.toml' `
  --state-dir "$env:ProgramData\Rumable" --site website
if ($LASTEXITCODE -ne 0) { throw 'Rumable integration failed. Check the terminal output.' }

setup prepares and applies the integration. Nginx displays the proposed hooks; after confirmation, it writes, checks, and reloads. For complex or unsupported processing configurations, use the manual hooking procedure in the package guide. To only preview Nginx hooks, run render first per the guide, then run attach --dry-run.

Verifying the Integration¶

After IIS integration, first perform a normal refresh on the original browser page while keeping the cache; do not use a hard refresh or Disable cache. Check the homepage and other major HTML pages: they should return 200, contain exactly one current initialization script, and have normal business content. Auto-discovery by default usually checks only the homepage; to cover other templates, configure the corresponding probePaths. If something is abnormal, save the request, response, and failure output first, then troubleshoot by following the operations guide.

Run the following with the actual CLI path, state directory, and the site ID recorded from the terminal. The paths and ID below must be replaced with the original deployment values.

Linux (with sudo privileges):

rumable="/replace-with-your-actual-install-directory/rumable"
state="/var/lib/rumable"
site_id="replace-with-the-original-site-id"
sudo "$rumable" status --state-dir "$state" --site "$site_id"
sudo "$rumable" probe --state-dir "$state" --site "$site_id"

Windows (administrator terminal):

$rumable = Read-Host 'Enter the full path of the installed rumable.exe'
$state = Join-Path $env:ProgramData 'Rumable'
$siteId = Read-Host 'Enter the original site ID'
& $rumable status --state-dir $state --site $siteId
& $rumable probe --state-dir $state --site $siteId

Validation must be confirmed layer by layer:

probe verifies HTTP injection and resource reachability but does not execute the browser SDK. A simulated receiver returning success cannot replace checking real data ingestion. Adjust sampling and Session Replay only after full validation.