Updating the ConHive Agent

Keeping your ConHive Agent up-to-date ensures you benefit from the latest features, performance improvements, and security enhancements. This guide outlines the recommended methods for updating your agent installation.

Before you begin: It’s always a good practice to back up your agent’s configuration files (located in the configs subdirectory of your workdir) before performing an update.

Method 1: Using the Dedicated Update Script (update_conhive_agent.sh)

This method uses a specific script designed for safe in-place upgrades, particularly suitable for installations managed as a service.

Key Features of the Script

• Safe Operation: Stops the agent service before updating.
• Backup: Automatically creates a backup of your current agent binary.
• Download & Validation: Fetches the specified (or latest) version and verifies its integrity.
• Replacement: Replaces the old binary with the new version.
• Automatic Restart: Restarts the agent service after a successful update.
• Rollback: Automatically restores the backup if any step during the update process fails.

Steps to Update using the Script

1. Download the Update Script: Open your terminal and download the script using wget or curl.

   # Using wget:
   wget [https://conhive.ai/hub/update_conhive_agent.sh](https://conhive.ai/hub/update_conhive_agent.sh) -O update_conhive_agent.sh
   
   # Using curl:
   curl -o update_conhive_agent.sh [https://conhive.ai/hub/update_conhive_agent.sh](https://conhive.ai/hub/update_conhive_agent.sh)

2. Make the Script Executable:

   chmod +x update_conhive_agent.sh

3. Run the Update Script: Execute the script with administrative privileges (sudo). You can optionally specify a target version.

   # Update to a specific version (replace vX.Y.Z)
   sudo ./update_conhive_agent.sh vX.Y.Z
   
   # Update to the latest version (assuming script defaults to latest if version is omitted)
   # Verify script behavior if unsure.
   sudo ./update_conhive_agent.sh

   • Note: To find available versions, please check the ConHive Release Hub.

4. Verify the Update: After the script completes, confirm the agent service is running and check the installed version.

   # Check service status (if applicable)
   sudo systemctl status conhive-agent.service
   
   # Check agent version (adjust path if not default /usr/local/bin)
   # Common version flags are --version or version. Verify the correct flag for your agent.
   /usr/local/bin/conhive-agent --version
   # or perhaps:
   # /usr/local/bin/conhive-agent version

Script Workflow Summary

The update_conhive_agent.sh script automates these steps:

1. Stops the conhive-agent service.
2. Backs up the current binary.
3. Downloads the specified/latest version.
4. Validates the downloaded binary.
5. Replaces the old binary with the new one.
6. Restarts the conhive-agent service.
7. Performs an automatic rollback to the backup if any error occurs.

---

Method 2: Re-running the Installer Script (Linux Systemd)

If you initially installed the agent using the installer.sh script (Method 2 in Installation), you can often re-run the same script to perform an update.

# Using curl:
curl -sSL [https://conhive.ai/installer.sh](https://conhive.ai/installer.sh) | bash -s agent

# Using wget:
wget -qO- [https://conhive.ai/installer.sh](https://conhive.ai/installer.sh) | bash -s agent

This script typically includes logic to detect an existing installation, back it up, download the latest version, install it, and restart the service, similar to the dedicated update script. Check the the installation section for more details on this script.

---

Method 3: Manual Update

You can always update the agent manually by replacing the binary. This method requires careful execution.

1. Stop the Agent:
   • If running as a service: sudo systemctl stop conhive-agent.service
   • If running manually: Stop the process (e.g., Ctrl+C, kill <PID>).
   • If running in Docker: docker stop <container_name>
2. Backup (Recommended): Manually copy the existing agent binary to a safe location. Also, back up your workdir/configs directory.
3. Download New Binary: Go to the ConHive Release Hub and download the latest binary (.tar.gz or .zip) for your OS and architecture.
4. Extract New Binary: Extract the conhive-agent or conhive-agent.exe file from the downloaded archive.
5. Replace Old Binary: Replace the existing agent binary file with the new one you just extracted (e.g., overwrite /usr/local/bin/conhive-agent or the binary in your manual installation path).
6. Check Permissions (Linux/macOS): Ensure the new binary has execute permissions (chmod +x /path/to/conhive-agent).
7. Restart the Agent:
   • If running as a service: sudo systemctl start conhive-agent.service
   • If running manually: Execute the run command again.
   • If running in Docker: (See Docker method below - manual replacement inside container is not typical).
8. Verify: Check the agent version and ensure it’s functioning correctly.

---

Method 4: Updating Docker Container

If you are running the agent via Docker:

1. Pull Latest Image: Fetch the latest version of the agent image from Docker Hub.

   docker pull ai2hive/conhive-agent:latest

2. Stop and Remove Old Container: Stop the currently running agent container and remove it. Your configuration should ideally be stored in a mapped volume, so it persists.

   docker stop conhive-agent # Use the name you assigned
   docker rm conhive-agent

3. Run New Container: Start a new container using the updated image, ensuring you re-apply the same volume mappings (-v), port mappings (-p), and other configurations (--restart, --name, etc.) you used previously.

   # Example run command - adjust volume paths and other flags as needed
   docker run -d --name conhive-agent -p 5050:5050 \
     -v /path/on/host/to/conhive/workdir:/app/workdir \
     --restart always \
     ai2hive/conhive-agent:latest

4. Verify: Check the logs (docker logs conhive-agent) and access the web interface or API to ensure the updated agent is running correctly with your configuration.

Choose the update method that corresponds to your installation type and comfort level. Using the provided scripts (update_conhive_agent.sh or installer.sh) is generally recommended for ease of use and safety features like automatic backups and rollbacks.