Update

Update Lager Box code from GitHub repository

Update Lager Box software on Lagerboxes with comprehensive progress tracking and automatic configuration.

Syntax

lager update [OPTIONS]

Options

Option	Description
--box BOX	Lagerbox name or IP address
--all	Update all saved boxes that need updating
--version VERSION	Release tag, semver pin, or branch to update to (default: main). See Version pinning.
--yes	Skip confirmation prompt
--check	Dry run: report what would change without modifying the box
--skip-restart	Skip container restart after update
--check-jlink	Check for J-Link and offer to install if missing
--force	Force fresh Docker build by removing cached image
--verbose / -v	Show detailed output (default shows progress bar)

Either --box or --all is required. They cannot be used together.

Version pinning

Since lager 0.22.0, a semver value passed to --version — with or without a leading v (e.g. 0.26.0 or v0.26.0), including common pre-release suffixes (-rc1, -beta2, -alpha, -preview) — resolves to the release tag vX.Y.Z. Release tags are the single source of truth for a pinned version.

# All three pin the same release tag (v0.26.0)
lager update --box my-lager-box --version v0.26.0 --yes
lager update --box my-lager-box --version 0.26.0 --yes
lager update --box my-lager-box --version v0.27.0-rc1 --yes

Any other value (main, staging, or a feature branch name) resolves to origin/<name> as before.

Per-release version branches (bare X.Y.Z branches) are deprecated in favour of tags. A value like 0.26.0 now resolves to the tag v0.26.0, not a branch of the same name. See RELEASE_PROCESS.md in the repository.

Usage

Basic Update

# Update to latest main branch
lager update --box my-lager-box --yes

# Update to staging branch
lager update --box my-lager-box --version staging --yes

# Update with verbose output
lager update --box my-lager-box --yes --verbose

# Force fresh Docker build (use for major code changes)
lager update --box my-lager-box --force --yes

Update All Boxes

The --all flag queries every saved box’s version and updates only those that are behind the current CLI version.

# Update all boxes that need updating
lager update --all --yes

# Preview which boxes need updating (without --yes, shows confirmation)
lager update --all

How --all works:

1. Queries each saved box’s /cli-version endpoint
2. Compares box version against the current CLI version
3. Builds a list of boxes that need updating (version older than CLI or unknown)
4. Skips boxes that are already current, newer, or unreachable
5. Updates each box sequentially
6. Displays a summary of successes and failures

Example output:

CLI version: 0.3.22

Checking box versions...

  lab-box-1    0.3.20  will update
  lab-box-2    0.3.22  current
  pi-box       0.3.19  will update
  offline-box  ---     unreachable (skipped)

2 box(es) need updating. Proceed? [Y/n]: y

Updating lab-box-1...
  [OK] Updated to 0.3.22

Updating pi-box...
  [OK] Updated to 0.3.22

Update complete (45.2s total)
  Successful: 2
  Failed:     0

Skip Container Restart

# Update code but don't restart containers
lager update --box my-lager-box --skip-restart --yes

# Manually restart later
ssh lagerdata@my-lager-box 'cd ~/box && ./start_box.sh'

J-Link Installation Check

# Check if J-Link is installed, offer to install if missing
lager update --box my-lager-box --check-jlink --yes

---

Update Process

The update command performs the following steps (shown in progress bar):

1. SSH Connection - Establish secure connection to Lager Box
2. Git Repository Check - Validate lager repository exists
3. Git Pull - Pull latest code from specified branch
4. Udev Rules - Install USB instrument access rules
5. Docker Build - Build updated containers (no-cache)
6. Firewall Setup - Configure UFW if needed
7. Customer Binaries - Set up custom binaries directory
8. J-Link Check - Verify debug probe software (optional)
9. Version Update - Record version in /etc/lager/version
10. Container Restart - Start updated containers
11. Status Verification - Confirm containers are running

---

Version Tracking

The Lager Box tracks its current version in /etc/lager/version. You can sync versions from all Lager Boxes:

# Sync versions from all configured boxes
lager boxes sync

---

SSH Key Authentication

The update command automatically detects SSH key configuration:

• With SSH keys: Updates proceed without password prompts
• Without SSH keys: Prompts for password (interactive mode)

To set up SSH keys:

ssh-copy-id lagerdata@<box-ip>

---

Firewall Auto-Configuration

If UFW is not configured, the update command will:

1. Detect missing firewall rules
2. Offer to install and configure UFW
3. Apply secure defaults (VPN-only access to Lager ports)

# Manual firewall configuration
cli/deployment/security/secure_box_firewall.sh <box-ip>

---

Examples

# Standard update workflow
lager update --box lab-lager-box --version main --yes

# Update all boxes at once
lager update --all --yes

# Update all boxes to staging branch
lager update --all --version staging --yes

# Force fresh build on a specific box
lager update --box my-lager-box --force --yes

# Verbose update for troubleshooting
lager update --box my-lager-box --verbose

---

Troubleshooting

Update Fails at Git Pull

# Check the remote URL (should be HTTPS, not SSH)
ssh lagerdata@<box-ip> 'cd ~/box && git remote get-url origin'

# If it shows [e-mail]:..., switch to HTTPS:
ssh lagerdata@<box-ip> 'cd ~/box && git remote set-url origin https://github.com/lagerdata/lager.git'

Container Build Fails

# SSH in and check Docker status
ssh lagerdata@<box-ip>
docker ps -a
docker logs controller

Firewall Issues

# Check firewall status
ssh lagerdata@<box-ip> 'sudo ufw status verbose'

# Re-run firewall setup
cli/deployment/security/secure_box_firewall.sh <box-ip>

---

Notes

• Progress bar is disabled when --verbose is used
• Container builds use --no-cache to ensure fresh builds
• Version defaults to main if not specified
• Update automatically verifies container health after restart
• --all checks versions automatically and only updates outdated boxes
• --force removes cached Docker images before building (useful after major code changes)
• --box and --all are mutually exclusive