3diy
/
moonraker
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update install documentation 

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>
This commit is contained in:
Eric Callahan 2024-07-30 07:55:41 -04:00
parent c2409e813e
commit b40751ba9d
3 changed files with 87 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
docs/changelog.md
View File

@ -6,6 +6,22 @@ The format is based on [Keep a Changelog].
## [Unreleased] ## [Unreleased]
## [0.9.2] - 2024-07-30
### Added
- **install**: Add support for installing Moonraker's python package via pip.
- **scripts**: Add script to sync python and system dependencies from
`pyproject.toml` and `system-dependencies.json` respectively.
- **dev**: Add pre-commit hook to call `sync_dependencies.py`.
### Fixed
- **build**: Build from sdist now correctly includes share data.
- **build**: Remove stray `.gitignore` from Python Wheel.
### Changed
- **install**: The `MOONRAKER_FORCE_DEFAULTS` environment variable has changed
to `MOONRAKER_FORCE_SYSTEM_INSTALL`.
## [0.9.1] - 2024-07-25 ## [0.9.1] - 2024-07-25
### Fixed ### Fixed
@ -190,7 +206,8 @@ The format is based on [Keep a Changelog].
[api_changes.md]: api_changes.md [api_changes.md]: api_changes.md
<!-- Versions --> <!-- Versions -->
[unreleased]: https://github.com/Arksine/moonraker/compare/v0.9.1...HEAD [unreleased]: https://github.com/Arksine/moonraker/compare/v0.9.2...HEAD
[0.9.2]: https://github.com/Arksine/moonraker/compare/v0.9.1...v0.9.2
[0.9.1]: https://github.com/Arksine/moonraker/compare/v0.9.0...v0.9.1 [0.9.1]: https://github.com/Arksine/moonraker/compare/v0.9.0...v0.9.1
[0.9.0]: https://github.com/Arksine/moonraker/compare/v0.8.0...v0.9.0 [0.9.0]: https://github.com/Arksine/moonraker/compare/v0.8.0...v0.9.0
[0.8.0]: https://github.com/Arksine/moonraker/compare/v0.7.1...v0.8.0 [0.8.0]: https://github.com/Arksine/moonraker/compare/v0.7.1...v0.8.0

2
docs/configuration.md
View File

