PasswordLab Software Upgrade Guide

Upgrading the PasswordLab software ensures you benefit from the latest features, security patches, and performance improvements. Follow these steps to safely upgrade your installation.

1. Preparation

a. Backup Your Data

Before any upgrade, always back up your database and configuration files.

Database Backup:

mysqldump -u [db_username] -p [db_name] > /root/passwordlab-backup-$(date +%Y%m%d).sql

Replace [db_username] and [db_name] with values from /root/database.txt.

Configuration Backup:

cp /etc/passwordlab/passwordlab.json /etc/passwordlab/passwordlab-backup-$(date +%Y%m%d).json

b. Notify Users

Inform users about a short maintenance window, as the service will be restarted.

2. Stop the PasswordLab Service

systemctl stop passwordlab

3. Download the Latest PasswordLab Binary

wget -O /tmp/passwordlab.zip http://download.passwordlab.io/latest.zip

4. Verify the Downloaded Binary

Get the latest SHA1 checksum:

curl -s https://download.passwordlab.io/shasum.txt

Unzip the downloaded file:
```
unzip -o /tmp/passwordlab.zip -d /tmp/
```
Check the downloaded file:
```
sha1sum /tmp/passwordlab
```
Compare the output with the official checksum. Only proceed if they match.

5. Replace the Old Binary

Create a backup of the existing binary:

cp /usr/local/bin/passwordlab /usr/local/bin/passwordlab-backup

Copy the new binary:
```
cp /tmp/passwordlab /usr/local/bin/
```
Set executable permissions:
```
chmod +x /usr/local/bin/passwordlab
```

6. Run Database Migration

After updating the binary, run the migration command to upgrade the database schema:

/usr/local/bin/passwordlab --exec upgrade

This ensures your database structure is compatible with the new binary version.

7. Restart the PasswordLab Service

systemctl start passwordlab

8. Verify the Upgrade

Check service status:
```
systemctl status passwordlab
```
It should show as “active (running)”.
Test the web interface to ensure the application is running as expected.

9. Rollback (If Needed)

If you encounter issues after the upgrade, follow these steps in order:

Stop the PasswordLab service (if running):
```
systemctl stop passwordlab
```
Make sure the service is stopped before proceeding:
```
systemctl status passwordlab
```
Restore the database from your backup with new database name:
This is a precautionary step in case the new binary changed the database structure.
```
mysql -u [db_username] -p [new_db_name] < /root/passwordlab-backup-YYYYMMDD.sql
```
Replace [db_username] and [new_db_name] with your actual values.
Update the new database name in configuration file:
```
nano /etc/passwordlab/passwordlab.json
```
Change the database name to [new_db_name] and save the file.

Delete the latest binary and replace it with the backup binary:

rm /usr/local/bin/passwordlab
cp /usr/local/bin/passwordlab-backup /usr/local/bin/passwordlab
chmod +x /usr/local/bin/passwordlab
systemctl restart passwordlab

This order is important: the new binary may have changed the database structure, so always restore the database first, then the old binary.

10. Clean Up

Remove old backup files if no longer needed.
Monitor logs for any errors:
```
journalctl -u passwordlab -f
```

Best Practices

Always test upgrades in a staging environment before production.
Schedule upgrades during low-usage periods.
Keep regular backups and document upgrade steps for your team.

By following this guide, you can safely upgrade your PasswordLab binary with minimal risk and downtime.