Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Upgrading

This guide provides instructions for upgrading your Kinesis API installation to newer versions. Because Kinesis API is actively developed, new releases may include important security updates, bug fixes, and new features.

Before You Begin

Before upgrading your Kinesis API installation, it's important to take some precautionary steps:

  1. Create a backup: Always back up your data before upgrading. See the Backups guide for detailed instructions.

  2. Review the changelog and roadmap:

    • Check the Changelog at /web/changelog for detailed information about each version's changes, including any breaking changes or deprecations
    • Review the Roadmap at /web/roadmap for a higher-level overview of monthly development progress and upcoming features

  3. Test in a non-production environment: If possible, test the upgrade process in a development or staging environment before applying it to production.

Upgrading Docker Installations

If you're running Kinesis API via Docker (the recommended method), follow these steps:

Step 1: Pull the Latest Image

# Pull the latest version
docker pull edgeking8100/kinesis-api:latest

# Or pull a specific version
docker pull edgeking8100/kinesis-api:x.y.z

Step 2: Stop the Current Container

docker stop kinesis-api

Step 3: Remove the Current Container (preserving volumes)

docker rm kinesis-api

Step 4: Start a New Container with the Updated Image

docker run --name kinesis-api \
  -v $(pwd)/.env:/app/.env \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/public:/app/public \
  -p 8080:8080 -d \
  --restart unless-stopped \
  edgeking8100/kinesis-api:latest

Step 5: Verify the Upgrade

  1. Check the container logs for any errors:
docker logs kinesis-api
  1. Access the web interface to confirm it's working correctly.

Upgrading Rust Installations

If you're running Kinesis API directly from the Rust source:

Step 1: Backup Your Data and Environment

cp -r data/ data_backup/
cp .env .env.backup

Step 2: Update the Source Code

git pull origin master

Step 3: Build the Updated Version

cargo build --release

Step 4: Restart the Service

# If running as a systemd service
sudo systemctl restart kinesis-api

# Or if running directly
./target/release/kinesis-api

Post-Upgrade Steps

After upgrading, perform these checks:

  1. Verify all projects and collections are accessible
  2. Test API endpoints to ensure they're functioning correctly
  3. Review logs for any errors or warnings
  4. Check database integrity if you've upgraded across major versions

Handling Breaking Changes

Kinesis API follows semantic versioning (SemVer):

  • Patch updates (e.g., 1.0.0 to 1.0.1): Safe to upgrade, contains bug fixes
  • Minor updates (e.g., 1.0.0 to 1.1.0): Generally safe, adds new features in a backward-compatible way
  • Major updates (e.g., 1.0.0 to 2.0.0): May contain breaking changes

For major version upgrades, read the release notes carefully as they will include:

  • List of breaking changes
  • Required manual steps
  • Migration guides

Rollback Procedures

If you encounter issues after upgrading, you can roll back to the previous version:

Docker Rollback

# Stop the current container
docker stop kinesis-api
docker rm kinesis-api

# Start a new container with the previous version
docker run --name kinesis-api \
  -v $(pwd)/.env:/app/.env \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/public:/app/public \
  -p 8080:8080 -d \
  --restart unless-stopped \
  edgeking8100/kinesis-api:previous-version-tag

Rust Rollback

# Checkout the previous version
git checkout v1.x.x

# Rebuild
cargo build --release

# Restart
sudo systemctl restart kinesis-api  # or start manually

Troubleshooting Common Upgrade Issues

Database Connection Errors

If you see database connection errors after upgrading:

  1. Check that your data directory permissions are correct
  2. Verify the database connection settings in your .env file
  3. Ensure the data format is compatible with the new version

UI Issues After Upgrade

If the web interface appears broken after upgrading:

  1. Clear your browser cache
  2. Check for JavaScript console errors
  3. Verify that all static assets are being served correctly

API Endpoints Not Working

If API endpoints stop working after an upgrade:

  1. Check the route configuration in the X Engine
  2. Verify that any changes to authentication methods have been accounted for
  3. Look for changes in parameter handling or response formats

Getting Help

If you encounter issues during the upgrade process: