Upgrading Edge Client#

If you are not upgrading from a previous version, for instructions on how to register a new device from scratch, please refer to Device Registration.

Version 2.5.0 -> 3.0.0#

To upgrade your edge device from version 2.5.0 to 3.0.0 you will need to update:

  • User and group IDs

  • Docker socket permissions

  • Edge Manager docker-compose file

  • File/Folder permissions for the Edge Client Volume

Copy the following script onto your device and run to update user and group permissions:

chmod +x user_group_2_5-3-0.sh
sudo ./user_group_2_5-3-0.sh
user_group_2_5-3-0.sh#
 1#!/bin/bash
 2
 3[ "$EUID" -ne 0 ] && echo "Please run as root" && exit 1
 4
 5# Update docker group
 6if getent group docker > /dev/null; then
 7  groupmod --gid 49999 docker
 8else
 9  groupadd -o --gid 49999 docker
10fi
11
12# Ensure user with UID 49999 exists and is in the docker group
13USER_49999=$(getent passwd 49999 | cut -d: -f1)
14if [ -z "$USER_49999" ]; then
15  adduser --disabled-password --uid 49999 --gid 49999 app
16  USER_49999="app"
17else
18  usermod -aG docker $USER_49999
19fi
20
21# Update docker socket permissions
22chown -R root:49999 /var/run/docker.sock
23
24# Verify updates
25DOCKER_GID=$(getent group docker | cut -d: -f3)
26SOCK_GROUP=$(stat -c '%g' /var/run/docker.sock)
27echo "-----------------------------"
28echo "OctaiPipe v3.0 Configuration:"
29[ "$DOCKER_GID" -eq 49999 ] && echo "✅ Docker group ID: 49999" || echo "❌ Docker group ID: $DOCKER_GID (should be 49999)"
30[ -n "$USER_49999" ] && echo "✅ User with UID 49999: $USER_49999" || echo "❌ No user with UID 49999 found"
31[ "$SOCK_GROUP" -eq 49999 ] && echo "✅ Docker socket group ID: 49999" || echo "❌ Docker socket group ID: $SOCK_GROUP (should be 49999)"
32echo "-----------------------------"

Before running the next script, ensure that the Edge Client on your vm has been stopped. Navigate to the directory containing your Edge Manager docker-compose.yml file and run:

docker compose down

Run docker ps to check and ensure that the Edge Client is no longer running.

Copy the following script onto your device and run to upgrade the existing registered Edge Client docker-compose.yml from version 2.5.x to 3.0.x:

chmod +x edge_device_2_5-3_0.sh
./edge_device_2_5-3_0.sh <path/to/your/docker-compose.yml>
edge_device_2_5-3_0.sh#
 1#!/bin/bash
 2
 3# Check if a compose file was provided and exists
 4if [ $# -ne 1 ]; then
 5  echo "Usage: $0 <docker-compose.yml>"
 6  exit 1
 7elif [ ! -f "$1" ]; then
 8  echo "Error: File $1 not found"
 9  exit 1
10fi
11
12# Get volume name from docker compose
13VOLUME_NAME=$(grep -o "name: octaipipe_[^ ]*" "$1" | head -1 | awk '{print $2}')
14
15if [ -z "$VOLUME_NAME" ]; then
16  echo "Warning: Could not extract volume name from $1"
17  echo "Volume migration will be skipped"
18else
19  # Create a temporary container to migrate data from old path to new path
20  echo "Migrating data from /home/octaipipe/.octaipipe to /home/app/.octaipipe"
21  docker run --rm -v "$VOLUME_NAME:/data" alpine sh -c '
22    if ! [ -d /data ]; then
23      echo '\''ERROR: Volume '"$VOLUME_NAME"' does not appear to be mounted correctly at /data in the temporary container.'\''
24      echo '\''Skipping ownership update.'\''
25      exit 1
26    fi
27
28    if [ -n "$(ls -A /data 2>/dev/null)" ]; then
29      chown -R 49999:49999 /data
30      CHOWN_EXIT_CODE=$? 
31      if [ $CHOWN_EXIT_CODE -eq 0 ]; then 
32        echo '\''INFO: Ownership update for existing data in volume '"$VOLUME_NAME"' completed.'\''
33      else
34        echo "ERROR: Failed to update ownership for data in volume '"$VOLUME_NAME"'. chown exit code was $CHOWN_EXIT_CODE." 
35        exit 1
36      fi
37    fi
38  '
39  DOCKER_RUN_EXIT_CODE=$?
40  if [ $DOCKER_RUN_EXIT_CODE -ne 0 ]; then
41    echo "ERROR: The data migration/ownership step failed with exit code $DOCKER_RUN_EXIT_CODE."
42    echo "Please check the messages above. The docker-compose.yml file was NOT modified due to above error."
43    exit $DOCKER_RUN_EXIT_CODE
44  fi
45fi
46
47# Create a backup of original docker compose file
48cp "$1" "$1.backup"
49echo "Created backup at $1.backup"
50
51# Update docker compose file to version 3.0.0
52TMP_FILE=$(mktemp)
53sed 's|octaipipe/octaipipe_manager:.*|octaipipe/octaipipe_manager:3.0.0|g' "$1" | \
54  awk '!/group_add:/ && !index($0, "- '\''1080'\''")' | \
55  sed 's|/home/octaipipe/.octaipipe|/home/app/.octaipipe|g' | \
56  sed 's|chown -R 1080:1080 /home/app/.octaipipe|/bin/sh -c "mkdir -p /home/app/.octaipipe/outputs /home/app/.flwr/apps \&\& chmod 2770 /home/app/.octaipipe /home/app/.flwr \&\& chown -R 49999:49999 /home/app/.octaipipe /home/app/.flwr"|g' | \
57  sed 's|user: "1080:1080"|user: "49999:49999"|g' > "$TMP_FILE"
58mv "$TMP_FILE" "$1"
59echo "Updated $1 to OctaiPipe v3.0 format"

After the script has successfully updated your docker-compose.yml file, restart your Edge Client services by running:

docker compose up -d

Note that depending on your device permissions you may need to run the above command with sudo.

Manual Upgrade#

If you run into any issues upgrading your Edge Client using these automated scripts and are happy to delete and recreate your Edge Client, follow these instructions:

  1. Down the Edge Client:

    • From the directory containing your Edge Manager docker-compose.yml file, run:

    docker compose down

  2. Delete your existing Edge Client docker volume:

    docker volume rm octaipipe_<your_device_id>

  3. Delete the Device in the Portal:

    • From the OctaiPipe Portal, navigate to the Devices page, select your device and click DELETE to delete the device you are upgrading.

  4. Re-register your device and setup user using Device Registration Guide

  5. Change permissions of files/folders read by OctaiPipe containers where necessary.