.. _sec-bundledplugins-softwareupdate: Software Update Plugin ====================== The Software Update Plugin allows receiving notifications about new releases of OctoPrint or installed plugins which registered with it and -- if properly configured -- also applying the found updates. .. _sec-bundledplugins-softwareupdate-firststeps: First Steps ----------- Out of the box the Software Update Plugin will be able to notify you of any updates that might be available for your OctoPrint installation or any plugins that registered themselves with it. In order to also be able to update your OctoPrint installation, you'll need to configure at least OctoPrint's checkout folder, and you also should configure the restart commands for OctoPrint and the whole server. For configuring the plugin you'll need to go into OctoPrint's Settings Dialog, navigate to the Software Upda.. _section therein and once you are there click on the little wrench icon in the upper right corner. .. _fig-bundledplugins-softwareupdate-plugin-configuration: .. figure:: ../images/bundledplugins-softwareupdate-plugin-configuration.png :align: center :alt: Software Update plugin configuration dialog The Software Update plugin configuration dialog There you can adjust the following settings: * **OctoPrint checkout folder**: This should be the path to OctoPrint's git checkout folder (``/home/pi/OctoPrint`` for OctoPi or `manual installs following the Raspberry Pi setup guide `_). This must be set to allow updating from within OctoPrint .. note:: OctoPi releases 0.12.0 and later ship with this already setup for you. .. note:: **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 0.11.0 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 version tracking**: Whether you want to track OctoPrint *releases* or every *commit*. Usually you want to select "Release" here which is also the default, unless you are a developer. * **OctoPrint Release Channel**: The release channel of OctoPrint to track for updates. If you only want stable versions, select "Stable" here which is also the default. "Maintenance RCs" will also allow you to update to maintenance release candidates, "Devel RCs" will also allow you to update to development release candidates. If in doubt, leave it at "Stable". `Read more about Release Channels here `_. * **Version cache TTL**: The "time to live" of the cache OctoPrint will use to temporarily persist the version information for the various components registered with the plugin, so that they don't have to be queried from the internet every time you load the page. Defaults to 24h, you usually shouldn't need to change that value. More settings are available by :ref:`editing the correspondi.. _section in config.yaml `. That restart commands for OctoPrint and the whole server can be configured under Settings > Server. .. _sec-bundledplugins-softwareupdate-configuration: Configuring the Plugin ---------------------- .. code-block:: yaml 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 # pip command, if another one than the automatically detected one should be # used - should normally NOT be necessary and hence set pip_command: /path/to/pip .. _sec-bundledplugins-softwareupdate-configuration-versionchecks: Version checks ++++++++++++++ * ``github_release``: Checks against releases published on Github. Additional config parameters: * ``user``: (mandatory) Github user the repository to check belongs to * ``repo``: (mandatory) Github repository to check * ``prerelease``: ``True`` or ``False``, default ``False``, set to ``True`` to also include releases on Github marked as prerelease. * ``release_branch``: Branch name to check against ``target_comittish`` field in Github release data - release will only be included if the values match. Defaults to being unset, in which case no match will be performed. * ``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: * ``user``: (mandatory) Github user the repository to check belongs to * ``repo``: (mandatory) 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: * ``checkout_folder``: (mandatory) 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: * ``command``: (mandatory) 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 :ref:`hook `. Additional config parameters: * ``python_checker``: (mandatory) A python callable which returns version information and whether the current version is up-to-date or not, see below for details. .. _sec-bundledplugins-softwareupdate-configuration-updatemethods: 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), ``{branch}`` for the branch to switch to to access the release, ``{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 :ref:`hook `. A python callable which performs the update, see below for details. .. _sec-bundledplugins-softwareupdate-configuration-patterns: Common configuration patterns +++++++++++++++++++++++++++++ Example for a setup that allows "bleeding edge" updates of OctoPrint under OctoPi (the ``update_script`` gets configured correctly automatically by the plugin itself): .. code-block:: yaml plugins: softwareupdate: checks: octoprint: type: github_commit user: foosel repo: OctoPrint branch: devel update_folder: /home/pi/OctoPrint Plugin installed via pip and hosted on Github under ``https://github.com/someUser/OctoPrint-SomePlugin``, only releases should be tracked: .. code-block:: yaml plugins: softwareupdate: checks: some_plugin: type: github_release user: someUser repo: OctoPrint-SomePlugin pip: 'https://github.com/someUser/OctoPrint-SomePlugin/archive/{target}.zip' The same, but tracking all commits pushed to branch ``devel`` (thus allowing "bleeding edge" updates): .. code-block:: yaml plugins: softwareupdate: checks: some_plugin: type: github_commit user: someUser repo: OctoPrint-SomePlugin branch: devel pip: 'https://github.com/someUser/OctoPrint-SomePlugin/archive/{target}.zip' .. _sec-bundledplugins-softwareupdate-hooks: Hooks ----- .. _sec-bundledplugins-softwareupdate-hooks-check_config: octoprint.plugin.softwareupdate.check_config ++++++++++++++++++++++++++++++++++++++++++++ .. py:function:: update_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``. .. code-block:: python # 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}.zip" ) ) __plugin_hooks__ = { "octoprint.plugin.softwareupdate.check_config": get_update_information } :return: A dictionary of check configurations as described above :rtype: dict .. _sec-bundledplugins-softwareupdate-helpers: Helpers ------- .. _sec-bundledplugins-softwareupdate-helpers-version_checks: 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``). .. _sec-bundledplugins-softwareupdate-helpers-updaters: updaters ++++++++ ``updaters`` module of the Software Update plugin, allows reusing the bundled updater variants from plugins (e.g. wrapped in a ``python_updater``). .. _sec-bundledplugins-softwareupdate-helpers-exceptions: exceptions ++++++++++ ``exceptions`` module of the Software Update plugin. .. _sec-bundledplugins-softwareupdate-helpers-util: util ++++ ``util`` module of the Software Update plugin. .. _sec-bundledplugins-softwareupdate-source: 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``.