Improved docs; minor bugs

bin/build-service.sh

@@ -1,6 +1,12 @@
 #!/bin/bash
 un="$2"
-port="$3"
+
+# Startup options (prepended to launch command), i.e., "export MAKERVERSE_PORT=80"
+cmd_opts=""
+if [[ ! -z "$3" ]]; then
+  cmd_opts="$3 && "
+fi
+
 echo "Makerverse Server will be controlled by $un"
 
 sv="makerverse.service"
@@ -40,10 +46,7 @@ if [ "$1" = "install" ]; then
   echo "" >> $sf
 
   echo "[Service]" >> $sf
-  if [[ ! -z "$port" ]]; then
-    echo "Environment=MAKERVERSE_PORT=${port}"
-  fi
-  echo "ExecStart=runuser -l ${un} -c \"${lf}\"" >> $sf
+  echo "ExecStart=runuser -l ${un} -c \"${cmd_opts}${lf}\"" >> $sf
   echo "Restart=always" >> $sf
   echo "StandardOutput=syslog" >> $sf
   echo "StandardError=syslog" >> $sf

ci/raspbian-desktop.json

@@ -86,7 +86,7 @@
         "sudo usermod -aG docker pi",
         "sudo systemctl enable docker",
         "sudo systemctl start docker",
-        "cd /home/pi/makerverse && bash bin/build-service.sh install pi"
+        "cd /home/pi/makerverse && bash bin/build-service.sh install pi 80"
       ]
     }
   ]

ci/raspbian-lite.json

@@ -79,7 +79,7 @@
         "sudo usermod -aG docker pi",
         "sudo systemctl enable docker",
         "sudo systemctl start docker",
-        "cd /home/pi/makerverse && bash bin/build-service.sh install pi"
+        "cd /home/pi/makerverse && bash bin/build-service.sh install pi \"export MAKERVERSE_PORT=80\""
       ]
     }
   ]

docs/about/contribution.md

