Merge pull request #27 from Start9Labs/docs-updates

Docs updates

source/conf.py

@@ -59,7 +59,7 @@ html_theme_options = {
     "use_edit_page_button": True,
     "use_issues_button": True,
     "use_repository_button": True,
-    "extra_navbar": "",
+    "extra_navbar": "Powered by <a href=\"https://start9.com\">Start9</a>", # Will be displayed underneath the left navbar"
     "show_navbar_depth": 1,
     "use_download_button": False,
     "use_edit_page_button": True,

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

@@ -35,6 +35,19 @@ Running Tor on Windows
     sc create tor start=auto binPath="<PATH TO>\Browser\TorBrowser\Tor\tor.exe -nt-service"
     sc start tor
 
+   .. note:: If you get the error "Access denied," please ensure you are running the command prompt in Administrator mode.  You can tell because the prompt will show C:\\Users\\YOUR-USERNAME> if you are NOT in admin mode, and it will show C:\\WINDOWS\\system32 if you ARE in admin mode.
+
+   .. note:: If you get the error "The specified service already exists," complete the following steps:
+
+      1. Run the command:
+
+      .. code-block::
+
+       sc delete tor
+
+      1. Uninstall the Tor Browser, following `these steps <https://tb-manual.torproject.org/uninstalling/>`_.
+      2. Begin this guide again from the beginning.
+
 #. When you run this, it should look something like this:
 
    .. figure:: /_static/images/tor/tor_windows_terminal.png

source/support/FAQ/bitcoin-faq.rst

@@ -26,7 +26,7 @@ It is fully validating and verifying consensus all the way from Genesis. Really,
 
 What actions, specifically, are only possible with an archival, or ‘unpruned’ node?
 -----------------------------------------------------------------------------------
-The more sophisticated the blockchain analysis being done is, the more index data is required, which will increase the system resources required.  For example, if you wanted to run a block explorer, you would require not only a full archival node, but also a full transaction index.
+The more sophisticated the blockchain analysis being done is, the more index data is required, which will increase the system resources required.  For example, if you wanted to run a block explorer, you would require not only a full archival node, but also a full transaction index.  So, specifically, at this time, a full archival node is required for running an Electrum server, a block explorer, and for doing advanced chain analysis in general.
 
 Is it insecure to run a pruned node?
 ------------------------------------
@@ -46,8 +46,8 @@ The commitment fees are automatically negotiated every few blocks with your peer
 
 What would happen if I shut down an Embassy that is running a Lightning node with open channels?
 ------------------------------------------------------------------------------------------------
-It is REALLY IMPORTANT that people understand that if they shut off their Lightning services for long periods of time (days on end) it is possible for your peers to cheat you out of money. If you are not prepared to LOSE ALL THE MONEY IN YOUR CHANNELS, KEEP YOUR NODE RUNNING.
+It is REALLY IMPORTANT to understand that if Lightning services are shut off for long periods of time (days on end) it is possible for your peers to cheat you out of money. If you are not prepared to LOSE ALL THE MONEY IN YOUR CHANNELS, KEEP YOUR NODE RUNNING.
-That said, malicious actors on the network right now are probably sparse, however you are still open to that risk if you do not keep your node online.
+That said, malicious actors on the network right now are probably sparse. However, you are still open to that risk if you do not keep your node online.
 
 Is there a solution to this?
 ----------------------------
@@ -70,9 +70,33 @@ Bitcoin Wallet Tracker and Electrum Personal Server are 2 services that do the s
 Both work with your Bitcoin node to provide a richer set of information to wallets than could be done with bitcoind alone.  They are basically identical in purpose, their differences are notably in the software memory requirements and how snappily they can answer the same questions.
 Electrum (and some other wallets) require more than just a Bitcoin node to run in a sovereign way, they require an “Electrum Server”. Both Electrum Personal Server and Bitcoin Wallet Tracker are “Electrum servers”.
 
+I want to use my hardware signer, such as Coldcard or Trezor, with my Embassy.  How does this work?
+---------------------------------------------------------------------------------------------------
+You do not use hardware signers directly with your node. Hardware signers interface with wallets, and wallets interface with nodes.
+
+Node (Embassy) <— Wallet (Specter, Sparrow, Electrum) <— Hardware signer (Coldcard, Trezor)
+
+You would use your hardware signee with your wallet, then instruct that wallet to use Embassy as its node.
+
+- Nodes are for interacting with the Bitcoin network: enforcing consensus rules, validating and relaying blocks/transactions, and broadcasting transactions.
+
+- Wallets are for constructing and viewing transactions, as well as generating addresses.
+
+- Signers are for generating and storing keys, as well as signing transactions.
+
+The reason there is so much confusion about these 3 concepts is that the Bitcoin Core Node comes with its own Wallet (which you should not use), and that wallet is also a signer. In fact, most wallets double as signers, and most wallets do NOT support connecting to your own node. So, most wallets are actually serving as a wallet, a node, and a signer, which might be convenient, but it is neither trustless nor maximally secure. Ideally, you are using a wallet that supports both integrating with a hardware signer (like Coldcard or Trezor) AND a backend node (like on the Embassy).
+
+Please note: of the wallets listed (Specter/Sparrow/Electrum), only Specter is currently able to use Embassy as it's node, but the other two should be available soon.
+
 Which wallets can I use that sync with my Embassy Bitcoin node?
 ---------------------------------------------------------------
-There are many wallets that support linking to your own full node.  You will need one that supports tor.  Here are a few options that are compatible: FullyNoded, Samourai, Specter, Wasabi, Zap, and Zeus.
+There are many wallets that support linking to your own full node.  You will need one that supports Tor.  Here are a few options that are compatible: FullyNoded, Samourai, Specter, Wasabi, Zap, and Zeus.
+
+Is there a guide for connecting Specter Wallet to my Embassy?
+-------------------------------------------------------------
+There is.  Please follow the integration guide `here <https://github.com/Start9Labs/bitcoind-wrapper/tree/master/docs/integrations/specter>`_ and select the tutorial based on your operating system.
+
+More guides, particularly in video form, are forthcoming.
 
 Is BlueWallet an option?
 ------------------------
@@ -96,7 +120,7 @@ All LND backups are best done via the Embassy backup flow.  It is not supported
 
 To clarify some of the reasons for this choice:
 
-First off, Lightning is fundamentally different than on-chain/Layer1(L1) bitcoin. There is no way to compress all of that information down into a single 24 word seed in such a way that it will continue to work throughout your usage of the Lightning Network. 
+First off, Lightning is fundamentally different than on-chain/Layer1(L1) bitcoin. There is no way to compress all of that information down into a single 24 word seed in such a way that it will continue to work throughout your usage of the Lightning Network.
 
 So, what is the LND seed *for*? In short, the seed is only used for the Layer1 portion of the funds you have locked up in LND. Due to the live nature of LND and lightning nodes in general, we tend to discourage keeping any significant amounts of money in the onchain portion of your wallet. Given that we cannot actually recover the Layer2(L2) funds with that seed, we needed to have a more holistic way to backup LND funds such that the backup would encompass the ability to get L2 funds back. The Embassy backup system does this, and this approach also happens to be a perfectly valid backup of your L1 funds as well. While Bitcoin users have been trained that the 24 word seed can be used to recover all of their funds, it is important to state that lightning does not and cannot work this way. Exposing the seed gives you two separate things to keep track of in order to recover your funds instead of just one.
 
@@ -112,6 +136,10 @@ Check the LND logs, it can take a while to bootstrap, and starting RTL before th
 ---------------------------------------------------------------------------------------------------
 You may need to restart the LND Service.
 
+I get the following error from LND: "Error ECONNREFUSED Fetching Info Failed! Unknown Error." What's wrong?
+-----------------------------------------------------------------------------------------------------------
+LND is waiting for Bitcoin to completely sync, and then needs to catch up on block scanning itself.  This may take several minutes, and in some cases might require a restart of the LND service.  Do this if the process takes more than 5-10 minutes.
+
 What's the best way to move a small lightning balance?
 ------------------------------------------------------
 It is possible to have lightning balances that are so low that they will not (or barely will) cover the on-chain fees to recoup into an on-chain wallet.

source/support/FAQ/embassy-faq.rst

@@ -61,4 +61,4 @@ Apps like Bitwarden however do not store plaintext information, so your password
 
 Why http and not https for .onion websites?
 -------------------------------------------
-When visiting a Tor V3 URL (.onion website), your communications are end-to-end encrypted and onion-routed by default. There is no added benefit to using https.
+When visiting a Tor V3 URL (.onion website), your communications are end-to-end encrypted and onion-routed by default. There is no added benefit to using https.  See this `article <https://community.torproject.org/onion-services/advanced/https/>`_ from the Tor Project for more details.

source/support/FAQ/general-faq.rst

@@ -74,6 +74,24 @@ Is the power supply that comes with Embassy 220v compatible?
 ------------------------------------------------------------
 Yes.
 
+Is the software Open Source?
+----------------------------
+Yes! EmbassyOS is open sourced under the `Start9 Personal Use License <https://start9labs.com/license>`_.  Some of our other projects are currently open sourced under MIT. You can find these in the Start9 Labs `GitHub repository <https://github.com/Start9Labs>`_.
+
+Is there a product warranty?
+----------------------------
+Yes! Start9 commits, to the best of our ability, to serving each beta Embassy product released into the wild. We will resolve any issue encountered with our provided hardware or software in a personalized matter.  We strive to provide highly available, quality customer service.
+
+Can you tell me about the License?
+----------------------------------
+EmbassyOS is published under our own Start9 Non-Commercial License, which has similar properties to many open source licenses with the exception that users cannot in any way, either through products or services, commercialize the source code, and any changes to the code or derivative works of the code are treated in the same manner. This means people will be welcome to access the source code, download it, use it, run it, fork it, change it, improve it - whatever they want - except sell it or sell services related to it.
+
+I run a business, can I use an Embassy for tasks such as password management and file sharing?
+----------------------------------------------------------------------------------------------
+Absolutely.  An Embassy would be a great addition to any business as it is easy to use and provides services that you control, with no subscription fees.
+
+With the addition of `BTCPay Server <https://btcpayserver.org/>`_, you can even run your own payment processor and accept cryptocurrency payments with no third party necessary!
+
 How does pricing work for EmbassyOS?  Are you targeting a specific USD price?
 -----------------------------------------------------------------------------
 The price is changed every 2016 blocks, which occurs about every 14 days. And no, the intent is not to tie EmbassyOS to a USD value, though at the moment USD is a convenient proxy for real purchasing power.

source/support/FAQ/index.rst

@@ -5,7 +5,7 @@ Frequently Asked Questions
 A collection of common questions and concerns from our community.
 
 .. toctree::
-  :maxdepth: 1
+  :maxdepth: 2
 
   general-faq
   embassy-faq

source/support/FAQ/services-faq.rst

@@ -49,7 +49,7 @@ Cups does not have multiple accounts support. Each person would need their own E
 
 Is the embassy able to connect to Sphinxchat?
 ---------------------------------------------
-Maybe, but we are also planning to add Sphinxchat to the Embassy directly.
+We have added Sphinx as an Embassy service.  Please see the announcement `here <https://start9labs.medium.com/new-service-sphinx-chat-2cd4f40d3f05>`_ and check the Marketplace to start using Sphinx!
 
 I get an error ("Unlock Wallet Failed") when trying to log in to RTL, what can I do?
 ------------------------------------------------------------------------------------
@@ -63,9 +63,11 @@ Can the browser extension be used with Bitwarden hosted on the embassy?
 -----------------------------------------------------------------------
 Yes, but only in a tor-enabled browser.  Just add your .onion address as the server in the extension.
 
-I heard I can connect Specter Wallet to my Embassy; is there a guide for that?
+I want to use BTCPayServer on my website, but Tor is the only option, how can visitors access my BTCPay on clearnet?
-------------------------------------------------------------------------------
+--------------------------------------------------------------------------------------------------------------------
-There is.  Please follow the integration guide `here <https://github.com/Start9Labs/bitcoind-wrapper/tree/master/docs/integrations/specter>`_ and select the tutorial based on your operating system.
+As the Embassy produces a Tor Hidden Service for each service, BTCPayServer is only available via Tor by default.  For a brick and mortar business, this is no problem as you can use your own device for a customer to pay you on.  If you run your own website, it is possible to set up a reverse proxy in order to serve BTCPay content to your clearnet visitors.  A guide to doing this is available in the `BTCPayServer docs <https://docs.btcpayserver.org/ReverseProxyToTor/>`_.
+
+We understand that this can be a frustrating limitation, and adding clearnet support is high on our list of priorities for the Embassy.  This will allow a number of services to have better interoperability with the broader Web.
 
 I don't see an answer to my question regarding a certain service.  Is there more documentation?
 -----------------------------------------------------------------------------------------------

source/support/FAQ/setup-faq.rst

@@ -4,11 +4,11 @@ Setup and Troubleshooting
 
 What do I do first?
 -------------------
-Simply plug the device into power and internet, typically from your home internet router.  That's it!  After this, get the :ref:`Setup App <initial-setup>`, and follow the instructions.
+Simply plug the device into power and internet, most easily by using an empty ethernet port on your home internet router.  That's it!  After this, get the :ref:`Setup App <initial-setup>`, and follow the instructions.
 
 How do I know if my Embassy is running?
 ---------------------------------------
-After plugging into power and internet, you will hear 2 distinct sounds: first, a “bep” ‐ indicating the device is powering on, and second, a “chime” ‐ indicating the device is ready for setup.
+After plugging into power and your router, you will hear 2 distinct sounds: first, a “bep” ‐ indicating the device is powering on, and second, a “chime” ‐ indicating the device is ready for setup.
 
 What if I can't connect to my Embassy?
 --------------------------------------

source/support/FAQ/usage-faq.rst

@@ -26,6 +26,14 @@ What’s the advantage of using the .local address over the .onion address?
 -------------------------------------------------------------------------
 If you are in your home network it is both faster and more private since the connection never leaves your household.  The downside is that it won’t work if you’re on the go.
 
+Can I use the .local addresses over the Tor Browser?
+----------------------------------------------------
+Unfortunately, no.  The Tor Browser requires all web visits to first enter the Tor network. Once you have entered the Tor network there is no way to exit the Tor network in such a way that .local/mDNS addresses resolve.
+
+Can I not use .local addresses on Android?  Why not?
+----------------------------------------------------
+Unfortunately, no.  Google has not included support for .local addresses via mDNS for Android.
+
 Is the software Open Source?
 ----------------------------
 Yes! EmbassyOS is open sourced under the `Start9 Personal Use License <https://start9.com/license>`_.  Some of our other projects are currently open sourced under MIT. You can find these in the Start9 Labs `GitHub repository <https://github.com/Start9Labs>`_.
@@ -48,6 +56,10 @@ Can I have multiple users on my Embassy?
 ----------------------------------------
 Currently, the Embassy itself is designed to for a single user. There is no way to grant others access to your Embassy without sharing your personal, master password, which is not recommended. There are certain services, however, such as Bitwarden, File Browser, and Mastodon, that absolutely support multiple users (aka multi-tenancy, aka uncle Jim model) where people who trust you can create their own, personal accounts for these services on your Embassy. Just remind them that they are trusting you with their data, and that it might be preferable for them to take the final leap of self-sovereignty and get an Embassy of their own.
 
+What can I do if I am having issues connecting to an Android app?
+-----------------------------------------------------------------
+Unfortunately, Orbot can be finicky, and therefore the best solution to Android issues is normally to restart Orbot, or to reboot the phone.  This will solve most common problems.
+
 Do I need to delete existing backups before doing a new backup? Or does a new backup override the old backup?
 -------------------------------------------------------------------------------------------------------------
 No, you don’t need to delete the old backups. The technology we use updates the existing backup.

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

@@ -17,6 +17,18 @@ Select the browser you would like to configure to import the certificate from yo
 - :ref:`Firefox <firefox>`
 - :ref:`Safari <safari>`
 
+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>`
+
 .. _brave:
 
 Brave

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

@@ -184,4 +184,24 @@ Windows
 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>`.
+Nothing specific needs to be configured for this environment, so you just need the certificate from your Embassy.
+
+#. 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
+
+Then open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.

source/user-manual/initial-setup.rst

@@ -16,9 +16,9 @@ Download the Setup App
 Power On
 ========
 
-Connect your Embassy to power and Ethernet.
+Connect your Embassy to power and Internet, normally using an ethernet port on your home Internet router.
 
-.. note:: to avoid networking issues, it is recommended to use your primary router, not an extender or mesh router.
+.. note:: To avoid networking issues, it is recommended to use your primary router, not an extender or mesh router.
 
 You will hear 2 distinct sounds:
 
@@ -28,7 +28,9 @@ You will hear 2 distinct sounds:
 Claim Your Embassy
 ==================
 
-1. Ensure your phone is connected to the same WiFi network as your router.
+1. Ensure your phone is connected to the same WiFi network as your router.  
+
+.. warning:: Sometmies a router will have a "guest WiFi network," which might be different than the network your Embassy is placed on via ethernet.
 
 2. Inside the Setup App, enter the product key located on the bottom of your Embassy