From d60b852b27a68b9730fbd0225056e15b5bc21c68 Mon Sep 17 00:00:00 2001 From: Eric Callahan Date: Thu, 8 Jul 2021 10:52:56 -0400 Subject: [PATCH] docs: add documentation for latest changes to the update manager Signed-off-by: Eric Callahan --- docs/configuration.md | 48 ++++++++++++++++++++++++++------- docs/web_api.md | 63 +++++++++++++++++++++++++++++++++++++++---- 2 files changed, 96 insertions(+), 15 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 4084847..023a9e7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -394,10 +394,22 @@ enable_auto_refresh: False # When set to False Moonraker will only fetch update state on startup # and clients will need to request that Moonraker updates state. The # default is False. -distro: debian -# The disto in which moonraker has been installed. Currently the -# update manager only supports "debian", which encompasses all of -# its derivatives. The default is debain. +enable_system_updates: True +# A boolean value that can be used to toggle system package updates. +# Currently Moonraker only supports updating packages via APT, so +# this option is useful for users that wish to experiment with linux +# distros that use other package management applications, or users +# that prefer to manage their packages directly. Note that if this +# is set to False users will be need to make sure that all system +# dependencies are up to date. The default is True. +channel: dev +# The update channel applied to Klipper and Moonraker. May be 'dev' +# which will fetch updates using git, or 'beta' which will fetch +# zipped beta releases. Note that this channel does not apply to +# client updates, a client's update channel is determined by its +# 'type' option. When this option is changed the next "update" will +# swap channels, any untracked files in the application's path will be +# removed during this process. The default is dev. ``` ### Client Configuration @@ -412,8 +424,9 @@ service restart such as Fluidd/Mainsail. ```ini # moonraker.conf -[update_manager client client_name] +[update_manager client_name] type: web +# Indicates that this is a web client. repo: # This is the GitHub repo of the client, in the format of user/client. # For example, this could be set to cadriel/fluidd to update Fluidd or @@ -426,22 +439,29 @@ persistent_files: # themes. The default is no persistent files. ``` -This second example is for git repositories that have a service that need -updating. Note that git repos must have at least one tag for Moonraker +This second example is for "applications". These may be git repositories +or zipped distributions. + +Note that git repos must have at least one tag for Moonraker to identify its version. ```ini # moonraker.conf # service_name must be the name of the systemd service -[update_manager client service_name] +[update_manager service_name] type: git_repo +# Can be git_repo, zip, or zip_beta. See your the client's documentation +# for recommendations on which value to use. Generally a git_repo is +# an applications "dev" channel, zip_beta is its "beta" channel, and zip +# is its "stable" channel. This parameter must be provided. path: -# The absolute path to the client's files on disk. This parameter must be provided. +# The absolute path to the client's files on disk. This parameter must be +# provided. # Example: # path: ~/service_name origin: -# The full GitHub URL of the "origin" remote for the repository. This can +# The full git URL of the "origin" remote for the repository. This can # be be viewed by navigating to your repository and running: # git remote -v # This parameter must be provided. @@ -468,6 +488,14 @@ enable_node_updates: # to package-lock.json. Note that if your project does not have a # package-lock.json in its root directory then the plugin will fail to load. # Default is False. +host_repo: +# The GitHub repo in which zipped releases are hosted. Note that this does +# not need to match the repository in the "origin" option, as it is possible +# to use a central GitHub repository to host multiple client builds. As +# an example, Moonraker's repo hosts builds for both Moonraker and Klipper. +# This option defaults to the repo extracted from the "origin" option, +# however if the origin is not hosted on GitHub then this parameter must +# be provided. ``` ## `[mqtt]` diff --git a/docs/web_api.md b/docs/web_api.md index 972444a..904ca2e 100644 --- a/docs/web_api.md +++ b/docs/web_api.md @@ -2057,6 +2057,10 @@ and `fluidd` are present as clients configured in `moonraker.conf` ] }, "moonraker": { + "type": "zip_beta", + "channel": "beta", + "need_channel_update": false, + "pristine": true, "remote_alias": "origin", "branch": "master", "owner": "Arksine", @@ -2084,6 +2088,10 @@ and `fluidd` are present as clients configured in `moonraker.conf` "remote_version": "v1.10.0" }, "klipper": { + "type": "zip_beta", + "channel": "beta", + "need_channel_update": false, + "pristine": true, "remote_alias": "origin", "branch": "master", "owner": "KevinOConnor", @@ -2133,9 +2141,23 @@ Below is an explanation for each field: reported as seconds since the epoch (aka Unix Time). The `moonraker`, `klipper` packages, along with and clients configured -as git repos have the following fields: +as applications have the following fields: -- `owner`: the owner of the repo +- `configured_type`: the application type configured by the user +- `detected_type`: the applicaiton type as detected by Moonraker. +- `channel`: the currently configured update channel. For Moonraker + and Klipper this is set in the `[update_manager]` configuration. + For clients the channel is determined by the configured type +- `need_channel_update`: This will be set to `true` if Moonraker has + detected that a channel swap is necessary (ie: the configured type does + not match the detected type). The channel swap will be performed on the + next update. +- `pristine`: For `zip` and `zip_beta` types this is set to `true` if an + applications source checksum matches the one generated when the app was + built. This value will be set to the opposite of "dirty" for git repos. + Note that a zip application can still be updated if the repo is not + pristine. +- `owner`: the owner of the repo / application - `branch`: the name of the current git branch. This should typically be "master". - `remote_alias`: the alias for the remote. This should typically be @@ -2146,9 +2168,14 @@ as git repos have the following fields: - `current_hash`: hash of the most recent commit on disk - `remote_hash`: hash of the most recent commit pushed to the remote - `is_valid`: true if installation is a valid git repo on the master branch - and an "origin" set to the official remote -- `is_dirty`: true if the repo has been modified -- `detached`: true if the repo is currently in a detached state + and an "origin" set to the official remote. For `zip` and `zip_beta` + types this will report false if Moonraker is unable to fetch the + current repo state from GitHub. +- `is_dirty`: true if the repo has been modified. This will always be false + for `zip` and `zip_beta` types. +- `detached`: true if the repo is currently in a detached state. For `zip` + and `zip_beta` types it is considered detached if the local release info + does not match what is present on the remote. - `debug_enabled`: True when `enable_repo_debug` has been configured. This will bypass repo validation allowing detached updates, and updates from a remote/branch other than than the primary (typically origin/master). @@ -2175,6 +2202,32 @@ The `system` package has the following fields: - `package_list`: an array containing the names of packages available for update +### Perform a full update +Attempts to update all configured items in Moonraker. Updates are +performed in the following order: + +- `system` if enabled +- All configured clients +- Klipper +- Moonraker + +HTTP request: +```http +POST /machine/update/full +``` +JSON-RPC request: +```json +{ + "jsonrpc": "2.0", + "method": "machine.update.full", + "id": 4645 +} +``` +Returns: + +`ok` when complete + + #### Update Moonraker Pulls the most recent version of Moonraker from GitHub and restarts the service. If an update is requested while a print is in progress then