v0.3 checks

Updating to V0.3

Before updating

  1. Backup the database
  2. verify that usernames are unique do not clash and fix manually if necessary
  3. verify that emails are unique and do not clash and fix manually if necessary
  4. delete the api.secret_key from config file

Use docker image tryffel/virtualpaper:v0.3 or tryffel/virtualpaper:v0.3-arm64.

Note: this update will introduce database migrations that may potentially fail. To make sure the migration goes smoothly, please run the following checks before doing the update. Only proceed updating if the checks pass, and test again after you have fixed possible conflicts. If there are only a few users, it’s okay to check the values from the admin UI, but the database query will give exact results.

Why the additional checks?

Earlier it was possible to create several users which were not unique when lowercased. E.g. it was possible to create user with username ‘John’ and separate user with ‘john’. With v0.3 this is no longer possible and will result in a conflict. These existing users must be manually resolved before upgrading to v0.3.

The same applies to emails: several users might have had exactly or nearly same email (when lowercased). Starting with v0.3 email uniqueness will be enforced. If the system already has multiple users with the same email address, these too will result in a conflict. These email addresses will need to be manually resolved before updating the system.

1. Verify that usernames are case-insensitively unique.

Migration will fail if this is not satisfied.

E.g. usernames ‘John’ and ‘john’ are going to be invalid. One of the usernames must be changed to meet with the requirement. The safest option is to edit the username in the database and rerun the sql query until it does not return any rows.

Option A: Verify using admin UI

Verify manually using the administrator UI that each username case-insensitively unique.

Find out if there are duplicate usernames by running the following database query:

SELECT username, usernames_count
FROM (
    SELECT LOWER(public.users.name) AS username, COUNT(LOWER(name)) AS usernames_count FROM users
    GROUP BY LOWER(name)
     ) q
WHERE usernames_count > 1;

If there are any rows returned, these usernames must be resolved manually.

Query for changing username:

UPDATE users SET name='<new-username>' WHERE id=<user-id>;

2. Verify that emails are case-insensitively unique

Migration will fail if this is not satisfied.

E.g. emails ‘John@mail.com’ and ‘john@mail.com’ are going to be invalid. One of the emails must be changed to meet with the requirement. The safest option is to edit the email in the database and rerun the sql query until it does not return any rows.

Option A: Verify using admin UI

Verify manually using the administrator UI that each email is case-insensitively unique.

Find out if there are duplicate emails by running the following database query:

SELECT email, email_count
FROM (
    SELECT LOWER(email) AS email , COUNT(LOWER(email)) AS email_count FROM users
    GROUP BY LOWER(email)
     ) q
WHERE email_count > 1;

If there are any rows returned, these emails must be resolved manually.

Query for changing email:

UPDATE users SET email='<new-email>' WHERE id=<user-id>;

3. Delete the api.secret_key

Edit the configuration file and remove the secret_key from api-section. This will invalidate all existing authentication tokens but is required in order to generate new, longer secret key.

Updating

Only after all previous steps have been successfully completed, update the system:

  • all existing tokens will be invalidated and user needs to login again with each device
  • SECURITY: token signing key size has been increased. Previous size is considered a security risk. Please remove the api.secret_key (set it empty) and let the server recreate the key.

Use docker image tryffel/virtualpaper:v0.3 or tryffel/virtualpaper:v0.3-arm64.