docs: update documentation reflected new folder structure

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>

docs/configuration.md

@@ -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
+!!! Note:
-    Moonraker currently supports two paths with read/write access, the
+    Previously the `[file_manager]` section contained `config_path` and
-    `config_path` configured in the `file_manager` and the `virtual_sdcard` path
+    `log_path` options. These options are now deprecated, as both locations
-    configured through Klipper in `printer.cfg`. These paths are monitored for
+    are determined by the `data path` configured on the command line.
-    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.
 
 !!! 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.
+!!! Note:
-If omitted defaults will be used.
+    This section no long has configuration options.  Previously the
-
+    `database_path` option was used to determine the locatation of
-```ini
+    the database folder, it is now determined by the `data path`
-moonraker.conf
+    configured on the command line.
-
-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.
 
 ### `[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
+!!! Note:
-# moonraker.conf
+    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]
+Example ini secrets file:
-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:
 
 ```ini
 # moonraker_secrets.ini
@@ -1834,7 +1804,7 @@ token: long_token_string
 
 ```
 
-Example json file:
+Example json secrets file:
 
 ```json
 {

docs/installation.md

@@ -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
+You may also want to take this opportunity to configure `printer.cfg` and
-printer.cfg to match Moonraker's `config_path` option (see the
+`klippy.log` so they are located in Moonraker's `data_path`, for example:
-[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:
 ```
 # 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 ~/moonraker_data
-mkdir printer_config
+mkdir ~/moonraker_data/logs
-mv printer.cfg printer_config
+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
+The install script will attempt to create a basic configuration if
-using the `config_path`, create it in the specified directory otherwise create
+`moonraker.conf` does not exist at the expected location, however if you
-it in the HOME directory.  The [sample moonraker.conf](./moonraker.conf) in
+prefer to have Moonraker start with a robust configuration you may create
-the `docs` directory may be used as a starting point.
+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`:
+- `-a <alias>`:
-  Specifies the path to Moonraker's config file. The default location
+  The alias used for this instance of Moonraker.  Moonraker uses this option
-  is `/home/<user>/moonraker.conf`.  When using this option to modify
+  when determining the file names for the configuration file, log file,
-  an existing installation it is necessary to add `-f` as well.
+  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`
+- `data path`: `$HOME/moonraker_data`
-- log file path - `/tmp/moonraker.log`
+- `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
+In general it is not recommended to install Moonraker with file logging
-`/etc/systemd/system/moonraker.service`.  The `install-moonraker.sh` script
+disabled.  While moonraker will still log to stdout, all requests for support
-may also be used to modify the config file location.
+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.

docs/moonraker.conf

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