Upgrading Ubuntu 20.04 to 22.04 for Self-Hosted Jama Connect (KOTS) Environments

Published Date: March 20, 2026

Validated: Yes

Audience: Everyone

Products and Versions Covered:

Self-hosted
Jama Connect® v9.17.x
Database: MySQL 8.0
OS: Ubuntu 20.04 → 22.04

Summary

Customers running self-hosted Jama Connect® 9.17.x using Replicated (KOTS) may encounter issues when attempting to upgrade their application servers from Ubuntu 20.04 to 22.04 using a standard in-place OS upgrade.

This article explains the cause of these issues and outlines supported upgrade approaches to ensure system stability and data integrity while maintaining connection to an external MySQL 8.0 database.

After performing a standard Ubuntu OS upgrade (20.04 → 22.04), customers may experience:

KOTS configuration reset or missing
Jama Connect is failing to start or appears as a fresh installation
Application services (e.g., search/Elasticsearch) are failing
General instability or degraded performance

Jama Connect (KOTS-based deployments) relies on system-level dependencies, including:

Kubernetes (via kURL installer)
Container runtime components
OS-level libraries and kernel versions

A direct OS upgrade can:

Modify or replace these dependencies
Disrupt or reset KOTS-managed state
Invalidate existing configuration and deployment metadata

As a result, the environment may no longer recognize the existing Jama Connect installation, leading to configuration loss or failed startup.

Best Practice Recommendation

Jama Software recommends:

Avoiding direct in-place OS upgrades for KOTS environments
Using a clean installation and migration approach whenever possible
Validating upgrade paths prior to execution

Resolution

Important Considerations for Ubuntu 22.04

When running Jama Connect 9.17.x on Ubuntu 22.04:

Ensure system memory is properly allocated:
- JVM Heap: ~6 GB
- Container memory: ~8 GB
Improper memory configuration may result in Elasticsearch startup failures
Validate all services post-deployment, including indexing and background jobs

Option 1 – Clean Installation on Ubuntu 22.04 (Recommended)

This is the preferred and supported approach for upgrading the underlying OS.

Steps:

Provision a new server running Ubuntu 22.04
Install Replicated KOTS using the Jama-supported kURL installer
Capture configuration from the existing environment:
- KOTS application configuration (via support bundle)
- License file
Maintain your existing external MySQL 8.0 database (no upgrade required)
Configure the new KOTS instance:
- Use the same database connection details
- Reapply prior configuration settings
Deploy Jama Connect 9.17.x
Perform a full reindex
Validate system functionality
Cut over users (DNS or load balancer update)

Benefits:

Avoids dependency conflicts introduced by OS upgrades
Preserves configuration and application integrity
Provides a clean, stable deployment

Option 2 – In-Place OS Upgrade (Not Recommended / Higher Risk)

If provisioning a new server is not feasible, an in-place upgrade may be attempted with caution.

Requirements:

Full backups:
- External MySQL 8.0 database
- KOTS configuration and license
- Persistent volumes (e.g., /var/lib/longhorn)
Upgrade KOTS/kURL components prior to OS upgrade
Plan for downtime and potential rollback

Risks:

Loss of KOTS configuration
Failed or partial deployments
Extended recovery time

Additional Resources

To reduce risk and ensure a successful upgrade, customers are encouraged to engage Jama Software’s Customer Delivery Services (CDS) team. These services help ensure proper planning, minimize downtime, and prevent issues such as configuration loss.

Available options include:

Complimentary pre-upgrade consultation to review the environment and validate the approach
Guided upgrade services through existing service agreements or success credits
Success Programs
Success Catalog
Datasheets
Request a Solution Offering or Training from the Success Catalog

Feedback:
We welcome your input! Please sign in to leave any comments, suggestions, or improvement ideas below.

Related to