Upgrading WireGuard Easy from Version 13 to 14 on Docker

With the release of WireGuard Easy version 14, there are some breaking changes. Follow these steps to smoothly upgrade from version 13 to 14.

Please note that I’m using docker compose for running it.

1. Stopping the Existing Container

Start by stopping and removing the current container:

# Stop and remove the container
docker compose down

2. Updating the Docker Image

Optionally, update the wg-easy tag in your docker-compose file to version 14, especially if you were using a specific tag for version 13. If you are using the latest tag, you can skip this step.

# Example of updating the tag in docker-compose.yml
image: ghcr.io/wg-easy/wg-easy:14

Now pull the latest version of the image:

# Pull the new version
docker pull ghcr.io/wg-easy/wg-easy

3. Generating a New Password Hash

You need to generate a new password hash for version 14. Run the following command to generate it and update your .env file accordingly:

# Generate the password hash
docker run --rm -it ghcr.io/wg-easy/wg-easy wgpw 'YOUR_EXISTING_PASSWORD'
 
# Example output:
# PASSWORD_HASH='$2b$12$coPqCsPtcFO.Ab99xylBNOW4.Iu7OOA2/ZIboHN6/oyxca3MWo7fW'

Update your .env file with the new hashed password:

# .env
- PASSWORD=...
+ PASSWORD_HASH=...

4. Updating docker-compose.yml

Next, update the docker-compose.yml file to use the new PASSWORD_HASH environment variable:

- PASSWORD={$PASSWORD}
+ PASSWORD_HASH={$PASSWORD_HASH}

Optionally, change the wg-easy version in your compose file if you previously used a version-specific tag.

5. Starting the Updated Service

To bring up the updated service, run:

docker compose up -d

6. Troubleshooting

If you encounter errors when opening the dashboard in your browser, such as:

• The dashboard shows a spinner indefinitely.
• The manifest returns a 401 Unauthorized error.
• A Vue error: ReferenceError: restoreConfig is not defined.

You can resolve these issues by clearing your browser cache. After that, everything should work correctly.

Reference:

• Issue #1434