@ -2222,7 +2222,7 @@ folder that provides supplemental information for the application. The
Moonraker uses the [PDM backend](https://backend.pdm-project.org/) to perform Moonraker uses the [PDM backend](https://backend.pdm-project.org/) to perform
its package builds. An example of a pdm build script that generates a its package builds. An example of a pdm build script that generates a
`release_info` file may be found `release_info` file may be found
[here](https://github.com/Arksine/moonraker/blob/master/scripts/pdm_build_dist.py). [here](https://github.com/Arksine/moonraker/blob/master/pdm_build.py).
#### The System Dependencies File Format #### The System Dependencies File Format

99
docs/installation.md
View File

@ -1,19 +1,19 @@
## Installation ## Installation
This document provides a guide on how to install Moonraker on a Raspberry This document provides a guide on how to install Moonraker on a Debian
Pi running Raspian/Rasperry Pi OS. Other SBCs and/or linux distributions based Linux Distributions. Other linux distributions may work, however
may work, however they may need a custom install script. Moonraker they may need a custom install script. Moonraker requires Python 3.7 or
requires Python 3.7 or greater, verify that your distribution's greater, verify that your distribution's Python 3 packages meet this
Python 3 packages meet this requirement. requirement.
### Installing Klipper ### Installing Klipper
Klipper should be installed prior to installing Moonraker. Please see Klipper should be installed prior to installing Moonraker. Please see
[Klipper's Documention](https://klipper3d.com/Overview.html) for details. [Klipper's Documentation](https://klipper3d.com/Overview.html) for details.
After installing Klipper you should make sure to add Moonraker's After installing Klipper you should make sure to add Moonraker's
[configuration requirements](#klipper-configuration-requirements). [configuration requirements](#klipper-configuration-requirements).
### Klipper Configuration Requirements #### Klipper Configuration Requirements
Moonraker depends on the following Klippy extras for full functionality: Moonraker depends on the following Klippy extras for full functionality:
@ -34,7 +34,7 @@ missing one or both, you can simply add the bare sections to `printer.cfg`:
path: ~/printer_data/gcodes path: ~/printer_data/gcodes
``` ```
### Enabling Klipper's Unix Domain Socket Server #### Enabling Klipper's Unix Domain Socket Server
After Klipper is installed it may be necessary to modify its `defaults` file in After Klipper is installed it may be necessary to modify its `defaults` file in
order to enable the Unix Domain Socket. Begin by opening the file in your order to enable the Unix Domain Socket. Begin by opening the file in your
@ -53,7 +53,7 @@ KLIPPY_EXEC=/home/pi/klippy-env/bin/python
KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer.cfg -l /tmp/klippy.log" KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer.cfg -l /tmp/klippy.log"
``` ```
Add `-a /tmp/klippy_uds` to KLIPPY_ARGS: Add `-a /home/pi/printer_data/comms/klippy.sock` to KLIPPY_ARGS:
``` ```
# Configuration for /etc/init.d/klipper # Configuration for /etc/init.d/klipper
@ -61,7 +61,7 @@ KLIPPY_USER=pi
KLIPPY_EXEC=/home/pi/klippy-env/bin/python KLIPPY_EXEC=/home/pi/klippy-env/bin/python
KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer.cfg -l /tmp/klippy.log -a /tmp/klippy_uds" KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer.cfg -l /tmp/klippy.log -a /home/pi/printer_data/comms/klippy.sock
``` ```
!!! note !!! note
@ -79,7 +79,7 @@ KLIPPY_USER=pi
KLIPPY_EXEC=/home/pi/klippy-env/bin/python KLIPPY_EXEC=/home/pi/klippy-env/bin/python
KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer_data/config/printer.cfg -l /home/pi/printer_data/logs/klippy.log -a /tmp/klippy_uds" KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer_data/config/printer.cfg -l /home/pi/printer_data/logs/klippy.log -a /home/pi/printer_data/comms/klippy.sock"
``` ```
Moonraker's install script will create the data folder, however you Moonraker's install script will create the data folder, however you
@ -94,13 +94,52 @@ mv printer.cfg ~/printer_data/config
### Installing Moonraker ### Installing Moonraker
Begin by cloning the git respository: Moonraker provides an install script that can be used to facilitate
installation. The type of installation depends on where the install
script is located on the host file system. If the install script is
downloaded and run individually, the script will install Moonraker as
a Python Package using pip. If the script is run from Moonraker's
original source it will install Moonraker from source.
Prior to installation it is necessary to open a terminal on the host
machine, or SSH into it. It is recommended to read this entire
section before proceeding with the installation.
#### Installing the Moonraker Python package
The Python Package version of Moonraker will receive fewer updates, and
should generally be more stable. This is intended for users that do
not need to run unofficial 3rd party extensions, such as
[Moonraker-Timelapse](https://github.com/mainsail-crew/moonraker-timelapse),
and do not desire to run the "bleeding edge" version of Moonraker.
To perform this installation, download Moonraker's
[install script](https://raw.githubusercontent.com/Arksine/moonraker/master/scripts/install-moonraker.sh)
from Github, then run the installer:
```
cd ~
wget https://raw.githubusercontent.com/Arksine/moonraker/master/scripts/install-moonraker.sh
./install-moonraker.sh
```
#### Installing Moonraker from source
Moonraker can be run directly from source. This method of installation will
clone Moonraker's git repository, and may receive frequent bleeding edge
updates. Users who want to test Moonraker, run unofficial modifications, and
do not mind SSHing into the host to correct issues should choose this option.
To install Moonraker from source, clone its git repository then run the installer:
``` ```
cd ~ cd ~
git clone https://github.com/Arksine/moonraker.git git clone https://github.com/Arksine/moonraker.git
~/moonraker/scripts/install-moonraker.sh
``` ```
#### Customizing the installation
The install script will attempt to create a basic configuration if The install script will attempt to create a basic configuration if
`moonraker.conf` does not exist at the expected location, however if you `moonraker.conf` does not exist at the expected location, however if you
prefer to have Moonraker start with a robust configuration you may create prefer to have Moonraker start with a robust configuration you may create
@ -109,20 +148,17 @@ it now. By default the configuration file should be located at
data path may be configured using the script's command line options. data path may be configured using the script's command line options.
The [sample moonraker.conf](./moonraker.conf) may be used as a starting The [sample moonraker.conf](./moonraker.conf) may be used as a starting
point, full details can be found in the point, full details can be found in the
[confguration documentation](./configuration.md). [configuration documentation](./configuration.md).
For a default installation run the following commands:
```
cd ~/moonraker/scripts
./install-moonraker.sh
```
The install script has a few command line options that may be useful, The install script has several command line options that may be useful,
particularly for those upgrading: particularly for those upgrading:
- `-f`: - `-f`:
Force an overwrite of Moonraker's systemd script. By default the Force an overwrite of Moonraker's systemd script. In addition, a
the systemd script will not be modified if it exists. new `moonraker.env` file will be created, and the PolKit rules will
be re-installed. By default these items will not be modified if
they exist.
- `-a <alias>`: - `-a <alias>`:
The installer uses this option to determine the name of the service The installer uses this option to determine the name of the service
to install. If `-d` is not provided then this options will also be to install. If `-d` is not provided then this options will also be
@ -133,7 +169,7 @@ particularly for those upgrading:
files and directories used by moonraker. See the `Data Folder Structure` files and directories used by moonraker. See the `Data Folder Structure`
section for details. If omitted this defaults to `$HOME/printer_data`. section for details. If omitted this defaults to `$HOME/printer_data`.
- `-c <path to configuration file>` - `-c <path to configuration file>`
Specifies the path to Moonraker's configuation file. By default the Specifies the path to Moonraker's configuration file. By default the
configuration is expected at `<data_folder>/config/moonraker.conf`. ie: configuration is expected at `<data_folder>/config/moonraker.conf`. ie:
`/home/pi/printer_data/config/moonraker.conf`. `/home/pi/printer_data/config/moonraker.conf`.
- `-l <path to log file>` - `-l <path to log file>`
@ -157,25 +193,26 @@ variables:
- `MOONRAKER_VENV` - `MOONRAKER_VENV`
- `MOONRAKER_REBUILD_ENV` - `MOONRAKER_REBUILD_ENV`
- `MOONRAKER_FORCE_DEFAULTS` - `MOONRAKER_FORCE_SYSTEM_INSTALL`
- `MOONRAKER_DISABLE_SYSTEMCTL` - `MOONRAKER_DISABLE_SYSTEMCTL`
- `MOONRAKER_SKIP_POLKIT` - `MOONRAKER_SKIP_POLKIT`
- `MOONRAKER_CONFIG_PATH` - `MOONRAKER_CONFIG_PATH`
- `MOONAKER_LOG_PATH` - `MOONRAKER_LOG_PATH`
- `MOONRAKER_DATA_PATH` - `MOONRAKER_DATA_PATH`
- `MOONRAKER_SPEEDUPS` - `MOONRAKER_SPEEDUPS`
When the script completes it should start both Moonraker and Klipper. In When the script completes it should start the Moonraker system service. If Klipper
`klippy.log` you should find the following entry: is running and Moonraker is able to establish a connection the following log entry
should be available in `klippy.log`:
`webhooks client <uid>: Client info {'program': 'Moonraker', 'version': '<version>'}` `webhooks client <uid>: Client info {'program': 'Moonraker', 'version': '<version>'}`
Now you may install a client, such as Now you may wish to install a frontend, such as
[Mainsail](https://github.com/mainsail-crew/mainsail) or [Mainsail](https://github.com/mainsail-crew/mainsail) or
[Fluidd](https://github.com/fluidd-core/fluidd). [Fluidd](https://github.com/fluidd-core/fluidd).
!!! Note !!! Note
Moonraker's install script no longer includes the nginx dependency. Moonraker's installer does not include nginx as a dependency.
If you want to install one of the above clients on the local machine, If you want to install one of the above clients on the local machine,
you may want to first install nginx (`sudo apt install nginx` on you may want to first install nginx (`sudo apt install nginx` on
debian/ubuntu distros). debian/ubuntu distros).
@ -299,7 +336,7 @@ Following are some items to take note of:
- The `EnvironmentFile` field contains Moonraker's arguments. See the - The `EnvironmentFile` field contains Moonraker's arguments. See the
[environment file section](#the-environment-file) for details. [environment file section](#the-environment-file) for details.
- The `ExecStart` field begins with the python executable, followed by - The `ExecStart` field begins with the python executable, followed by
by the enviroment variable `MOONRAKER_ARGS`. This variable is set in by the environment variable `MOONRAKER_ARGS`. This variable is set in
the environment file. the environment file.
@ -362,7 +399,7 @@ If is necessary to run Moonraker without logging to a file the
While moonraker will still log to stdout, all requests for support While moonraker will still log to stdout, all requests for support
must be accompanied by `moonraker.log`. must be accompanied by `moonraker.log`.
Each command line argument has an associated enviroment variable that may Each command line argument has an associated environment variable that may
be used to specify options in place of the command line. be used to specify options in place of the command line.
- `MOONRAKER_DATA_PATH="<data path>"`: equivalent to `-d <data path>` - `MOONRAKER_DATA_PATH="<data path>"`: equivalent to `-d <data path>`
@ -460,7 +497,7 @@ with the `sudo` prefix. This has significant downsides:
wants to poll information about the system. wants to poll information about the system.
Moonraker now supports communicating with system services via D-Bus. Moonraker now supports communicating with system services via D-Bus.
Operations that require elevated privileges are authrorized through Operations that require elevated privileges are authorized through
PolicyKit. On startup Moonraker will check for the necessary privileges PolicyKit. On startup Moonraker will check for the necessary privileges
and warn users if they are not available. Warnings are presented in and warn users if they are not available. Warnings are presented in
`moonraker.log` and directly to the user through some clients. `moonraker.log` and directly to the user through some clients.