Merge branch 'master' into docs-updates

README.md

@@ -24,6 +24,8 @@ pip3 install sphinx-book-theme || pip install git+https://github.com/executableb
 
 Run: `sphinx-autobuild source build/html` to activate a live-reload environment on `localhost:8000`.
 
+To run in development mode when actively changing js/css files run: `sphinx-autobuild source build/html source/_static/js/main.js source/_static/default.css`. This will auto reload with changes to noted files.
+
 The main configuration file for this project is located at `./source/conf.py`.
 
 The navigation structure is aligned with the folder/file organization under `./source/`. This is where the individual page `.rst` files live and can be edited.
@@ -45,3 +47,12 @@ Click on the "Pull requests" tab in the top navbar. Select the green "New pull r
 ## Helpful Resources
 
 - [Lists in RST](https://sublime-and-sphinx-guide.readthedocs.io/en/latest/lists.html)
+
+## Updating theme
+
+To update Sphinx Book Theme:
+- `pip uninstall sphinx-book-theme` (needed to properly propagate new changes for some undetermined reason)
+- `pip install sphinx-book-theme==<tag_version>` || `pip install git+https://github.com/executablebooks/sphinx-book-theme.git@<branch_name>` eg. `pip install sphinx-book-theme==0.0.42`
+
+To deploy theme update:
+- Build and publish according to production release process

source/_static/default.css

@@ -1,6 +1,7 @@
-body, h1, h2, h3, h4, nav, .topbar, .topbar-main, .tocsection, .form-control, .bd-toc {
+body, p, h1, h2, h3, h4, nav, .topbar, .topbar-main, .tocsection, .form-control, .bd-toc, .bd-sidebar {
     background-color: #2b2b2b!important;
     color: #f8f8ff!important;
+    line-height: 1.65;
 }
 
 h1 {

source/_static/js/main.js

@@ -1,8 +1,7 @@
-$(document).ready(function () {
+$(document).ready(function (e) {
   // open external links in separate tab
   $('a[href^="http://"], a[href^="https://"]').not('a[class*=internal]').attr('target', '_blank');
-  $(".fa-arrow-left").attr("class", "fas fa-times");
-  $(".fa-arrow-up").attr("class", "fas fa-times");
+
   // toggle hidable sections
   $(".toggle > *").hide();
   $(".toggle .admonition-title").show();
@@ -10,12 +9,16 @@ $(document).ready(function () {
       $(this).parent().children().not(".admonition-title").toggle(400);
       $(this).parent().children(".admonition-title").toggleClass("open");
   })
-  // default menu to open on initial load
-  $('.site-navigation').removeClass('collapsing');
-  $('.site-navigation').removeClass('collapse');
-  $('.site-navigation').addClass('show');
-  // initially hide menu close button
+
+  // change appearance of arrow to X for menu closing
+  $(".fa-arrow-left").attr("class", "fas fa-times");
+  $(".fa-arrow-up").attr("class", "fas fa-times");
+
+  // initially hide menu close button on small screen widths
+  if ($(window).width() < 768) {
     $('.fa-times').addClass('hidden');
+  }
+
   $('#navbar-toggler').click(function() {
     // toggle menu open/close button depending on collapsed state
     if ($('#navbar-toggler').hasClass("collapsed")) {

source/misc-guides/available-services.rst

@@ -16,6 +16,7 @@ Bitcoin-related services
 * `Ride the Lightning (RTL) <https://github.com/Start9Labs/ride-the-lightning-wrapper/tree/master/docs>`_
 * `Spark Wallet <https://github.com/Start9Labs/spark-wallet-wrapper/tree/master/docs>`_
 * `BTCPayServer <https://github.com/Start9Labs/btcpayserver-wrapper>`_
+* `Sphinx Chat <https://sphinx.chat/>`_
 
 Other services
 ==============
@@ -25,3 +26,4 @@ Other services
 * `Cups <https://github.com/Start9Labs/cups-wrapper/tree/master/docs>`_
 * `File Browser <https://github.com/Start9Labs/filebrowser-wrapper/tree/master/docs>`_
 * `Mastodon <https://github.com/Start9Labs/mastodon-wrapper>`_
+* `Embassy Pages <https://github.com/Start9Labs/embassy-pages-wrapper>`_

source/misc-guides/tor-firefox/desktop.rst

@@ -17,17 +17,17 @@ Setting up Firefox with Tor on Desktop
     :width: 80%
     :alt: Firefox whitelist onions screenshot
 
-4. Create a `Proxy Auto Config` file (advanced) or use our `standard one <https://registry.start9labs.com/sys/proxy.pac>`_ (recommended), using the OS-specific instructions below:
+4. Download a `Proxy Auto Config` file to inform Firefox how to use the Tor daemon running on your computer. You can get Start9's standard file by following the OS-specific instructions below:
 
-Windows
+Windows:
 
-Download a `Proxy Auto Config` file that will use the Tor service to resolve .onion urls. We have one hosted. Save it somewhere you won’t delete it. For this example:
+Click `here <https://registry.start9labs.com/sys/proxy.pac>`_ to get the file and save the file somewhere you won’t delete it. For this example:
 
     .. code-block::
 
       C:\Program Files\Tor Browser\proxy.pac
 
-Mac
+Mac:
 
 Open the `Terminal` App on your Mac. You can find it in your list of Applications.  In the terminal, enter:
 
@@ -41,7 +41,7 @@ Open the `Terminal` App on your Mac. You can find it in your list of Application
 
       wget -P /usr/local/etc/tor https://registry.start9labs.com/sys/proxy.pac
 
-Linux
+Linux:
 
 From a terminal, enter:
 

source/misc-guides/tor-os/ios.rst

@@ -4,6 +4,6 @@
 Setting up Tor on iOS
 *********************
 
-Unfortunately, Apple does not allow tor to be run natively on iOS.  This means that Firefox cannot be configured to use tor.  This leaves 2 options for iOS users:
+Unfortunately, Apple does not allow tor to be run natively on iOS. This leaves 2 options for iOS users:
 
 You can use Start9 Labs' own Consulate Browser, which is available `here <https://apps.apple.com/us/app/start9-consulate-browser/id1528124570>`_, or you can select another Tor Browser by searching the `App Store <https://www.apple.com/us/search/onion-browser?src=serp>`_.

source/misc-guides/tor-os/windows.rst

@@ -28,7 +28,7 @@ Running Tor on Windows
 
    * In Windows 10, you can simply type ``cmd`` in the Windows search bar, right click on the first result, and select `Run as Administrator`.
 
-#. Once it opens, you can run the following commands, inserting your destination folder in place of ``<PATH TO>``:
+#. Once it opens, you can run the following commands, inserting your destination folder (from above) in place of ``<PATH TO>``:
 
    .. code-block::
 

source/support/FAQ/usage-faq.rst

@@ -54,15 +54,9 @@ No, you don’t need to delete the old backups. The technology we use updates th
 
 Can I clone my Embassy SD card for backup purposes?
 ---------------------------------------------------
-It is absolutely possible to do a deep clone of the card as a backup if you wish to do so, but there are some considerations when it comes to this. First off, we don't test/support that officially; it doesn't get nearly the same level of attention that the backups feature *within* the Embassy does. Secondly, it may take a while to do a deep clone of the card since the ones we ship are 128GB and there isn't a really effective way to clone the Embassy card that isn't a byte-for-byte copy. However, if you do a byte for byte copy (128GB), and run pishrink you could flash that image file onto a new card and restore all of your data.
+Warning: **DO NOT do this if you are running LND or c-lightning**. If you clone the SD card, then go back to running LND or c-lightning, and you *ever* try to restore the SD card, there is a good chance you will lose *all your channel funds*. Also, if you try to use the SD card for a 2nd Embassy, that will also result in loss of funds. This has nothing to do with Start9 or the Embassy; it is inherent to the architecture of Lightning.
 
-Another thing that must be mentioned, depending on what services you are running, if you are going outside of the Embassy backup flow you should be deeply aware of the implications of restoring backups. For instance, with LND it is *dangerous* to have multiple instances of the same LND node running at once because it can cause your channel funds to be completely lost. So while it would be safe for LND to restore the SD card if the original copy was completely offline, you should be aware that if it isn't offline you can lose all of that money.
-
-This is not just if you run two embassies. It can also happen if you conduct any lightning activity including letting the commitment fees update. The embassy backup system informs each service when it has been restored through the backup flow so that each service can respond appropriately how it sees fit. At the moment LND and c-lightning both respond to this by deleting their dangerous state. If you restore with a deep clone of the sd, this information is not included and so LND/c-lightning will unwittingly expose themselves to channel fund loss.
-
-And to be crystal clear, commitment fees update without user action.
-
-So all in all, if you are running lightning, we strongly advise that you DO NOT DO THIS.
+If you are not running LND or c-lightning, then *yes*, it is possible to do a deep clone of the SD card as a backup. But even here, there are some considerations: Start9 does not test/support this officially, which means it is untested. Also, it may take a while to do a deep clone of the card since the ones we ship are 128GB and there isn't a really effective way to clone the Embassy card that isn't a byte-for-byte copy. However, if you do a byte for byte copy (128GB), and run `PiShrink <https://github.com/Drewsif/PiShrink>`_ you could flash that image file onto a new card and restore all of your data.
 
 Why would I even buy this when I can just build it for free??
 -------------------------------------------------------------

source/user-manual/general/lan-setup/browser-setup.rst

@@ -1,9 +1,21 @@
-.. _browsers:
+.. _browser-setup:
 
-Browser Config
-==============
+Browser Setup
+=============
 
-.. warning:: Make sure you have completed setup on your :ref:`device <ssl-setup>` before continuing!
+.. warning:: Make sure you have completed your :ref:`computer setup <computer-setup>` before continuing!
+
+Select the browser you would like to configure to import the certificate from your desktop:
+
+.. .. toctree::
+..   :hidden:
+
+..   browser
+
+- :ref:`Brave <brave>`
+- :ref:`Chrome <chrome>`
+- :ref:`Firefox <firefox>`
+- :ref:`Safari <safari>`
 
 Select the browser you would like to configure to import the certificate from your desktop:
 

source/user-manual/general/lan-setup/computer-setup.rst

@@ -0,0 +1,187 @@
+.. _computer-setup:
+
+Computer Setup
+==============
+
+MacOS
+-----
+
+#. Visit your Embassy at its Tor Address.
+
+#. Navigate to --> Embassy --> Connect Over LAN
+
+   .. figure:: /_static/images/embassy_lan_setup.png
+    :width: 90%
+    :alt: LAN setup menu item
+
+    Select the "Connect over LAN" menu item
+
+#. Select the "Root Certificate Authority" sub menu. This will prompt a download to save the certificate file to your machine.
+
+   .. figure:: /_static/images/secure_lan_setup_page.png
+    :width: 90%
+    :alt: LAN setup page
+
+    Select the "Root Certificate Authority" sub menu
+
+#. Select the option to open your key with Keychain Access. If you choose to save file, double click on it once downloaded.
+
+   .. figure:: /_static/images/secure_lan_setup_prompt.png
+    :width: 90%
+    :alt: LAN setup prompt
+
+    Open with "Keychain Access" and select "OK"
+
+#. Enter your computer password when prompted. It will be imported into your computer’s keychain.
+
+   .. figure:: /_static/images/ssl/macos/certificate_untrusted.png
+    :width: 90%
+    :alt: Keychain access import menu
+
+    Keychain access import menu
+
+#. If the keychain console did not open, press "Command + spacebar" and type “Keychain Access”, and hit enter to open it.
+
+#. Navigate to the "System" tab and find the certificate entitled “Embassy Local Root CA”.
+
+#. Double click on this certificate. A second window will pop up.
+
+#. Open the “Trust” dropdown and select “Always Trust” from the dropdown next to “when using this certificate”.
+
+   .. figure:: /_static/images/ssl/macos/always_trust.png
+    :width: 90%
+    :alt: Keychain submenu
+
+    Select "Always trust" under SSL dropdown for Embassy Local CA
+
+#. Close this window and enter your password to apply the settings.
+
+#. The “Embassy Local Root CA” cert will now read “This certificate is marked as trusted for all users” in Keychain Access.
+
+   .. figure:: /_static/images/ssl/macos/certificate_trusted.png
+    :width: 90%
+    :alt: Keychain menu trusted certificate
+
+    Trusted Embassy Local CA certificate
+
+#. Open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.
+
+Windows
+-------
+
+#. Install `Bonjour Print Services <https://support.apple.com/kb/DL999>`_ on your Windows machine. This is necessary in order to visit .local addresses on Windows.
+#. If you are having issues running Bonjour after installing, you might have had Bonjour previously installed. To fix:
+
+   #. Check out this video: https://www.youtube.com/watch?v=9ECCB3bqNDQ
+   #. Uninstall Bonjour completely via ``system settings -> remove programs``
+   #. Reinstall Bonjour Printer Driver package (download at https://support.apple.com/kb/DL999?locale=en_US)
+   #. Restart Windows
+   #. Note: Uninstalling Bonjour via the setup package seems to be not enough to solve the issue. Bonjour must be uninstalled via windows system settings.
+
+#. Visit your Embassy at its Tor Address.
+
+#. Navigate to --> Embassy --> Connect Over LAN
+
+   .. figure:: /_static/images/embassy_lan_setup.png
+    :width: 90%
+    :alt: LAN setup menu item
+
+    Select the "Connect over LAN" menu item
+
+#. Select the "Root Certificate Authority" sub menu. This will prompt a download to save the certificate file to your machine.
+
+   .. figure:: /_static/images/secure_lan_setup_page.png
+    :width: 90%
+    :alt: LAN setup page
+
+    Select the "Root Certificate Authority" sub menu download icon
+
+#. Select the option to save the *Embassy Local CA.crt* file.
+
+   .. figure:: /_static/images/ssl/windows/windows_download_cert.png
+    :width: 90%
+    :alt: LAN setup prompt
+
+    "Save file" when Opening Embassy Local CA.crt
+
+#. On your computer, right-click the “Start” menu and select “Run”.
+
+#. Type in “mmc” and click “OK”. When prompted on the “User Account Control” window, select “Yes” to allow this program to run.
+
+   .. figure:: /_static/images/ssl/windows/1_windows_mmc.png
+    :width: 90%
+    :alt: Windows MMC
+
+    Access the Windows Management Console
+
+#. When the Management Console opens, navigate to *File > Add/Remove Snap-in*.
+
+   .. figure:: /_static/images/ssl/windows/2_windows_console_root.png
+    :width: 90%
+    :alt: Windows Console Root
+
+    Add Snap-in from Console Root
+
+#. Select “Certificates” in the left side menu, then “Add”. This will open another window.
+
+   .. figure:: /_static/images/ssl/windows/3_windows_add_certificates.png
+    :width: 90%
+    :alt: Add Certificates
+
+    Add Certificates to selected snap-ins
+
+#. Select “Computer account” and click “Next. Leave defaulted options on the next screen and click “Finish”.
+
+#. When you return to the “Add or Remove Snap-ins” page, ensure “Certificates (Local Computer)” exists under “Console Root” in the “Selected snap-ins” section, then click “OK”.
+
+   .. figure:: /_static/images/ssl/windows/4_windows_selected_snapin.png
+    :width: 90%
+    :alt: Snap-in Selected
+
+    Certificates (Local Computer) is selected as snap-in
+
+#. In the left hand menu of the Management Console, navigate to Certificates (Local Computer) > Trusted Root Certification Authorities > Certificates.
+
+   .. figure:: /_static/images/ssl/windows/5_windows_trusted_certificate_menu.png
+    :width: 90%
+    :alt: Certificates in Management Console
+
+    Access Certificates in Management Console
+
+#. Right click on “Certificates”, then navigate to *All Tasks > Import*.
+
+   .. figure:: /_static/images/ssl/windows/6_windows_import_cert.png
+    :width: 90%
+    :alt: Import certificate
+
+    Select "Import" from Certificates sub-menu
+
+#. Click “Next” on the first page of the Certificate Import Wizard, then browse to the location where you saved the downloaded certificate and click “Open”.
+
+   .. figure:: /_static/images/ssl/windows/7_windows_import_cert_wizard.png
+    :width: 90%
+    :alt: Import cert wizard
+
+    Add downloaded certificate int he Certificate Import Wizard
+
+#. On the “Certificate Store” window, ensure that it says “Trusted Root Certificate Authorities” and click “Next”.
+
+#. Select “OK” when the import is successful.
+
+#. Verify the Embassy Local Root CA certificate is in the “Certificates” folder.
+
+   .. figure:: /_static/images/ssl/windows/8_windows_successful_cert_install.png
+    :width: 90%
+    :alt: Successful cert install
+
+    Embassy Local Root CA imported into Certificate folder
+
+#. You can save the settings to the console if desired or cancel.
+
+#. Open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.
+
+
+Linux
+-----
+
+Nothing specific needs to be configured for this environment. Open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.

source/user-manual/general/lan-setup/desktop.rst

@@ -2,8 +2,10 @@
 Desktop
 *******
 
+Enabling LAN connectivity for desktop involves configuring both your computer and your browser.
+
 .. toctree::
   :maxdepth: 1
 
-  OS Config<os-config>
-  Browser Config<browser>
+  Computer Setup<computer-setup>
+  Browser Setup<browser-setup>