Migration from older setups

12. Migration from older setups

If you have an older GateControl install with a named Docker volume (the historical default), you can migrate to the recommended /opt/gatecontrol/ layout with a ~15-second downtime. Named volumes are invisible to the host filesystem and make backups awkward; bind-mounts fix that.

Steps:

# 1. Verify source volume
docker inspect gatecontrol --format '{{range .Mounts}}{{.Type}} {{.Source}}{{"\n"}}{{end}}'
# if "volume <path>" appears, proceed. If "bind <path>" already — you are done.

# 2. Prepare new location
mkdir -p /opt/gatecontrol
cp /path/to/old/.env /opt/gatecontrol/.env
cat > /opt/gatecontrol/docker-compose.yml <<'EOF'
services:
  gatecontrol:
    image: ghcr.io/callmetechie/gatecontrol:latest
    container_name: gatecontrol
    network_mode: host
    cap_add:
      - NET_ADMIN
    volumes:
      - ./data:/data
    env_file:
      - .env
    restart: unless-stopped
EOF

# 3. Stop old, copy data, start new (brief downtime)
cd /path/to/old  # where the old docker-compose.yml lives
docker compose down

mkdir -p /opt/gatecontrol/data
VOL_PATH=$(docker volume inspect <old-volume-name> --format '{{.Mountpoint}}')
cp -a "$VOL_PATH"/. /opt/gatecontrol/data/
chown -R 101:102 /opt/gatecontrol/data

cd /opt/gatecontrol
docker compose up -d

# 4. Verify
docker inspect gatecontrol --format '{{range .Mounts}}{{.Type}} {{.Source}}{{"\n"}}{{end}}'
# should now show: bind /opt/gatecontrol/data
curl -s http://127.0.0.1:3000/health | jq

Keep the old named volume around for at least 24 hours as a fallback. Once you are confident the new setup works, remove it:

docker volume rm <old-volume-name>