Documentation
📘 Commands
upgrade

upgrade

rfswift upgrade

Upgrade containers to newer image versions while preserving selected data directories.

Synopsis 

rfswift upgrade -c CONTAINER_NAME [-i IMAGE_NAME] [-r REPOSITORIES]

The upgrade command follows this pattern: pull new image → create new container → copy preserved directories → inherit original container name. This enables seamless version upgrades while maintaining important data.

Options

Flag Description Required Example
-c, --container STRING Container name or ID to upgrade Yes -c my_container
-i, --image STRING Target image name/tag No (defaults to latest) -i telecom_15012025
-r, --repositories STRING Comma-separated directories to preserve No -r /root/tools,/opt/data

Examples

Basic Usage

Upgrade to latest version:

rfswift upgrade -c my_container

Upgrade to specific version:

rfswift upgrade -c sdr_work -i penthertz/rfswift_noble:sdr_full

Upgrade with preserved directories:

rfswift upgrade -c analysis_work \
  -i penthertz/rfswift_noble:sdr_full \
  -r /root/scripts,/root/captures,/opt/tools

Downgrade to previous version:

rfswift upgrade -c production -i penthertz/rfswift_noble:v0.6.4

How Upgrade Works

Upgrade Process

The upgrade command follows this sequence:

  1. Validate: Check source container exists
  2. Pull: Download target image (if not present locally)
  3. Create: Start new container from target image
  4. Copy: Transfer preserved directories from old to new container
  5. Stop: Stop old container
  6. Rename: Rename old container (adds _old suffix)
  7. Inherit: New container inherits original name
  8. Cleanup: Old container remains stopped for verification
  graph LR
    A[Old Container] -->|Pull Image| B[New Image]
    B -->|Create| C[New Container]
    A -->|Copy Directories| C
    A -->|Stop & Rename| D[Old Container_old]
    C -->|Inherit Name| E[New Container with Original Name]

What Gets Preserved

Content Preserved? How
Directories in -r flag ✅ Yes Copied to new container
Files in preserved dirs ✅ Yes Complete copy
Other directories ❌ No Use new image defaults
Container name ✅ Yes Inherited by new container
Volume bindings ✅ Yes Automatically inherited
Network settings ✅ Yes Automatically inherited
Port bindings ✅ Yes Automatically inherited
Device mappings ✅ Yes Automatically inherited
Capabilities ✅ Yes Automatically inherited
Cgroup rules ✅ Yes Automatically inherited
Environment variables ✅ Yes Automatically inherited
Privileged mode ✅ Yes Automatically inherited
Seccomp profile ✅ Yes Automatically inherited

The upgrade command now automatically preserves all host bindings, network settings, device mappings, capabilities, cgroup rules, and port bindings from the original container. A timestamped backup image is created before the old container is removed.

What Doesn’t Get Preserved

  • ❌ Files outside of -r directories (new image defaults apply)
  • ❌ Running processes (container is restarted fresh)

Troubleshooting

Container Not Found

Error: Error: No such container: container_name

Solutions:

# List containers
rfswift last

Image Pull Failed

Error: Error pulling image

Solutions:

# Check network connectivity
ping registry.hub.docker.com

# Pull manually first
docker pull penthertz/rfswift_noble:sdr_full

# Retry upgrade
rfswift upgrade -c container -i penthertz/rfswift_noble:sdr_full

Preserved Directory Not Found

Error: Directory /root/nonexistent not found in source container

Solutions:

# Check what directories exist
rfswift exec -c old_container
ls -la /root/
exit

# Adjust -r flag to existing directories only
rfswift upgrade -c container -r /root/existing,/opt/tools

Old Container Still Running

Problem: Upgrade completes but old container still active

Solution:

# Stop old container manually
rfswift stop -c container_old

# Verify new container is running
docker ps | grep container

# Remove old container when satisfied
rfswift remove -c container_old

Configuration Lost After Upgrade

Problem: Network/volume/device settings missing after upgrade

Note: This should no longer occur — RF Swift now automatically preserves all container settings (bindings, devices, network, capabilities, cgroups, ports) during upgrade. If you experience this issue, ensure you’re running the latest version of RF Swift.

Workaround (for older versions):

# Document current configuration before upgrade
docker inspect old_container > old_container_config.json

# After upgrade, reconfigure manually
rfswift bindings add -c container -s ~/data -t /root/data
rfswift capabilities add -c container -p NET_ADMIN
rfswift cgroups add -c container -r "c 189:* rwm"
rfswift ports bind -c container -b "8080:8080/tcp"

Rollback Failed

Problem: Can’t restore old container after bad upgrade

Solution:

# If you have backup
rfswift import container -i backup.tar.gz -n container_restored
rfswift run -i container_restored -n container

# If old container still exists
rfswift remove -c container  # Remove bad new container
rfswift rename -n container_old -d container
rfswift exec -c container

Related Commands

  • run - Create new containers
  • commit - Save container state before upgrade
  • export - Backup before upgrade
  • import - Restore from backup if upgrade fails
  • images - Check available images for upgrade
⬆️
Always Backup First: Before upgrading, create a backup with export container. This allows easy rollback if the upgrade has issues. The old container is kept as container_old for verification.
Settings Preserved: RF Swift now automatically inherits all container settings (bindings, devices, network mode, capabilities, cgroup rules, ports, environment variables) from the original container during upgrade. No manual reconfiguration needed.
Selective Preservation: Use the -r flag to preserve only necessary directories. Preserving too much may carry over conflicts, while preserving too little requires more post-upgrade setup. Balance based on your needs!
Last updated on
downloadbuild