Plugin: Software Update

derpicknicker1 edited this page May 19, 2016 · 18 revisions

The Software Update plugin comes bundled with OctoPrint (starting with 1.2.0).

It allows receiving notifications about new releases of OctoPrint or installed plugins which registered with it and also applying the found updates.

Update notification

Overview of current versions

Configuration dialog for plugin settings

Update in progress

Automatic restart after update

Configuring the Plugin

plugins:
  softwareupdate:
    # the time-to-live of the version cache, in minutes
    cache_ttl: 60

    # configured version check and update methods
    checks:
      # "octoprint" is reserved for OctoPrint
      octoprint:
        # this defines an version check that will check against releases
        # published on OctoPrint's Github repository and an update method
        # utilizing an (included) update script that will be run on 
        # OctoPrint's checkout folder
        type: github_release
        user: foosel
        repo: OctoPrint
        update_script: '{python} "/path/to/octoprint-update.py" --python="{python}" "{folder}" "{target}"'
        update_folder: /path/to/octoprint/checkout/folder

      # further checks may be define here

Version checks

  • github_release: Checks against releases published on Github. Additional config parameters (mandatory in bold):
    • user: Github user the repository to check belongs to
    • repo: Github repository to check
    • prerelease: True or False, default False, set to True to also include releases on Github marked as prerelease.
    • release_compare: Method to use to compare between current version information and release versions on Github. One of python (version comparison using pkg_resources.parse_version, newer version detected if remote > current), semantic (version comparison using semantic_version package, newer version detected if remote > current) and unequal (string comparison, newer version detected if remote != current).
  • github_commit: Checks against commits pushed to Github. Additional config parameters (mandatory in bold):
    • user: Github user the repository to check belongs to
    • repo: Github repository to check
    • branch: Branch of the Github repository to check, defaults to master if not set.
  • git_commit: Checks a local git repository for new commits on its configured remote. Additional config parameters (mandatory in bold):
    • checkout_folder: The full path to the folder with a valid git repository to check.
  • command_line: Uses a provided script to determine whether an update is available. Additional config parameters (mandatory in bold):
    • command: The full path to the script to execute. The script is expected to return a 0 return code if an update is available and to return the display name of the available version as the final and optionally the display name of the current version as the next to final line on stdout.
  • python_checker: Can only be specified by plugins through the hook. Additional config parameters (mandatory in bold):
    • python_checker: A python callable which returns version information and whether the current version is up-to-date or not, see below for details.

Update methods

  • pip: An URL to provide to pip install in order to perform the update. May contain a placeholder {target} which will be the most recent version specifier as retrieved from the update check.
  • update_script: A script to execute in order to perform the update. May contain placeholders {target} (for the most recent version specified as retrieved from the update check), {folder} for the working directory of the script and {python} for the python executable OctoPrint is running under. The working directory must be specified either by an update_folder setting or if the git_commit check is used its checkout_folder setting.
  • python_updater: Can only be specified by plugins through the hook. A python callable which performs the update, see below for details.

Common configuration patterns

Plugin installed via pip and hosted on Github under https://github.com/someUser/OctoPrint-SomePlugin, only releases should be tracked:

plugins:
  softwareupdate:
    checks:
      some_plugin:
        type: github_release
        user: someUser
        repo: OctoPrint-SomePlugin
        pip: 'https://github.com/someUser/OctoPrint-SomePlugin/archive/{target_version}.zip' 

The same, but tracking all commits pushed to branch devel (thus allowing "bleeding edge" updates):

plugins:
  softwareupdate:
    checks:
      some_plugin:
        type: github_commit
        user: someUser
        repo: OctoPrint-SomePlugin
        branch: devel
        pip: 'https://github.com/someUser/OctoPrint-SomePlugin/archive/{target_version}.zip' 

Example for a setup that allows "bleeding edge" updates of OctoPrint under OctoPi (the update_script gets configured correctly automatically by the plugin itself):

plugins:
  softwareupdate:
    checks:
      octoprint:
        type: git_commit
        checkout_folder: /home/pi/OctoPrint

Making OctoPrint updateable on existing installations

If you updated OctoPrint to 1.2.0 or later from a previous existing install, you'll probably want to set up its software update configuration to allow it to update itself from now on.