@@ -11,9 +11,11 @@ Pull requests welcome!
 
 See [issues](/about/#issues) for reporting bugs or problems.
 
-## Documentation
+## Updating the Documentation
 
-These docs are located within the same Github repository that is home to Makerverse. You'll find them in the `docs/` folder, stored as `.md` (markdown) files. Therefore, the contribution process is the same as changing the Makerverse code...
+These docs are located within the same Github repository that is home to Makerverse. You'll find them in the `docs/` folder, stored as `.md` (markdown) files. Therefore, the contribution process is the same as changing the Makerverse code (_see below_). Once a pull request containing docs has been approved and merged, it will appear automatically on Makerverse.com.
+
+_**Note**: to test your changes to the docs, run `bundle exec jekyll serve` from the `docs/` folder. You will need to have Ruby & Jekyll installed ([see their docs](https://jekyllrb.com/docs/installation/))._
 
 ## How to Contribute
 

docs/features/advanced.md

@@ -2,11 +2,15 @@
 layout: default
 title: Advanced
 parent: Features
-nav_order: 10
+nav_order: 9
 ---
 
 # Advanced
 
 ## Turn Off Login (Guest Mode)
 
-To enable guest mode, edit the `~/.makerverse` to include the top-level `insecureDangerousGuestAccess` boolean key.
+ In [extreme cases](/features/security/#security-hazards) this may result in a **risk to your physical safety**!!
+
+_Edit the `~/.makerverse` to include the top-level `insecureDangerousGuestAccess` boolean key._
+
+In keeping with Makerverse's "easier to be secure" philosophy, guests are required to bypass the login screen at regular intervals (whereas logged-in users stay logged in).

docs/features/index.md

@@ -2,7 +2,7 @@
 layout: default
 title: Features
 permalink: /features/
-nav_order: 3
+nav_order: 4
 has_children: true
 ---
 

docs/features/security.md

@@ -2,7 +2,7 @@
 layout: default
 title: Security
 parent: Features
-nav_order: 9
+nav_order: 8
 ---
 
 # Security
@@ -21,8 +21,20 @@ When you first install Makerverse and log in to your account, an internet connec
 
 If at any point you become locked out of your account, you can reset your password using the email address you used to create the account.
 
-## Detailed Explanation
+## Potential Safety Hazards
 
-There's a good blog post by the folks at Octoprint about [why accounts are needed for security purposes](https://octoprint.org/blog/2018/09/03/safe-remote-access/). The blog post notes that [security researchers have found](https://isc.sans.edu/forums/diary/3D+Printers+in+The+Wild+What+Can+Go+Wrong/24044/) _thousands of exposed (hackable) OctoPrint installations_. The blog post doesn't discuss public (or poorly-secured) networks, but there are doubtlessly **many times more** installations vulnerable to hacking along this attack vector.
+Though it may sound extreme, accounts are meant to protect against potential safety hazards.
 
-To prevent this from ever becoming a problem with Makerverse, we made the decision to require secure login from the very beginning. Using a centralized authority (OpenWorkShop) allows authentication to happen via HTTPS (encrypted channels). Unlike with a "local-login," _your password is never transmitted via HTTP_. Moreover, OpenWorkShop uses modern security best-practices (OAuth, as opposed to a simple username/password) and open-source security libraries (`oidc-client`). This means that even someone who has hacked your WiFi network will be unable to see your login credentials.
+Makerverse can run large-scale heavy CNC machinery, laser cutters, plasma torches, and more. Many users enable full remote control over these tools, including the ability to turn them on and off via a web browser. It would be entirely possible for an uninformed guest to cause accidental human harm with such tools. Thus, accounts ensure that even well-intentioned guests cannot use the system.
+
+## Technical Explanation
+
+There's a good blog post by the folks at Octoprint about [why accounts are needed for security purposes](https://octoprint.org/blog/2018/09/03/safe-remote-access/). The blog post notes that [security researchers have found](https://isc.sans.edu/forums/diary/3D+Printers+in+The+Wild+What+Can+Go+Wrong/24044/) _thousands of totally exposed ("don't even need to hack them") OctoPrint installations_. The blog post doesn't discuss public (or poorly-secured) networks, but there are doubtlessly **many times more** installations vulnerable to hacking along this attack vector.
+
+_**Note**: despite the above security report, the folks behind OctoPrint are extremely diligent in this matter. We simply feel that a tool like Makerverse, which comes with the above hazards, should make it **easier** to be secure than insecure._
+
+## Philosophy
+
+To prevent this from ever becoming a problem with Makerverse, we made the decision to be "secure by default." Using a centralized authority (OpenWorkShop) allows authentication to happen via HTTPS (encrypted channels). Unlike with a "local-login," _your password is never transmitted via HTTP_. Moreover, OpenWorkShop uses modern security best-practices (OAuth, as opposed to a simple username/password) and open-source security libraries (`oidc-client`). This means that even someone who has hacked your WiFi network will be unable to see your login credentials.
+
+If you still want to enable guest mode, despite the potential hazards, see the "advanced" features.

docs/index.md

@@ -14,7 +14,6 @@ A full-featured web-based controller platform for CNC & 3DP machines.
 ## Quickstart
 
 - Follow the [installation](/installation/) guide.
+- [Connect to the application](/tutorial/open-makerverse/) and [create a workspace](/tutorial/create-workspace/).
 - Follow your [machine-specific](/machines/) instructions.
-- Launch the application and create a workspace (_coming soon_).
-- Calibrate and test your machine (_coming soon_).
-- Run your first print/cut (_coming soon_).
+- Upload and [run your first cut or print](/tutorial/run-programs/).

docs/installation/index.md

@@ -6,12 +6,22 @@ permalink: /installation/
 has_children: true
 ---
 
+# Installation
+
 You can always find the latest versions on the [Releases page](https://github.com/makermadecnc/makerverse/releases/).
 
+## Methods
+
 There are **two primary ways** to run Makerverse.
 
-- **Stand-Alone**: easy to install on Mac and Windows, but can only be used from that computer.
-- **Web Server**: works on any computer; can be accessed from any web browser.
+- **Stand-Alone**: easy to install on Mac and Windows; harder to update.
+- **Web Server**: works on any computer; has automatic updates.
+
+## Recommendations
+
+1. If you have a Raspberry Pi, just [flash the pre-built image](/installation/web-server/raspberry-pi/) for the easiest, most full-featured solution.
+2. If you're **non-technical** and **only** using Makerverse on a **Mac/Windows** computer, use the [stand-alone install](/installation/stand-alone/).
+3. Otherwise, use the [generic web server install](/installation/web-server/) (works with just about any computer).
 
 ## Prereleases (Beta Versions)
 

docs/installation/web-server/docker.md

@@ -75,6 +75,15 @@ docker run --rm --privileged --name makerverse \
   "makerverse/core:latest"
 ```
 
+## Configuration
+
+You can set the following environment variables to configure Makerverse on any Web Server:
+
+- `MAKERVERSE_PORT`: Which port to listen on (default: `8000`).
+- `MAKERVERSE_HOME`: Where the settings files should be stored (default: `$HOME`).
+- `MAKERVERSE_SRC_DIR`: Where the Makerverse code is located (default: `$HOME/makerverse`).
+- `MAKERVERSE_LAUNCH_METHOD`: Use Docker or Node? (default: `docker`).
+
 ## Updating
 
 Each time the `bin/launch` script is run, it will automatically update the application by pulling the latest docker image. If you use the [linux service](/installation/web-server/linux-service/#updating), this happens each time you restart the service.

docs/installation/web-server/index.md

@@ -14,21 +14,12 @@ _**Tip**: the easiest setup is the [Raspberry Pi Image](/installation/web-server
 
 If you don't wish to use the pre-built image, you can achieve the same thing on a Raspberry Pi (or any Debian computer) using the [Linux Service](/installation/web-server/linux-service/) installation. For all other cases, refer directly to the [Docker](/installation/web-server/docker/) instructions.
 
-## Configuration
-
-You can set the following environment variables to configure Makerverse on any Web Server:
-
-- `MAKERVERSE_PORT`: Which port to listen on (default: `8000`).
-- `MAKERVERSE_HOME`: Where the settings files should be stored (default: `$HOME`).
-- `MAKERVERSE_SRC_DIR`: Where the Makerverse code is located (default: `$HOME/makerverse`).
-- `MAKERVERSE_LAUNCH_METHOD`: Use Docker or Node? (default: `docker`).
-
 ## Updating
 
 The web server installation automatically updates when it restarts.
 
-To update a web-server install, just run the `bin/launch` script:
+To manually update a **Linux Service** install, use `sudo systemctl restart makerverse`.
+
+_**Note**: while the update is downloaded, Makerverse will continue to run the old installation. You can check on the update progress with `journalctl -xe`. Once the update is complete, refresh your internet browser and look at the "About" screen to confirm the new version._
 
-```
-$HOME/makerverse/bin/launch
-```
+To manually update a Docker install (without a Linux service), run `bin/launch` from within the Makerverse directory. This can also be useful if you would like more feedback on the update progress (this approach happens in the foreground, instead of requiring that you use the `journalctl` command to view logs).

docs/installation/web-server/linux-service.md

@@ -29,6 +29,17 @@ Type `sudo systemctl [command] makerverse`, replacing **[command]** with one of
 - `stop`: Stop the application.
 - `disable`: Do not start the application automatically.
 
+## Configuration
+
+If you would like to set one or more [configuration (environment) variables](/installation/web-server/docker/#configuration), you will need to pass them to the service. For example, to set the port to 80 (_which is done by default on the Raspberry Pi image_), **reinstall the service** as follows (from the Makerverse directory):
+
+```
+sudo bin/build-service.sh install $(whoami) "export MAKERVERSE_PORT=80"
+```
+
+- The second parameter is the username (e.g., `pi`) which will run the service.
+- The third parameter will be prepended to the start command, in this case exporting the environment variable.
+
 ## Troubleshooting
 
 The following commands are helpful if something is not working:

docs/installation/web-server/raspberry-pi.md

@@ -14,10 +14,18 @@ It does all the work of setting up the Docker environment (and Linux service) fo
 
 ## Requirements
 
-- Raspberry Pi 3B+ (or better)
-- 16 GB micro SD card (or bigger)
-- Power supply for the RPi
-- _Optional: keyboard, mouse, and monitor_
+- Raspberry Pi 3B+ (or better).
+- 16 GB micro SD card (or bigger).
+- Power supply for the RPi.
+
+At least **one of** the following:
+
+- An ethernet connection (plugged in to the RPi).
+- A keyboard, monitor, and mouse.
+
+_**Note**: you will be able to configure WiFi later in the setup. If neither of the above two options are available to you, you will need to [use a wpa_supplicant.conf](https://www.raspberrypi.org/documentation/configuration/wireless/headless.md) to pre-configure WiFi._
+
+Additionally, the first time Makerverse starts, you will need an active internet connection.
 
 ## Choose Release
 
@@ -28,38 +36,50 @@ There are two download options in the [Latest Release](https://github.com/makerm
 
 These are merely customized versions of [the official Raspberry Pi OS images of the same names](https://www.raspberrypi.org/downloads/raspberry-pi-os/) (Lite vs. Desktop). Once you have downloaded the appropriate release file, unzip it and flash the `.img` to your SD card with your preferred application (e.g., Balena Etcher).
 
-## First Boot
+Then, just plug the RPi in and power it up!
+
+## Connecting to the RPi
 
 You'll need to get to a terminal in order to setup the Pi. You can either:
 
 - Attach a mouse and keyboard.
-- Use SSH to connect from your computer: `ssh pi@makerverse.local` (SSH is enabled by default in the Pi image).
+- Use SSH to connect from your computer: `ssh pi@makerverse.local`.
 
-_**Note**: if the SSH command does not work, either the Pi is not connected to your home network via ethernet, or your router does not support looking up the Pi by its name. In either case, you should open your router's admin interface and try to find the Pi's IP address on the network. If you can find the IP address, you can use it instead of `makerverse.local`._
+_**Note**: SSH is enabled by default in the Pi image. If the SSH command cannot connect (does not show a login prompt), either the Pi is not connected to the same network as the computer from which you are attempting to access it, or your router does not support looking up the Pi by its name. In either case, you should open your router's admin interface and try to find the Pi's IP address on the network. If you can find the IP address, you can use it instead of `makerverse.local`._
 
 The username/password (`pi`/`raspberry`) have been left unchanged from a "normal" Raspberry Pi OS. Use this whenever prompted for a username and password.
 
+## First Boot
+
 Once you've got a terminal open, type `sudo raspi-config` to run the official Raspberry Pi configuration tool.
 
 - You should **definitely** change the password, to keep the device secure!
 - You might also change the hostname from `makerverse` to something more memorable, like `maslow`, so you can use `maslow.local` instead of `makerverse.local`.
 - You might also want to turn on WiFi, so you do not need to use an ethernet connection on the Raspberry Pi to have access to Makerverse.
 
-The Makerverse application will start automatically on port `8000`. However, especially during the first boot, it will take some time to download (_~600MB_) and unpack the application. On a Raspberry Pi 3 B+ Rev.1.3 (about the  worst device which can handle Makerverse), this has been known to take 20-30 minutes. A RPi4 on a decent internet connection should only take a few minutes.
-
 _**Tip**: read the [useful commands in the Linux Service section](/installation/web-server/linux-service/#useful-commands)!_
 
+_**Note**: GPIO pin communication is enabled by default in Makerverse (meaning that `pigpiod` is enabled). This allows you to [create commands](/features/commands/) that turn on and off the machine, for example._
+
+## Opening Makerverse
+
+You can connect to Makerverse from any web browser on the same network.
+
+_**Note**: the Raspberry Pi image, unlike other web server instals, will run the Makerverse server on port `80` instead of port `8000`. This means that you can connect without specifying a port in your browser (e.g., `http://makerverse.local` instead of `http://makerverse.local:8000`)._
+
+The Makerverse application will start automatically on port `80`. However, especially during the first boot, it will take some time to download (_~600MB_) and unpack the application. On a Raspberry Pi 3 B+ Rev.1.3 (about the  worst device which can handle Makerverse), this has been known to take 20-30 minutes. A RPi4 on a decent internet connection should only take a few minutes. To check on the status of the startup or update, see the [useful commands in the Linux Service section](/installation/web-server/linux-service/#useful-commands).
+
 ## Tablet UI
 
-The Raspberry Pi image comes pre-installed with a mobile/tablet UI. It can be accessed by adding `/tablet` to the URL, such as `http://makerverse.local:8000/tablet`.
+The Raspberry Pi image comes pre-installed with a mobile/tablet UI. It can be accessed by adding `/tablet` to the URL, such as `http://makerverse.local/tablet`.
 
 However, this UI is not the default UI because it is much less full-featured (it is intended for simple controls, like jogging or pausing program execution, from the shopfloor). You will still need to perform setup and calibration using the normal, desktop UI.
 
 ## Desktop
 
 When running the `makerverse-raspberrypi-os-dekstop.**` (desktop version), you will need to follow on-screen instructions after the first boot to configure your Raspberry Pi. This image is based upon a standard Raspberry Pi OS Desktop installation, so please refer to the official documentation for any help.
 
-You can open a web browser and navigate to Makerverse at `http://localhost:8000`. Or, you can enable Kiosk mode...
+You can open a web browser and navigate to Makerverse at `http://localhost`. Or, you can enable Kiosk mode...
 
 ### Kiosk Mode
 

docs/machines/cnc/index.md

@@ -8,21 +8,22 @@ has_children: true
 
 # CNC
 
-Find your machine, below, and click on the appropriate link for the latest firmware.
+Find your machine, below, and click on the appropriate link for the latest firmware and instructions.
+
+_If you click on one of the links and are taken to a Github page, use the green **Code** button at the top to download the latest version, (unless specified otherwise in the instructions)._
 
 ## Maslow
 
 _Please read the [Maslow-specific instructions](/machines/cnc/maslow)._
 
-- [Arduino Mega](https://github.com/WebControlCNC/Firmware/tree/release/holey): Maslow "Classic" (JumpStart Kit) (Baud Rate: 57600)
-- [Arduino Due](https://github.com/makermadecnc/MaslowDue): M2 (Baud Rate: 38400)
+There are two common types of Maslow, built with two different Arduino boards:
 
-#### Tested On
+- [Arduino Mega](https://github.com/WebControlCNC/Firmware/tree/release/holey): Maslow "Classic" (JumpStart Kit)
+- [Arduino Due](https://github.com/makermadecnc/MaslowDue): M2, or similar
+
+_**Tip**: Coming from GroundControl/WebControl with an original Maslow Mega? Read [this forum post](https://forums.maslowcnc.com/t/how-to-upgrade-to-holey-51-28-firmware-using-webcontrol-in-preparation-for-running-makerverse/14549) for help upgrading firmware._
 
-- MakerMade JumpStart Kit
-- MakerMade M2
-- MetalMaslow Kit
-- MetalMaslow Due + Shield
+_**Note**: the firmware for the Arduino Due underwent significant changes in September, 2020. If your firmware was installed before this point, it is actually a Grbl machine (below) and does not have support for the [Maslow-specific features](/machines/cnc/maslow), like correcting for chain-sag effects (rounding) that happen in the corners of the stock._
 
 ## Grbl