Update

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:

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

Example output:

CLI version: 0.3.22

Checking box versions...

  my-lager-box  0.3.20  will update
  staging-box   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 my-lager-box...
  [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):

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

Version Tracking

The Lager Box tracks its current version in /etc/lager/version. The lager boxes listing queries each configured box and shows its current version in the version column:

# List all boxes with their current versions
lager boxes

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:

Detect missing firewall rules
Offer to install and configure UFW
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 my-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 git@github.com:..., 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

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Development

Utilities

Syntax

Options

Version pinning

Usage

Basic Update

Update All Boxes

Skip Container Restart

J-Link Installation Check

Update Process

Version Tracking

SSH Key Authentication

Firewall Auto-Configuration

Examples

Troubleshooting

Update Fails at Git Pull

Container Build Fails

Firewall Issues

Notes

​Syntax

​Options

​Version pinning

​Usage

​Basic Update

​Update All Boxes

​Skip Container Restart

​J-Link Installation Check

​Update Process

​Version Tracking

​SSH Key Authentication

​Firewall Auto-Configuration

​Examples

​Troubleshooting

​Update Fails at Git Pull

​Container Build Fails

​Firewall Issues

​Notes

Syntax

Options

Version pinning

Usage

Basic Update

Update All Boxes

Skip Container Restart

J-Link Installation Check

Update Process

Version Tracking

SSH Key Authentication

Firewall Auto-Configuration

Examples

Troubleshooting

Update Fails at Git Pull

Container Build Fails

Firewall Issues

Notes