Troubleshooting and Best Practices

When you work with online repositories, it is important to understand how different actions affect the repositories. Troubleshooting lists use cases that should be handled carefully so they do not lead to errors in end user host. Best Practices lists some useful practices that might be helpful in your daily work with online repositories.


Dependencies to Online Repository

Immediately after an end user installs something from an online repository via an online installer or a maintenance tool, a local dependency from the end user host to the online repository is established. Thus you should follow the following quidelines:

  • Do not remove repositories from the online server simply by deleting the repositories. Instead, you should add the following setting in the root repository:
    <Repository action="remove" url="...">
  • Do not manually change content in online repositories as it causes a SHA-1 checksum mismatch.
  • If you push an update for a component in an online repository, you must always remember to increase the version number of the updated component. See Updating Repository.

Unsuccessful Updates

If something goes wrong while you are uploading either content or Updates.xml, do not upload the previous versions from your own backup-files. The Qt Installer Framework does not support roll-back functionality. Thus the maintenance tool does not allow end users to install again the previous version that is known to work.

You should create a new version of the broken component and upload it to the online repository. End users need to uninstall the broken component and install the fixed one instead.

Mirroring and File Caching

If the web server uses mirroring or file caching, it is important to ensure that all content has been uploaded to the server before you upload a new version of Updates.xml.

Some web servers support setting cache expiration time to zero for some files. In this case, you could set the cache expiration time to zero for Updates.xml.

Best Practices

Uploading to Test Server

You can use a test server where you upload the repository builds for testing purposes. After you have verified the content, you can upload it publicly available to the web server that is used by online installers.

© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.