> For the complete documentation index, see [llms.txt](https://docs.tomorrowx.com/cap/vZHo2144m1e79o3WX0RU/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tomorrowx.com/cap/vZHo2144m1e79o3WX0RU/deploy-and-configure/installation-and-configuration/updating-between-v12-releases.md). # Updating Between V12 Releases This page describes moving an existing V12 installation to a newer V12 distribution - for example from a 12.1.10 install to the space.vars.X\_Console\_Version\_Full release. It is the procedure to use when a release updates a runtime component of the distribution itself, such as a security update to the embedded Jetty web server. It is important to understand what the two update mechanisms each deliver: * **Console updates from the update server** are in-place updates to the Console web application only. They are quick and safe, but they do not change the Jetty runtime, the Java service wrappers, or anything else outside the web application. The version of Jetty serving your Console is the one that shipped in the distribution you installed. * **A distribution refresh** (this page) replaces the whole installation - including the embedded Jetty runtime - while carrying your `HOME/` directory, and therefore all of your data and configuration, across unchanged. The same rule applies to Programmable Data Agent hosts: the web runtime serving an Agent is the one installed on that host - the distribution's Jetty for Agents co-hosted with a Console install, or the Jetty baked into the container or machine image for containerised Agents - and it updates when that installation or image is refreshed, never through an extension update. The Built-in Proxy (RulesBIP) extension bundles its own copies of the Jetty libraries for the proxy machinery that runs inside the Agent web application (upstream connections, response mediation, and the optional forward-proxy listener); updating that extension and redeploying the Agent refreshes those libraries, but not the runtime serving the Agent. Containerised Agents are refreshed by moving to the release's updated container or machine image; the Console host is the machine this page is about. The procedure is the same safe, reversible "copy HOME across" pattern as [Upgrading to V12](/cap/vZHo2144m1e79o3WX0RU/deploy-and-configure/installation-and-configuration/upgrading-to-v12.md), but simpler: both sides are V12, so there is no credential migration, no metadata format change, and no update content switch. A refresh typically takes 10 to 20 minutes. ## Prerequisites * A full backup of the existing installation directory (the entire install, not just `HOME/`) * The new V12 distribution zip * Approximately the same amount of free disk space as your current install * The Console stopped cleanly (service controls, or the Console UI shutdown) ## The refresh procedure ### Step 1: Unzip the new distribution alongside the old Both distributions unpack to a directory named space.vars.X\_Console\_Dir, so unzip the new release to a staging name rather than over the top of the running install: ``` /opt/cap/CAP-Console-12.1 <-- existing install (stopped) /opt/cap/CAP-Console-12.1-new <-- new distribution (fresh unzip) ``` Do not start the new install yet. ### Step 2: Copy HOME across Copy your existing `HOME/` wholesale into the new install, then restore the new distribution's `HOME/Applications/` folder (which contains the new Console web application binaries, not customer data): ``` # Save the new distribution's fresh Applications folder mv /opt/cap/CAP-Console-12.1-new/HOME/Applications /tmp/new-applications # Replace the new HOME with your existing HOME content rm -rf /opt/cap/CAP-Console-12.1-new/HOME cp -Rp /opt/cap/CAP-Console-12.1/HOME /opt/cap/CAP-Console-12.1-new/HOME # Restore the new Applications folder rm -rf /opt/cap/CAP-Console-12.1-new/HOME/Applications mv /tmp/new-applications /opt/cap/CAP-Console-12.1-new/HOME/Applications # Remove stale Derby lock files from the copied data find /opt/cap/CAP-Console-12.1-new/HOME -name "*.lck" -delete ``` Everything else in `HOME/` carries forward exactly as it is: repositories, rulesets, configurations, the Coop database (including `installation.key`), credential vaults, content, audit history, and every Agent directory. The full reference table of what each `HOME/` subdirectory contains is in [Upgrading to V12](/cap/vZHo2144m1e79o3WX0RU/deploy-and-configure/installation-and-configuration/upgrading-to-v12.md#what-the-home-subdirectories-contain). Use `cp -Rp` (not plain `cp -R`) so file permissions carry across - `HOME/Data/installation.key` must keep its owner-only permissions. ### Step 3: Copy configuration.properties The `configuration.properties` file holds every setting made on the Console Setup page and any made by editing the file, such as single sign-on. It lives inside the web application directory, whose name includes the build number, so it is replaced by Step 2 and must be copied explicitly. Run `ls HOME/Applications/console/` in each install. In the existing install, use the build directory with the highest number: each Console update from the update server adds a build directory, and the Console runs the highest. The new install has a single build directory. Keep the new distribution's file for reference, then copy yours over it: ``` cp /opt/cap/CAP-Console-12.1-new/HOME/Applications/console/B/WEB-INF/classes/configuration.properties \ /opt/cap/CAP-Console-12.1-new/HOME/Applications/console/B/WEB-INF/classes/configuration.properties.shipped cp /opt/cap/CAP-Console-12.1/HOME/Applications/console/B/WEB-INF/classes/configuration.properties \ /opt/cap/CAP-Console-12.1-new/HOME/Applications/console/B/WEB-INF/classes/configuration.properties ``` A refresh adds nothing to the copied file. Settings introduced since your file was created are not in it and keep their default values; the `configuration.properties.shipped` copy shows each of them with its description. See [Console Configuration](/cap/vZHo2144m1e79o3WX0RU/deploy-and-configure/installation-and-configuration/console-configuration.md) for the settings and how each kind of update treats the file. ### Step 4: Carry across server-level customisations The `server/` directory is entirely replaced by the new distribution, so any customisations you made there must be copied across, exactly as in the pre-upgrade checklist of [Upgrading to V12](/cap/vZHo2144m1e79o3WX0RU/deploy-and-configure/installation-and-configuration/upgrading-to-v12.md): * **Your own HTTPS keystore or certificates** and a modified `jetty-ssl-context.xml` from `server/etc/`. If you use the shipped self-signed certificate instead, skip this - the new install generates its own on first boot, and browsers that trusted the old certificate will prompt once to trust the new one. * **JDBC driver jars** from `server/lib/ext/jdbc/` * **Modified `web.xml` or `magic.properties`** files in the shipped webapps ### Step 5: Carry across custom Agent web applications If you have added your own Agent web applications under `server/webapps/` (anything beyond the shipped `console`, `consolex`, `root` and `testserver1`), copy each one across, then replace its engine library with the copy from the new distribution so the Agent runs the new engine build: ``` cp -Rp /opt/cap/CAP-Console-12.1/server/webapps/MyAgent \ /opt/cap/CAP-Console-12.1-new/server/webapps/MyAgent cp /opt/cap/CAP-Console-12.1-new/BaseApp/appname/WEB-INF/lib/magic-12.0.jar \ /opt/cap/CAP-Console-12.1-new/server/webapps/MyAgent/WEB-INF/lib/magic-12.0.jar ``` Agent engine libraries never update themselves - a copied webapp keeps its old engine until you replace the jar (its `HOME//` state carried across in Step 2 and needs no change). ### Step 6: Swap the installations and start Point your service wrapper at the new install. The simplest approach is to rename the directories so all existing paths keep working: ``` mv /opt/cap/CAP-Console-12.1 /opt/cap/CAP-Console-12.1.backup mv /opt/cap/CAP-Console-12.1-new /opt/cap/CAP-Console-12.1 ``` Start the Console and watch the startup log (by default `server/logs/stderrout-YYYY_MM_DD.log`). ## What to expect on first boot Unlike the V11 upgrade, a V12-to-V12 refresh performs no data migration: no credential migration messages appear in the log, and none are expected. Your `installation.key`, credential vaults and Agent metadata carry across byte-for-byte. ## Verifying the refresh 1. Log out and back in, and hard-refresh the browser - the Console UI caches the web application version per session, so an old tab keeps reporting the previous build until you do. 2. Confirm the version in the Console footer shows the new release and build. 3. Confirm your Agents are running and a Credential Vault entry displays correctly. ## After the refresh * In Configuration, then Updates, check for extension updates - in particular **Base Rules** and the **Built-in Proxy (RulesBIP)** - and install any offered for the new release. * **Redeploy your Agents.** Deployed Agents keep running the binaries they were deployed with; redeploying refreshes the extension libraries inside each Agent - including the Built-in Proxy's bundled Jetty libraries - to the versions you installed from the update server. * Keep the previous installation directory for at least one full backup cycle. It was only copied from, never modified, so reverting is simply a matter of stopping the new install and starting the old one. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.tomorrowx.com/cap/vZHo2144m1e79o3WX0RU/deploy-and-configure/installation-and-configuration/updating-between-v12-releases.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.