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:
-
Create a backup: Always back up your data before upgrading. See the Backups guide for detailed instructions.
-
Review the changelog and roadmap:
-
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
- Check the container logs for any errors:
docker logs kinesis-api
- 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:
- Verify all projects and collections are accessible
- Test API endpoints to ensure they're functioning correctly
- Review logs for any errors or warnings
- 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:
- Check that your data directory permissions are correct
- Verify the database connection settings in your
.env
file - Ensure the data format is compatible with the new version
UI Issues After Upgrade
If the web interface appears broken after upgrading:
- Clear your browser cache
- Check for JavaScript console errors
- Verify that all static assets are being served correctly
API Endpoints Not Working
If API endpoints stop working after an upgrade:
- Check the route configuration in the X Engine
- Verify that any changes to authentication methods have been accounted for
- Look for changes in parameter handling or response formats
Getting Help
If you encounter issues during the upgrade process:
- Check the official documentation
- Create a new ticket in the issue tracker
- Contact support at support@kinesis.world