Go Live and Maintain

Go Live and Maintain#

This page covers the checks before readers see the chat, and what you maintain afterwards. For the overview, see the Embedding Neo Chat in Your Own App or Site page.

Before You Go Live#

Check each of these before readers see the chat:

The SQUIRRO_REFRESH_TOKEN belongs to a dedicated service account with the reader server role, added with the Reader project role only to the projects in PROJECT_ID.
Memory is turned off for the service account in every project that the proxy serves, what it remembered is deleted, including under Recently deleted, and ALLOW_SHARED_MEMORY is unset.
Every reader may share the scheduled tasks of the service account. Either every reader may also share its file storage, or capability.filesystem.enabled is pinned to false in every project that the proxy serves, and ALLOW_SHARED_AGENT_TOOLS is tasks.
Every document that the service account can see is one that any reader may open.
You decided who may sign in as the service account, because that person sees the conversations of every reader, and when you erase those conversations.
With the Workspaces feature turned on, SQUIRRO_TENANT names the tenant of the workspace that holds the project.
Conversation IDs stay out of the access logs of your reverse proxy and out of your analytics.
NUTRIENT_LICENSE_KEY holds the key that Squirro supplied, issued for the domains that the widgets are embedded on, unless the evaluation watermark is acceptable.
If your site has a Content Security Policy, it has the sources listed on the Content Security Policy page.
ALLOWED_ORIGINS lists exactly your production origins.
ANON_TOKEN_SECRET is random, at least 32 characters long, the same on every replica, different for every environment, and stored as a secret.
PROJECT_ID names exactly the project, or projects, that the chat uses.
Your reverse proxy sets Host and X-Forwarded-For, and TRUST_PROXY matches the number of reverse proxies in front.
If the proxy listens on 0.0.0.0, only the reverse proxy can reach its port.
Uploads stay off, with allowUploads unset and capabilities.attachments off, unless every reader may see the files of every other reader.
Search stays off, with ALLOW_SEARCH unset, unless the page shows a search widget and every reader may search every document in the project.
/healthz is not reachable from the internet, or you accept that its connection counts are public, and your health check alerts on a growing sockets count or on timeouts.
The stop timeout of your container is above 30 seconds.
The rate limit fits your traffic. Readers behind one corporate gateway share one limit, and each replica of the proxy counts its limits on its own.
No reverse proxy, CDN, or load balancer in front of the chat proxy buffers streamed responses.
Your site serves neo-sdk.js compressed, with Brotli or at least gzip, and with a long cache lifetime.
You have tried the chat in light and dark mode on your real pages.
You have a plan to update the SDK and the components that you maintain, and to renew the refresh token before it expires.

Keeping the SDK Up to Date#

Update the proxy first, because an older proxy can refuse the requests or ignore the settings of a newer chat. You can update the script-tag embed and the React components later, each on its own.

Each Squirro release brings a new SDK minor version, and fixes for an LTS release come as patch versions of that minor version. To see the latest version of each dist-tag, run this command:

npm view @squirro/neo-sdk dist-tags

How to Update#

Update each part that you use:

The proxy

In the folder of your server project, install the new version with a tilde range, as described in the Installation section of the Set Up the Proxy page, then restart the proxy. For example, for SDK minor version 0.1, run this command:
```
npm install @squirro/neo-sdk@~0.1
```
The command installs the latest patch version of that minor version. For the SDK of a newer Squirro release, name its minor version instead.

Your copy of the template does not change when the package does. After each update, compare it with the template in node_modules/@squirro/neo-sdk/templates/, and carry over the changes. The PDF viewer updates with the package.
The script-tag embed

If you host neo-sdk.js yourself, copy it and its two license files again from the proxy server to your site. If you load it from a public npm CDN, change the version and the integrity hash in the script tag.
The React components

Install the new version in your React app, then rebuild and redeploy the app.

Components You Maintain#

The SDK package does not include the software it runs on. Keep the following up to date, including their security releases:

Node.js, version 22.18 or later.
Express, if you use the proxy-express.mjs template, as a dependency of your own server project.
In a React app, react, react-dom, @tanstack/react-query, and the other libraries that the SDK expects from the app.
The reverse proxy, the TLS certificates, the operating system or container image, and the process manager that restarts the proxy.

Your copy of a template is your own code, and Squirro maintains the @squirro/neo-sdk package that it calls. To report a problem with the package, visit the Squirro Support website and submit a technical support request.

Renewing the Refresh Token#

The refresh token stops working when it expires, when it is revoked or renewed, or when the server role or workspace role of the service account changes. A running proxy then keeps serving until its current access token expires, and afterwards responds to every request with 502 upstream_unavailable, while /healthz still reports it as serving.

Renewing invalidates the old token immediately, so set the new token on every replica of the proxy without delay. To replace the token, follow these steps:

Sign in to Squirro Neo as the service account.
Select the profile picture, navigate to Settings → API access, select Renew, and confirm with Renew token.
Select Copy token, set the token as SQUIRRO_REFRESH_TOKEN on every replica of the proxy, and restart each replica.

Without a valid token, the proxy does not start.