How to upgrade CodeScene On-Premise
Overview
This article explains how to upgrade a self-hosted CodeScene On-Premise instance to a newer version, whether you run it as a Docker container (recommended) or as a standalone JAR. Most upgrades take a few minutes plus a short restart.
Keeping CodeScene up to date gives you the latest analysis features and fixes, and it is the only way to receive security patches for CodeScene and its bundled components, such as the Java runtime in the Docker image.
CodeScene Cloud customers don't need to do anything as we upgrade the cloud service for you.
Before you upgrade
These steps apply to both Docker and JAR installations.
Check your current version and target version. Note the version you run today and pick the version you will upgrade to. In most cases this should be the latest release.
Read the release notes for the versions between your current and target version, looking for anything that needs action on your side.
Back up your database.
Built-in database: CodeScene takes an automatic backup during the upgrade, but we still recommend a manual copy of the data directory.
External database: back it up yourself using your usual database tooling.
Note your current configuration. Record the volumes, ports and environment variables (Docker) or the start command and Java options (JAR) so the new version starts with the same settings.
Plan a short maintenance window. CodeScene is unavailable while it restarts, so let your users know.
Upgrade steps
Docker
Pull the new image, replacing
<version>with your target version (or uselatest):docker pull codescene/codescene:<version>Stop the running container:
docker stop <container>Start a new container from the new image, using the same volumes, ports and environment variables as before. If you use Docker Compose, update the image tag in your compose file and run
docker compose up -d.
The Docker image bundles its own Java runtime, so upgrading the image also upgrades Java.
JAR
Download the latest JAR: codescene-enterprise-edition.standalone.jar.
Stop CodeScene, then start it again with the new JAR, keeping any Java options you used before:
java -jar codescene-enterprise-edition.standalone.jarKeep the Java runtime (JRE) on the host up to date. The JAR runs on your own Java installation, so Java security fixes are not included in a CodeScene upgrade.
Verify the upgrade
Once CodeScene is running again, check that the upgrade worked:
Log in and confirm CodeScene shows the new version number.
Open a project and check that existing analysis results are still there.
Run an analysis on one project and confirm it completes.
If you use integrations (such as pull request checks), open a test pull request and confirm the check runs.
Security updates: Which version to choose
When we announce a security update, upgrade to the version named in the announcement or any later version as soon as you can.
Go straight to the latest fix. We sometimes ship a quick interim release with a temporary workaround, followed by a release with the full fix. Skip the interim release and upgrade directly to the one that fully resolves the issue.
You don't need to step through intermediate versions. You can upgrade directly from your current version to the target version. Check the release notes for anything that needs action along the way.
Auto-upgrade: if your instance auto-upgrades, confirm it has reached the fixed version.
Troubleshooting and getting help
CodeScene doesn't start: Check the container logs (
docker logs <container>) or the JAR's console output. Confirm the new container uses the same volumes, ports and environment variables as before.Data appears to be missing: The new container is probably not mounted to the same data volume or database. Fix the mount or connection settings and restart.
You need to roll back: Stop the new version, restore your backup, and start the previous image tag or JAR.
Was this helpful?
More in On-Premise
How to Deploy CodeScene On-prem?How to Enable OKTA Single Sign-on (SSO) for On-Premise?How Can I Ensure Smooth Performance of the CodeScene Server?What Are CodeScene’s Deployment and System Requirements?Still need help? Ask the team