Upgrading Waveshift Server¶

This guide shows you how to upgrade your Waveshift server to a new version.

Active Egress Servers

Ensure you have no active PoPs before upgrading, as this upgrade could result in active PoPs not being completely destroyed when the user requests it.
Leave 10 minutes after destroying all PoPs before carrying out the server upgrade.

Prerequisites

Ensure you have an active aws cli session with the correct credentials
wavectl installed and the deployment wavectl.json config file

OR

CLI access to the waveshift server via some other means e.g. aws ssm / ssh

Upgrade Process Overview¶

Upgrading Waveshift involves updating the Docker image versions in the systemd service files. The process is straightforward:

Install the latest wavectl from the release bundle
Connect to the Waveshift server via wavectl
Edit the systemd service files
Update the Docker image version
Reload and restart the service

Step-by-Step Guide¶

Install the latest wavectl release¶

wavectl upgrade

Failure to upgrade wavectl could cause undesirable outcomes

remove the old version of wavectl from its installation location
copy the latest release of wavectl to the same location

Interactive Demo¶

Watch this recording to see the server upgrade process as it happens (commands can be copy and pasted directly from the video).

Click the markers on the timeline to jump to specific steps:

Router Firmware Upgrades¶

After upgrading the Waveshift server, you should also upgrade the firmware on your GL.iNet router hubs.

Dedicated Guide Available

For detailed instructions on upgrading router firmware, see the Upgrading Router Firmware guide.

1. Connect to the Server¶

Fron your deployment directory containing wavectl.json. Use wavectl to start an SSM session to your Waveshift server:

wavectl start-session waveshift

2. Switch to Root User¶

Once connected, switch to the root user:

sudo su -

3. Edit the Waveshift Service File¶

Edit the Waveshift systemd service file:

vim /etc/systemd/system/waveshift.service

4. Update the Versions¶

Locate the Docker image references in the files. You'll see two lines with the image version:

The ExecStartPre line that pulls the new image
The ExecStart line that runs the container

Update both lines from the old version (e.g., v0.3.0) to the new version (e.g., v0.4.0):

/etc/systemd/system/waveshift.service

[Unit]                                                                                                 
Description=Waveshift Orchestrator Container                                                           
Requires=docker.service postgres.service                                                               
After=docker.service postgres.service                                                                  

[Service]                                                                                              
Restart=always                                                                                         
ExecStartPre=-/usr/bin/docker rm orchestrator                                                          
ExecStartPre=/bin/bash -lc "/usr/bin/docker pull europe-docker.pkg.dev/blackfire-artifacts-93fg8/blackfire/waveshift:v0.4.0"                                                                                  
ExecStart=/usr/bin/docker run --rm --name orchestrator \                                               
  --env-file /opt/waveshift/waveshift.env \                                                            
  --network waveshift \                                                                                
  europe-docker.pkg.dev/blackfire-artifacts-93fg8/blackfire/waveshift:v0.4.0                           
ExecStop=/usr/bin/docker stop orchestrator                                                             
TimeoutStopSec=30                                                                                      

[Install]                                                                                              
WantedBy=multi-user.target

5. Edit the Frontend Service File¶

Edit the Waveshift systemd service file:

vim /etc/systemd/system/frontend.service

/etc/systemd/system/frontend.service

[Unit]                                                                                                 
Description=Waveshift Orchestrator Container                                                           
Requires=docker.service postgres.service                                                               
After=docker.service postgres.service                                                                  

[Service]                                                                                              
Restart=always                                                                                         
ExecStartPre=-/usr/bin/docker rm orchestrator                                                          
ExecStartPre=/bin/bash -lc "/usr/bin/docker pull europe-docker.pkg.dev/blackfire-artifacts-93fg8/blackfire/waveshift-frontend:v0.4.0"                                                                                  
ExecStart=/usr/bin/docker run --rm --name orchestrator \                                               
  --env-file /opt/waveshift/waveshift.env \                                                            
  --network waveshift \                                                                                
  europe-docker.pkg.dev/blackfire-artifacts-93fg8/blackfire/waveshift-frontend:v0.4.0                           
ExecStop=/usr/bin/docker stop orchestrator                                                             
TimeoutStopSec=30                                                                                      

[Install]                                                                                              
WantedBy=multi-user.target

Save and exit the editor (:wq in vim).

6. Reload and Restart¶

Reload the systemd daemon and restart the service:

systemctl daemon-reload
systemctl restart waveshift frontend

7. Verify the Upgrade¶

Check the service status to ensure it started successfully:

systemctl status waveshift.service

You can also check the logs:

journalctl -u waveshift.service -f

You can also confirm the upgrade via docker with:

docker ps | grep v0.4.0

This will highlight the orchestrator containers with the new version.

Quick Upgrade Commands¶

# From local machine in deployment folder containing wavectl.json
# Connect to waveshift server
wavectl start-session waveshift

# The following commands are on the waveshift server:
# Switch to root user
sudo su -

# Edit the waveshift service files
sed -i -e 's/v0.3.0/v0.4.0/g' /etc/systemd/system/waveshift.service
sed -i -e 's/v0.3.0/v0.4.0/g' /etc/systemd/system/frontend.service

# Reload and restart the services
systemctl daemon-reload
systemctl restart waveshift frontend

# Confirm docker containers are running
docker ps | grep v0.4.0

Troubleshooting¶

Service Fails to Start¶

If the service fails to start after upgrading:

Check the logs for errors:
```
journalctl -u waveshift.service -n 50
```
Verify the Docker image was pulled successfully:
```
docker images | grep waveshift
```
Ensure the environment file exists and is readable:
```
ls -la /opt/waveshift/waveshift.env
```

Docker Pull Fails¶

If the Docker image pull fails:

Verify typo's within the service files
Verify the image version is correct

Rolling Back¶

If you need to roll back to a previous version, simply repeat the process with the old version number.

Version Compatibility¶

Version Compatibility

Always check the release notes before upgrading to ensure compatibility with your deployment. Some versions may require additional migration steps.

Best Practices¶

Monitor After Upgrade: Watch the service logs for a few minutes after upgrading to catch any issues early
Plan Downtime: The service will be unavailable during the restart, so plan accordingly