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

docs: update documentation reflected new folder structure 

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>
This commit is contained in:
Eric Callahan 2022-08-21 14:19:56 -04:00 committed by Eric Callahan
parent 577f55306e
commit dd7e480cdd
3 changed files with 277 additions and 121 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
docs/configuration.md
View File

@ -51,12 +51,6 @@ ssl_port: 7130
# The port to listen on for SSL (HTTPS) connections. Note that the HTTPS
# server will only be started of the certificate and key options outlined
# below are provided. The default is 7130.
ssl_certificate_path:
# The path to a self signed ssl certificate. The default is no path, which
# disables HTTPS.
ssl_key_path:
# The path to the private key used to signed the certificate. The default
# is no path, which disables HTTPS.
klippy_uds_address: /tmp/klippy_uds
# The address of Unix Domain Socket used to communicate with Klippy. Default
# is /tmp/klippy_uds
@ -67,6 +61,15 @@ enable_debug_logging: False
# of development the default is False.
```
!!! Note:
Previously the `[server]` section contained `ssl_certificate_path` and
`ssl_key_path` options. These options are now deprecated, as both locations
are determined by the `data path` and `alias` configured on the command
line, ie `<data_file_path>/certs/<alias>.cert`. By default the certificate
path resolves to `$HOME/moonraker_data/certs/moonraker.cert` and the key
path resolves to `$HOME/moonraker_data/certs/moonraker.key`. Both files
may be symbolic links.
### `[file_manager]`
The `file_manager` section provides configuration for Moonraker's file
@ -74,18 +77,6 @@ management functionality. If omitted defaults will be used.
```ini
# moonraker.conf
config_path:
# The path to a directory where configuration files are located. This
# directory may contain Klipper config files (printer.cfg) or Moonraker
# config files (moonraker.conf). Clients may also write their own config
# files to this directory. Note that this may not be the system root
# (ie: "/") and moonraker must have read and write access permissions
# for this directory.
log_path:
# An optional path to a directory where log files are located. Users may
# configure various applications to store logs here and Moonraker will serve
# them at "/server/files/logs/*". The default is no log paths.
queue_gcode_uploads: False
# When set to True the file manager will add uploads to the job_queue when
# the `start_print` flag has been set. The default if False.
@ -96,17 +87,17 @@ enable_object_processing: False
# "cancel object" functionality. Note that this process is file I/O intensive,
# it is not recommended for usage on low resource SBCs such as a Pi Zero.
# The default is False.
enable_inotify_warnings: True
# When set to True Moonraker will generate warnings when inotify attempts
# to add a duplicate watch or when inotify encounters an error. On some
# file systems inotify may not work as expected, this gives users the
# option to suppress warnings when necessary. The default is True.
```
!!! Warning
Moonraker currently supports two paths with read/write access, the
`config_path` configured in the `file_manager` and the `virtual_sdcard` path
configured through Klipper in `printer.cfg`. These paths are monitored for
changes, thus they must not overlap. Likewise, these paths may not be a
parent or child of folders containing sensitive files such as the `database`,
Moonraker's source, or Klipper's source. If either of the above conditions
are present Moonraker will generate a warning and revoke access to the
offending path.
!!! Note:
Previously the `[file_manager]` section contained `config_path` and
`log_path` options. These options are now deprecated, as both locations
are determined by the `data path` configured on the command line.
!!! Tip
It is also possible to enable object processing directly in the slicer.
@ -169,24 +160,11 @@ gcode:
### `[database]`
The `database` section provides configuration for Moonraker's lmdb database.
If omitted defaults will be used.
```ini
moonraker.conf
database_path: ~/.moonraker_database
# The path to the folder that stores Moonraker's lmdb database files.
# It is NOT recommended to place this file in a location that is served by
# Moonraker (such as the "config_path" or the location where gcode
# files are stored). If the folder does not exist an attempt will be made
# to create it. The default is ~/.moonraker_database.
```
!!! Note
Previously the `enable_database_debug` option was available for internal
development to test changes to write protected namespaces. This option
been deprecated and disabled.
!!! Note:
This section no long has configuration options. Previously the
`database_path` option was used to determine the locatation of
the database folder, it is now determined by the `data path`
configured on the command line.
### `[data_store]`
@ -1804,23 +1782,15 @@ separate from `moonraker.conf`. This allows users to safely distribute
their configuration and log files without revealing credentials and
other sensitive information.
```ini
# moonraker.conf
!!! Note:
This section no long has configuration options. Previously the
`secrets_path` option was used to specify the location of the file.
The secrets file name and location is now determined by the `data path`
and `alias` command line options, ie: `<data_base_path>/<alias>.secrets`.
By default this resolves to `$HOME/moonraker_data/moonraker.secrets`.
This may be a symbolic link.
[secrets]
secrets_path:
# A valid path to the "secrets" file. A secrets file should either be
# in "ini" format (ie: the same format as moonraker.conf) or "json"
# format. If the file is a "json" file, the top level item must be
# an Object. When this parameter is not specified no file will be
# loaded.
```
!!! Warning
For maximum security the secrets file should be located in a folder
not served by Moonraker.
Example ini file:
Example ini secrets file:
```ini
# moonraker_secrets.ini
@ -1834,7 +1804,7 @@ token: long_token_string
```
Example json file:
Example json secrets file:
```json
{

301
docs/installation.md
View File

@ -31,7 +31,7 @@ missing one or both, you can simply add the bare sections to `printer.cfg`:
[display_status]
[virtual_sdcard]
path: ~/gcode_files
path: ~/moonraker_data/gcodes
```
### Enabling the Unix Socket
@ -69,12 +69,9 @@ KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer.cfg -l /tmp/klip
the default LSB script. In this case, you need to modify the
klipper.service file.
You may also want to take this opportunity to change the location of
printer.cfg to match Moonraker's `config_path` option (see the
[configuration document](configuration.md#primary-configuration)
for more information on the config_path). For example, if the `config_path`
is set to `~/printer_config`, your klipper defaults file might look
like the following:
You may also want to take this opportunity to configure `printer.cfg` and
`klippy.log` so they are located in Moonraker's `data_path`, for example:
```
# Configuration for /etc/init.d/klipper
@ -82,14 +79,17 @@ KLIPPY_USER=pi
KLIPPY_EXEC=/home/pi/klippy-env/bin/python
KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/printer_config/printer.cfg -l /tmp/klippy.log -a /tmp/klippy_uds"
KLIPPY_ARGS="/home/pi/klipper/klippy/klippy.py /home/pi/moonraker_data/config/printer.cfg -l /home/pi/moonraker_data/logs/klippy.log -a /tmp/klippy_uds"
```
If necessary, create the config directory and move printer.cfg to it:
Moonraker's install script will create the data folder, however you
may wish to create it now and move `printer.cfg` to the correct
location, ie:
```
cd ~
mkdir printer_config
mv printer.cfg printer_config
mkdir ~/moonraker_data
mkdir ~/moonraker_data/logs
mkdir ~/moonraker_data/config
mv printer.cfg ~/moonraker_data/config
```
### Installing Moonraker
@ -101,10 +101,15 @@ cd ~
git clone https://github.com/Arksine/moonraker.git
```
Now is a good time to create [moonraker.conf](configuration.md). If you are
using the `config_path`, create it in the specified directory otherwise create
it in the HOME directory. The [sample moonraker.conf](./moonraker.conf) in
the `docs` directory may be used as a starting point.
The install script will attempt to create a basic configuration if
`moonraker.conf` does not exist at the expected location, however if you
prefer to have Moonraker start with a robust configuration you may create
it now. By default the configuration file should be located at
`$HOME/moonraker_data/config/moonraker.conf`, however the location of the
data path may be configured using the script's command line options.
The [sample moonraker.conf](./moonraker.conf) may be used as a starting
point, full details can be found in the
[confguration documentation](./configuration.md).
For a default installation run the following commands:
```
@ -112,29 +117,38 @@ cd ~/moonraker/scripts
./install-moonraker.sh
```
Or to install with `moonraker.conf` in the `config_path`:
```
cd ~/moonraker/scripts
./install-moonraker.sh -f -c /home/pi/printer_config/moonraker.conf
```
The install script has a few command line options that may be useful,
particularly for those upgrading:
- `-r`:
Rebuilds the virtual environment for existing installations.
Sometimes this is necessary when a dependency has been added.
- `-f`:
Force an overwrite of Moonraker's systemd script. By default the
the systemd script will not be modified if it exists.
- `-c /home/pi/moonraker.conf`:
Specifies the path to Moonraker's config file. The default location
is `/home/<user>/moonraker.conf`. When using this option to modify
an existing installation it is necessary to add `-f` as well.
- `-a <alias>`:
The alias used for this instance of Moonraker. Moonraker uses this option
when determining the file names for the configuration file, log file,
secrets file, etc. This option is also used to name Moonraker's systemd
service unit and enviroment file. If omitted this defaults to `moonraker`.
- `-d <path to data folder>`:
Specifies the path to Moonraker's data folder. This folder organizes
files and directories used by moonraker. See the `Data Folder Structure`
section for details. If omitted this defaults to `$HOME/<alias>_data`,
ie: `/home/pi/moonraker_data`.
- `-c <path to configuration file>`
Specifies the path to Moonraker's configuation file. By default the
configuration is expected at `<data_folder>/config/<alias>.conf`. ie:
`/home/pi/moonraker_data/config/moonraker.conf`.
- `-l <path to log file>`
Specifies the path to Moonraker's log file. By default Moonraker logs
to `<data_folder>/logs/<alias>.log`. ie:
`/home/pi/moonraker_data/logs/moonraker.log`.
- `-z`:
Disables `systemctl` commands during install (ie: daemon-reload, restart).
This is useful for installations that occur outside of a standard environment
where systemd is not running.
- `-x`:
Skips installation of [polkit rules](#policykit-permissions). This may be
necessary to install Moonraker on systems that do not have policykit
installed.
Additionally, installation may be customized with the following environment
variables:
@ -143,11 +157,13 @@ variables:
- `MOONRAKER_REBUILD_ENV`
- `MOONRAKER_FORCE_DEFAULTS`
- `MOONRAKER_DISABLE_SYSTEMCTL`
- `MOONRAKER_SKIP_POLKIT`
- `MOONRAKER_CONFIG_PATH`
- `MOONRAKER_LOG_PATH`
- `MOONAKER_LOG_PATH`
- `MOONRAKER_DATA_PATH`
When the script completes it should start both Moonraker and Klipper. In
`/tmp/klippy.log` you should find the following entry:
`klippy.log` you should find the following entry:
`webhooks client <uid>: Client info {'program': 'Moonraker', 'version': '<version>'}`
@ -162,18 +178,197 @@ Now you may install a client, such as
debian/ubuntu distros).
### Data Folder Structure
As mentioned previously, files and folders used by Moonraker are organized
in a primary data folder. The example below illustrates the folder
structure using the default data path of `$HOME/moonraker_data` and the
default alias of `moonraker`:
```
/home/pi/moonraker_data
├── backup
│   └── 20220822T202419Z
│   ├── config
│   │   └── moonraker.conf
│   └── service
│   └── moonraker.service
├── certs
│   ├── moonraker.cert (optional)
│   └── moonraker.key (optional)
├── config
│   ├── moonraker.conf
│   └── printer.cfg
├── database
│   ├── data.mdb
│   └── lock.mdb
├── gcodes
│   ├── test_gcode_one.gcode
│   └── test_gcode_two.gcode
├── logs
│   ├── klippy.log
│   └── moonraker.log
└── moonraker.secrets (optional)
```
The next example illustrates how the `<data file path>` and `<alias>`
command line options are used to populate the folder:
```
<data file path>
├── backup
│   └── <ISO8601_DATE>
│   ├── config
│   │   └── <full configuration backup>
│   └── service
│   └── <systemd service backup>
├── certs
│   ├── <alias>.cert (optional)
│   └── <alias>.key (optional)
├── config
│   ├── <alias>.conf
│   └── printer.cfg
├── database
│   ├── data.mdb
│   └── lock.mdb
├── gcodes
│   ├── test_gcode_one.gcode
│   └── test_gcode_two.gcode
├── logs
│   ├── klippy.log
│   └── <alias>.log
└── <alias>.secrets (optional)
```
If it is not desirible for the files and folders to exist in these specific
locations it is acceptable to use symbolic links. For example, it is common
for the gcode folder to be located at `$HOME/gcode_files`. Rather than
reconfigure Klipper's `virtual_sdcard` it may be desirable to create a
`gcodes` symbolic link in the data path pointing to this location.
!!! Note
It is still possible to directly configure the paths to the configuration
and log files if you do not wish to use the default `<alias>` naming
scheme or if you wish for them to exist outside of the data folder.
When Moonraker attempts to update legacy installations symbolic links
are used to avoid an unrecoverable error. Additionally a `backup`
folder is created which contains the prior configuration and/or
systemd service unit, ie:
```
/home/pi/moonraker_data
├── backup
│   └── 20220822T202419Z
│   ├── config
│   │   ├── include
│   │   │   ├── extras.conf
│   │   │   ├── power.conf
│   │   │   └── updates.conf
│   │   └── moonraker.conf
│   └── service
│   └── moonraker.service
├── certs
│   ├── moonraker.cert -> /home/pi/certs/certificate.pem
│   └── moonraker.key -> /home/pi/certs/key.pem
├── config -> /home/pi/klipper_config
├── database -> /home/pi/.moonraker_database
├── gcodes -> /home/pi/gcode_files
├── logs -> /home/pi/logs
└── moonraker.secrets -> /home/pi/moonraker_secrets.ini
```
!!! Warning
The gcode and config paths should not contain symbolic links
that result in an "overlap" of on another. Moonraker uses
inotify to watch files in each of these folders and takes action
when a file change is detected. The action taken depends on the
"root" folder, thus it is important that they be distinct.
### The systemd service file
The default installation will create `/etc/systemd/system/moonraker.service`.
Below is a common example of service file, installed on a Raspberry Pi:
```ini
# systemd service file for moonraker
[Unit]
Description=API Server for Klipper SV1
Requires=network-online.target
After=network-online.target
[Install]
WantedBy=multi-user.target
[Service]
Type=simple
User=pi
SupplementaryGroups=moonraker-admin
RemainAfterExit=yes
WorkingDirectory=/home/pi/moonraker
EnvironmentFile=/home/pi/moonraker/moonraker.env
ExecStart=/home/pi/moonraker-env/bin/python $MOONRAKER_ARGS
Restart=always
RestartSec=10
```
Following are some items to take note of:
- The `Description` contains a string that Moonraker uses to validate
the version of the service file, (notice `SV1` at the end, ie: Service
Version 1).
- The `moonraker-admin` supplementary group is used to grant policykit
permissions.
- The `EnvironmentFile` field contains Moonraker's arguments. More on this
below.
- The `ExecStart` field begins with the python executable, followed by
by the enviroment variable `MOONRAKER_ARGS`. This variable is set in
the environment file.
#### The Enivirorment File
The environment file is created in Moonraker's source directory during
installation. By default the enviroment file is named `moonraker.env`.
A default installation's enviroment file will contain the path
to `moonraker.py` and the alias option, ie:
```
MOONRAKER_ARGS="/home/pi/moonraker/moonraker/moonraker.py -a moonraker"
```
A legacy installation converted to the updated flexible service unit
might contain the following:
```
MOONRAKER_ARGS="/home/pi/moonraker/moonraker/moonraker.py -a moonraker -d /home/pi/moonraker_data -c /home/pi/klipper_config/moonraker.conf -l /home/pi/klipper_logs/moonraker.log"
```
Post installation it is simple to customize the [arguments](#command-line-usage)
supplied to Moonraker by editing this file and restarting the service.
!!! Note
The service unit and enviroment file are named based on the `alias`
option supplied to the install script, which is `moonraker` by default.
Supplying `-a moonraker_1` to the install script will result in a
service file named `moonraker_1.service` and an environment file
named `moonraker_1.env`.
### Command line usage
This section is intended for users that need to write their own
installation script. Detailed are the command line arguments
available to Moonraker:
```
usage: moonraker.py [-h] [-c <configfile>] [-l <logfile>] [-n]
usage: moonraker.py [-h] [-a <alias>] [-d <data path>] [-c <configfile>] [-l <logfile>] [-n]
Moonraker - Klipper API Server
optional arguments:
options:
-h, --help show this help message and exit
-a <alias>, --alias <alias>
Alternate name of instance
-d <data path>, --datapath <data path>
Location of Moonraker Data File Path
-c <configfile>, --configfile <configfile>
Location of moonraker configuration file
-l <logfile>, --logfile <logfile>
@ -182,22 +377,28 @@ optional arguments:
```
The default configuration is:
- config file path- `~/moonraker.conf`
- log file path - `/tmp/moonraker.log`
- `data path`: `$HOME/moonraker_data`
- `alias`: `moonraker`
- `config file`: `$HOME/moonraker_data/config/moonraker.conf`
- `log file`: `$HOME/moonraker_data/logs/moonraker.log`
- logging to a file is enabled
If one needs to start moonraker without generating a log file, the
!!! Tip
While the `alias` option may be omitted it is recommended that it
always be included for new installations. This allows Moonraker
to differentiate between new and legacy installations.
If is necessary to run Moonraker without logging to a file the
`-n` option may be used, for example:
```
~/moonraker-env/bin/python ~/moonraker/moonraker/moonraker.py -n -c /path/to/moonraker.conf
~/moonraker-env/bin/python ~/moonraker/moonraker/moonraker.py -n
```
In general it is not recommended to install moonraker with this option.
While moonraker will still log to stdout, all requests for support must
be accompanied by moonraker.log.
These options may be changed by editing
`/etc/systemd/system/moonraker.service`. The `install-moonraker.sh` script
may also be used to modify the config file location.
In general it is not recommended to install Moonraker with file logging
disabled. While moonraker will still log to stdout, all requests for support
must be accompanied by moonraker.log.
These options may be changed by editing `moonraker.env`.
### PolicyKit Permissions
@ -326,17 +527,3 @@ rm -rf klipper
git clone https://github.com/Klipper3d/klipper.git
sudo systemctl restart klipper
```
### Additional Notes
- Make sure that Moonraker and Klipper both have read and write access to the
directory set in the `path` option for the `[virtual_sdcard]` in
`printer.cfg`.
- Upon first starting Moonraker is not aware of the gcode file path, thus
it cannot serve gcode files, add directories, etc. After Klippy enters
the "ready" state it sends Moonraker the gcode file path.
Once Moonraker receives the path it will retain it regardless of Klippy's
state, and update it if the path is changed in printer.cfg.
Please see [configuration.md](configuration.md) for details on how to
configure moonraker.conf.

3
docs/moonraker.conf
View File

@ -6,8 +6,7 @@
[server]
# Bind server defaults of 0.0.0.0, port 7125
enable_debug_logging: True
config_path: ~/printer_config
enable_debug_logging: False
[authorization]
enabled: True