How to Update Your Self-Hosted Inkeep Agent Platform – inkeep

📋 Overview

This guide walks you through updating your self-hosted Inkeep agent platform deployed on Azure VM, GCP, AWS, Hetzner, or other infrastructure. Regular updates ensure you have the latest features, security patches, and performance improvements.

Target Audience: DevOps Engineers, System Administrators, Platform Engineers, IT Operations

Estimated Time: 10-15 minutes

Expected Downtime: 2-5 minutes during service restart

When to Update

Consider updating your self-hosted Inkeep platform when:

New features or improvements are announced in the Inkeep changelog
Security patches or critical bug fixes are released
You encounter issues that have been resolved in newer versions
As part of your regular maintenance schedule (recommended: monthly)

Prerequisites

Before starting the update process, ensure you have:

SSH access to your VM with appropriate permissions
Docker and Docker Compose installed and running
Your environment variables documented (especially INKEEP_AGENT_API_KEY)
Backup of your configuration (current docker-compose.yml and .env files)
Maintenance window scheduled if running in production

⚠️ Important: While database data persists through updates (stored in Docker volumes), always backup your configuration files before proceeding.

Pre-Update Checklist

Backup current configuration:

cd inkeep
cp docker-compose.yml docker-compose.yml.backup
cp .env .env.backup

Verify current version is running:
```
docker compose ps
```
Check available disk space:
```
df -h
```
Ensure you have at least 5GB of free space for new images.
Notify users if applicable about the scheduled maintenance window

Step-by-Step Update Procedure

Step 1: Navigate to Installation Directory

SSH into your VM and navigate to your Inkeep installation directory:

cd inkeep

Step 2: Stop Running Services

Gracefully stop all Inkeep services:

docker compose down

This command stops and removes containers but preserves your data volumes.

Step 3: Download Latest Configuration

Fetch the latest docker-compose.yml from the official Inkeep repository:

wget -O docker-compose.yml https://raw.githubusercontent.com/inkeep/agents/main/docker-compose.yml

💡 Tip: If you've made custom modifications to your docker-compose.yml (custom ports, additional environment variables, etc.), merge these changes carefully with the new file. Compare using: diff docker-compose.yml.backup docker-compose.yml

Step 4: Pull Latest Docker Images

Download the latest container images specified in the updated configuration:

docker compose pull

This may take several minutes depending on your internet connection and image sizes.

Step 5: Restart Services

Start the updated services in detached mode:

docker compose up -d

The -d flag runs containers in the background.

Step 6: Clean Up Old Images (Optional)

Remove unused Docker images to free up disk space:

docker image prune -a

Type y when prompted to confirm deletion.

⚠️ Warning: The prune command removes ALL unused images, not just Inkeep images. Skip this step if you have other Docker applications on the same host.

Post-Update Validation

After completing the update, verify that your platform is running correctly:

1. Check Container Status

docker compose ps

All services should show status Up or running.

2. View Container Logs

docker compose logs -f --tail=50

Look for any error messages or warnings. Press Ctrl+C to exit log viewing.

3. Test Health Endpoints

Verify the platform is responding correctly:

# Health check endpoint
curl http://localhost:3000/health

# Readiness check endpoint
curl http://localhost:3000/ready

Both should return successful responses (HTTP 200 status).

4. Verify Data Persistence

Confirm your database data was preserved:

docker volume ls

Your Inkeep volumes should still exist and retain their data.

5. Test Agent Functionality

Perform a test query to ensure your agents are functioning correctly:

Access your agent interface
Submit a test question
Verify responses are generated correctly
Check that any custom integrations still work

Rollback Procedures

If you encounter issues after updating, you can rollback to your previous version:

Quick Rollback

Stop current services:
```
docker compose down
```

Restore backup configuration:

cp docker-compose.yml.backup docker-compose.yml

Pull previous images:
```
docker compose pull
```
Restart with previous version:
```
docker compose up -d
```

Common Update Issues and Troubleshooting

Issue: Containers Won't Start After Update

Symptoms: Containers exit immediately or show Restarting status

Solutions:

Check logs: docker compose logs
Verify environment variables are set correctly in .env
Ensure INKEEP_AGENT_API_KEY is valid
Check for port conflicts: netstat -tuln | grep 3000

Issue: "Cannot Connect to Docker Daemon"

Solution:

sudo systemctl start docker
sudo systemctl enable docker

Issue: Disk Space Full During Update

Solution:

# Remove stopped containers
docker container prune

# Remove unused images
docker image prune

# Remove unused volumes (⚠️ careful with this)
docker volume prune

Issue: New Configuration Breaks Custom Settings

Solution: Carefully merge your custom settings from docker-compose.yml.backup into the new configuration file. Common customizations include:

Custom port mappings
Additional environment variables
Resource limits (memory, CPU)
Network configurations

Zero-Downtime Update Strategies (Advanced)

For production environments requiring minimal downtime, consider these approaches:

Blue-Green Deployment

Deploy updated version on a second VM (green environment)
Validate the new deployment thoroughly
Switch load balancer/DNS to point to new environment
Keep old environment (blue) as immediate rollback option

Rolling Update with Load Balancer

If running multiple instances behind a load balancer:

Remove one instance from load balancer pool
Update that instance following the standard procedure
Validate and return to pool
Repeat for remaining instances

Best Practices for Production Updates

Establish a Regular Update Schedule

Security patches: Apply within 24-48 hours of release
Minor updates: Monthly during maintenance windows
Major updates: Quarterly after thorough testing

Test Updates in Staging First

If possible, maintain a staging environment that mirrors production:

Apply updates to staging first
Run comprehensive tests for 24-48 hours
Document any issues and resolutions
Apply to production with confidence

Maintain Documentation

Keep a log of all updates including:

Date and time of update
Version numbers (before and after)
Issues encountered and resolutions
Downtime duration
Changes in configuration

Monitor After Updates

Increase monitoring vigilance for 24-48 hours after updates:

Check logs regularly: docker compose logs --follow
Monitor resource usage: CPU, memory, disk I/O
Track error rates and response times
Gather user feedback on any behavioral changes

Automate Where Possible

Consider creating an update script for consistency:

#!/bin/bash
# update-inkeep.sh

set -e  # Exit on error

echo "Starting Inkeep platform update..."

cd /path/to/inkeep

# Backup
cp docker-compose.yml docker-compose.yml.backup.$(date +%Y%m%d)
cp .env .env.backup.$(date +%Y%m%d)

# Update
docker compose down
wget -O docker-compose.yml https://raw.githubusercontent.com/inkeep/agents/main/docker-compose.yml
docker compose pull
docker compose up -d

# Validate
sleep 10
docker compose ps
curl -f http://localhost:3000/health || { echo "Health check failed!"; exit 1; }

echo "Update completed successfully!"

Additional Resources

Azure VM Deployment Guide - Initial setup documentation
Health Check Endpoints - Documentation on /health and /ready endpoints
Docker Compose Documentation - Official Docker Compose reference

Getting Help

If you encounter issues during the update process:

Check logs first: docker compose logs often reveals the root cause
Review this troubleshooting section for common issues
Contact Inkeep Support with your logs and configuration details
Include relevant information: Platform (Azure/GCP/AWS), Docker version, error messages

📌 Remember: Your database data persists through updates thanks to Docker volumes. The update process only refreshes the application containers and configurations, not your stored data.