This instructions are going to outline how to achieve that for standard installations (checked out from git, installed locally). If your setup differs from that, you'll need to adjust the update process accordingly, look at the available updaters and version checks above, maybe you can already tailor something from that to fit your specific setup.


Note: OctoPi releases 0.12.0 and later ship with this already setup for you!



Note for OctoPi 0.11.0 users: Please also take a look at the note at the very end of this FAQ entry. Due to a little issue in that OctoPi release you might have to fix the URL your OctoPrint checkout is using for updating. This can easily be done by SSHing into your OctoPi instance and doing this:

cd ~/OctoPrint
git remote set-url origin https://github.com/foosel/OctoPrint.git

OctoPrint >= 1.2.5

In your Software Update Plugin's settings dialog, click on the little button with the wrench in the upper right corner. Enter the checkout folder of you OctoPrint installation (on OctoPi that will be /home/pi/OctoPrint - if you installed your OctoPrint instance manually you'll have to adjust that path accordingly). Select "Release" tracking. Then save your changes.

If you also want OctoPrint to automatically be restarted on its own after an update, you'll also need to setup the global restart command. Still in the Settings, under "Server", fill out at least the restart command (on OctoPi that will be sudo service octoprint restart). Save your changes.

Finally restarty OctoPrint.

Whenever new releases become available, you should now be able to update right from the update notification.

OctoPrint < 1.2.5

In OctoPrint versions older than 1.2.5 you'll need to edit config.yaml and make it look like this (# ... indicates where your config.yaml might contain additional lines that are not of interest here):

# ...
plugins:
  # ...
  softwareupdate:
    # ...
    checks:
      # ...
      octoprint:
        update_folder: /home/pi/OctoPrint
      # ...
    octoprint_restart_command: sudo service octoprint restart
    environment_restart_command: sudo shutdown -r now
# ...

Note: You can copy and paste this YAML snippet into the Yamlpatcher to apply it to your config.yaml without having to edit it manually:

Yamlpatcher preview


If you are not running OctoPi or didn't setup OctoPrint following the Raspberry Pi setup guide you'll need to substitute /home/pi/OctoPrint with the folder you originally cloned OctoPrint into during initial setup.

Save the file, exit the editor, restart OctoPrint. Whenever new releases become available, you should now be able to update right from the update notification.

Hooks

octoprint.plugin.softwareupdate.check_config

hook(*args, **kwargs)

Returns additional check configurations for the Software Update plugin.

Handlers should return a Python dict containing one entry per check. Usually this will probably only be the check configuration for the plugin providing the handler itself, using the plugin's identifier as key.

The check configuration must match the format expected in the configuration (see description above). Handlers may also utilize the python_checker and python_updater properties to return Python callables that take care of performing the version check or the update.

python_checker is expected to be a callable matching signature and return value of the get_latest methods found in the provided version checkers in src/octoprint/plugins/softwareupdate/version_checks. python_updater is expected to be a callable matching signature and return value of the perform_update methods found in the provided updaters in src/octoprint/plugins/softwareupdate/updaters.

Example

The example single-file-plugin updates itself from Github releases published at the (fictional) repository https://github.com/someUser/OctoPrint-UpdatePluginDemo.

# coding=utf-8
from __future__ import absolute_import

def get_update_information(*args, **kwargs):
    return dict(
        updateplugindemo=dict(
            displayName=self._plugin_name,
            displayVersion=self._plugin_version,

            type="github_release",
            current=self._plugin_version,
            user="someUser",
            repo="OctoPrint-UpdatePluginDemo",

            pip="https://github.com/someUser/OctoPrint-UpdatePluginDemo/archive/{target_version}.zip"
        )
    )

__plugin_hooks__ = {
    "octoprint.plugin.softwareupdate.check_config": get_update_information
}

Helpers

version_checks

version_checks module of the Software Update plugin, allows reusing the bundled version check variants from plugins (e.g. wrapped in a python_checker).

updaters

updaters module of the Software Update plugin, allows reusing the bundled updater variants from plugins (e.g. wrapped in a python_updater).

exceptions

exceptions module of the Software Update plugin.

util

util module of the Software Update plugin.

Source Code

The source of the Software Update plugin is bundled with OctoPrint and can be found in its source repository under src/octoprint/plugins/softwareupdate.