Merge pull request Start9Labs#42 from Start9Labs/versioning

elvece · web-flow · commit 4e59b06c85b3 · 2021-12-03T10:32:38.000-07:00
Versioning
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,5 @@
 .DS_Store
 .vscode/
 build/
-build-send.sh
+build-send.sh
+utils/deploy.sh
diff --git a/README.md b/README.md
@@ -19,6 +19,7 @@ brew install sphinx-doc
 pip3 install sphinx-autobuild
 pip3 install sphinx-book-theme || pip install git+https://github.com/executablebooks/sphinx-book-theme.git@master
 pip3 install sphinxcontrib.yt
+pip3 install sphinx-multiversion
 ```
 
 ### Development
@@ -43,7 +44,7 @@ Click on the "Issues" tab in the top navbar. Provide a good title and describe c
 
 ### Submitting a pull request
 
-Click on the "Pull requests" tab in the top navbar. Select the green "New pull request button" in the top right section. Select your branch for the compare dropdown, and master as the base. Provide an appropriate title and summary of the changes in the pull request description. Changes will be reviewed and merged when satisfactory. 
+Click on the "Pull requests" tab in the top navbar. Select the green "New pull request button" in the top right section. Select your branch for the compare dropdown, and master as the base. Provide an appropriate title and summary of the changes in the pull request description. Changes will be reviewed and merged when satisfactory.
 
 ## Helpful Resources
 
@@ -56,4 +57,8 @@ To update Sphinx Book Theme:
 - `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
+- Build and publish according to production release process
+
+## Versioning
+- Build for versioning: `sphinx-multiversion source build/html`
+- To view version metadata: `sphinx-multiversion source build/html --dump-metadata`
diff --git a/source/_templates/layout.html b/source/_templates/layout.html
@@ -11,4 +11,4 @@
 <meta property="og:image" content="https://start9.com/images/icon.png" />
 <meta name="og:description"
   content="Documentation, guides, and FAQ for Start9 software and hardware products, as well as general information about open source technologies, Bitcoin, Lightning, and Tor.">
-{% endblock %}
+{% endblock %}
diff --git a/source/_templates/versioning.html b/source/_templates/versioning.html
@@ -0,0 +1,15 @@
+{% if versions %}
+<h3>{{ _('Branches') }}</h3>
+<ul>
+  {%- for item in versions.branches %}
+  <li><a href="{{ item.url }}">{{ item.name }}</a></li>
+  {%- endfor %}
+</ul>
+<h3>{{ _('Tags') }}</h3>
+<ul>
+  {%- for item in versions.tags %}
+  <li><a href="{{ item.url }}">{{ item.name }}</a></li>
+  {%- endfor %}
+</ul>
+{% endif %}
+<!-- <h1>*testing versions*</h1> -->
diff --git a/source/conf.py b/source/conf.py
@@ -25,18 +25,42 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinxcontrib.yt'
+    'sphinxcontrib.yt',
+    'sphinx_multiversion'
     # 'sphinxcontrib.needs'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+# HTML sidebar widgets
+html_sidebars = {
+    "**": ["sidebar-logo.html", "search-field.html", "versioning.html", "sbt-sidebar-nav.html", "sbt-sidebar-footer.html"]
+}
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# Multiversion settings
+# Whitelist pattern for tags (set to None to ignore all tags)
+smv_tag_whitelist = r'^v\d+\.\d+$' # Include tags like "v2.1"
+
+# Whitelist pattern for branches (set to None to ignore all branches)
+smv_branch_whitelist = r'^.*$'
+
+# Whitelist pattern for remotes (set to None to use local branches only)
+smv_remote_whitelist = r'^(origin)$'
+
+# Pattern for released versions
+smv_released_pattern = r'^tags/.*$'
+
+# Format for versioned output directories inside the build directory
+smv_outputdir_format = 'versions/{ref.name}'
+
+# Determines whether remote or local git branches/tags are preferred if their output dirs conflict
+smv_prefer_remote_refs = True
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -56,12 +80,13 @@
     # "theme_dev_mode": True,
     "path_to_docs": "source",
     "repository_url": "https://github.com/Start9Labs/documentation",
+    "repository_branch": "master",
     "use_edit_page_button": True,
     "use_issues_button": True,
     "use_repository_button": True,
     "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_download_button": True,
     "use_edit_page_button": True,
     "launch_buttons": {
         "main_site": "https://start9.com",
@@ -75,4 +100,4 @@
 ]
 html_cs_files = [
     'default.css'
-]
+]
diff --git a/source/getting-started/diy.rst b/source/getting-started/diy.rst
@@ -12,8 +12,7 @@ DIY Guide
 
 By popular demand, we are pleased to present this "Do it Yourself" (DIY) guide for the Start9 Embassy personal server!
 
-.. warning:: This DIY guide is for EmbassyOS version 0.2.13. A substantive change will be made to this guide for EmbassyOS v0.3.0 scheduled for release in Q3 2021.  When 0.3.0 launches it will REQUIRE hardware updates, which you can find `here <https://start9.com/eos-0.3.0>`__.
-
+.. warning:: This DIY guide has directions for EmbassyOS versions 0.2.x and versions 0.3.x.  When 0.3.0 launches it will REQUIRE hardware updates, which you can find `here <https://start9.com/eos-0.3.0>`__.  Please keep in mind that version 0.3.x is not yet available for purchase!! Please stay tuned to our community channels for updates.
 
 
 Motivation
@@ -31,26 +30,24 @@ There are four reasons you might prefer to build your own Embassy instead of pur
 
 #. You just like building things.
 
-Hardware
-========
-
-Components (EmbassyOS versions 0.2.x)
--------------------------------------
+Building EmbassyOS Versions 0.2.x
+=================================
 
-.. note:: For newer versions of EmbassyOS (0.3.0 and above), please see the new hardware requirements `here <https://start9.com/eos-0.3.0>`__.  These pieces are *in addition* to the hardware below.
+Hardware: Components
+--------------------
 
 #. `Raspberry Pi 4B (8GB) <https://raspberrypi.org/products/raspberry-pi-4-model-b/?variant=raspberry-pi-4-model-b-8gb>`_
 #. `Power supply for Raspberry Pi 4B <https://raspberrypi.org/products/type-c-power-supply/>`_
 #. Case for Raspberry Pi 4B (`passive cooling recommended <https://www.amazon.com/Geekworm-Raspberry-Aluminum-Passive-Heatsink/dp/B07Z6FYHCH/>`_ `*`)
 #. `High endurance microSD <https://amazon.com/SanDisk-Endurance-microSDXC-Adapter-Monitoring/dp/B07NY23WBG/>`_ (recommended 128GB or more)
-#. `GPIO mini speaker/buzzer <https://www.amazon.com/Corporate-Computer-Motherboard-Internal-Speaker/dp/B01527H4W2/ref=sr_1_5?keywords=pc+internal+speaker&qid=1638200450&qsid=134-2367895-4553613&sr=8-5&sres=B07FCHT22L%2CB01DM56TFY%2CB01527H4W2%2CB07VZV7GHL%2CB097B53J39%2CB01MR1A4NV%2CB08QRYTPGH%2CB088CSDZQM%2CB08GKLQWZZ%2CB09B1W6MLL%2CB08777GG4P%2CB084TSLMC6%2CB086JXJ1LF%2CB08C4P78DK%2CB07Q81VG54%2CB07B2WLS17&srpt=SPEAKERS>`_ (These often sell out, please let us know if this link needs to be refreshed)
+#. `GPIO mini speaker/buzzer <https://www.amazon.com/Corporate-Computer-Motherboard-Internal-Speaker/dp/B01527H4W2/>`_ (These often sell out, please let us know if this link needs to be refreshed)
 #. Ethernet cable
-#. MicroSD → USB adapter (if no microSD port on your computer)
+#. MicroSD → USB adapter (or you may have a microSD port on your computer)
 
 `*` If you use a fan, **DO NOT** use the official Raspberry Pi fan, as it requires the same GPIO pins as the audio speaker. Instead, we recommend `this fan <https://www.amazon.com/Raspberry-iUniker-30x30x7mm-Brushless-RetroFlag/dp/B076H3TKBP/>`_.
 
-Assembly Instructions
----------------------
+Hardware: Assembly Instructions
+-------------------------------
 
 #. Insert mini speaker/buzzer into GPIO pins 6/8/10/12 with the word "speaker" facing out, `away from the board`.
 
@@ -60,18 +57,15 @@ Assembly Instructions
 
 That's it. Place the Raspberry Pi 4 board (with speaker attached), into its case.
 
-Getting EmbassyOS
-=================
-
-Purchasing
-----------
+Getting EmbassyOS: Purchasing
+-----------------------------
 
 You can purchase EmbassyOS `here <https://store.start9.com/collections/embassy/products/embassyos-software-download>`_. This is by far the easiest path to get up and running.
 
 Depending on your Internet speed, the download should take between 5 and 30 minutes.
 
-Building from Source
---------------------
+Getting EmbassyOS: Building from Source
+---------------------------------------
 
 If you have the proper tooling and are comfortable using the command line, you can build EmbassyOS from `source <https://github.com/Start9Labs/embassy-os>`_, which is made available under the `Start9 Personal Use License <https://start9.com/license>`_.
 
@@ -81,7 +75,69 @@ Thanks to our community members who have kindly put together these guides!
 * A technically focused guide by `t0mmysm1th <https://github.com/t0mmysm1th/embassy-os/blob/master/BuildGuide.md>`_
 
 Installing EmbassyOS
-====================
+--------------------
+
+Whether you purchase EmbassyOS from us or build it yourself, you need to flash it onto a microSD card.
+
+#. Download `balenaEtcher <https://www.balena.io/etcher/>`_ onto your Mac, Windows, or Linux computer.
+#. Insert the microSD card into your computer, either directly or using an adapter.
+#. Open balenaEtcher.
+#. Click `Select Image`, then find and select your copy of EmbassyOS.
+#. Click `Select Target`, then find and select your micro SD card.
+#. Click `Flash!` You may be asked to (1) approve the unusually large disk target or (2) enter your password. Both are normal.
+
+   .. figure:: /_static/images/diy/balena.png
+    :width: 60%
+    :alt: Balena Etcher Dashboard
+
+#. Once the image is flashed and verified, you may remove the micro SD, insert it into your Embassy, and power up the device.
+#. The Embassy is now ready for use, and you may following the normal :ref:`setup <initial-setup>` instructions. ``*``
+
+``*`` The first time you power it on, your Embassy will make more noises than future attempts, and it may take several minutes to finally complete.
+
+Building EmbassyOS Versions 0.3.x
+=================================
+
+Hardware: Components
+--------------------
+
+#. `Raspberry Pi 4B (8GB) <https://raspberrypi.org/products/raspberry-pi-4-model-b/?variant=raspberry-pi-4-model-b-8gb>`_
+#. `Power supply for Raspberry Pi 4B <https://raspberrypi.org/products/type-c-power-supply/>`_ Make sure this is at minimum 15w and 3.5a.
+#. Case for Raspberry Pi 4B (`passive cooling recommended <https://www.amazon.com/Geekworm-Raspberry-Aluminum-Passive-Heatsink/dp/B07Z6FYHCH/>`_ `*`)
+#. A `16GB microSD card <https://amazon.com/SanDisk-Endurance-microSDXC-Adapter-Monitoring/dp/B07NY23WBG/>`_ (no need for bigger). If you have ABSOLUTELY NO data to migrate, you may choose to re-use the card already in your Embassy.
+#. `GPIO mini speaker/buzzer <https://www.amazon.com/Corporate-Computer-Motherboard-Internal-Speaker/dp/B01527H4W2/>`_ (These often sell out, please let us know if this link needs to be refreshed)
+#. Ethernet cable
+#. MicroSD → USB adapter (or you may have a microSD port on your computer)
+#. An external drive (1TB minimum, 2TB SSD recommended), or an `internal drive <https://www.amazon.com/Crucial-MX500-NAND-SATA-Internal/dp/B078211KBB>`_ with an `USB enclosure <https://www.amazon.com/gp/product/B07T9D8F6C>`_, as sold with our upgrade kits. MUST CONNECT OVER USB 3.0
+
+`*` If you use a fan, **DO NOT** use the official Raspberry Pi fan, as it requires the same GPIO pins as the audio speaker. Instead, we recommend `this fan <https://www.amazon.com/Raspberry-iUniker-30x30x7mm-Brushless-RetroFlag/dp/B076H3TKBP/>`_.
+
+Hardware: Assembly Instructions
+-------------------------------
+
+#. Insert mini speaker/buzzer into GPIO pins 6/8/10/12 with the word "speaker" facing out, `away from the board`.
+
+   .. figure:: /_static/images/diy/pins.png
+    :width: 60%
+    :alt: Speaker board spec
+
+#. Place the Raspberry Pi 4 board (with speaker attached), into its case.
+#. Plug in the external drive to one of the USB 3.0 (blue) slots
+
+Getting EmbassyOS: Purchasing
+-----------------------------
+
+You can purchase EmbassyOS `here <https://store.start9.com/collections/embassy/products/embassyos-software-download>`_. This is by far the easiest path to get up and running.
+
+Depending on your Internet speed, the download should take between 5 and 30 minutes.
+
+Getting EmbassyOS: Building from Source
+---------------------------------------
+
+A detailed build guide will be available around the time of the v0.3.0 release (or now, if you snoop around our GitHub long enough).
+
+Installing EmbassyOS
+--------------------
 
 Whether you purchase EmbassyOS from us or build it yourself, you need to flash it onto a microSD card.
 
@@ -96,7 +152,7 @@ Whether you purchase EmbassyOS from us or build it yourself, you need to flash i
     :width: 60%
     :alt: Balena Etcher Dashboard
 
-#. Once the image is flashed and verified, you may remove the micro SD and insert it into your Embassy.
+#. Once the image is flashed and verified, you may remove the micro SD, insert it into your Embassy, and power up the device.
 #. The Embassy is now ready for use, and you may following the normal :ref:`setup <initial-setup>` instructions. ``*``
 
 ``*`` The first time you power it on, your Embassy will make more noises than future attempts, and it may take several minutes to finally complete.
diff --git a/source/support/FAQ/030-faq.rst b/source/support/FAQ/030-faq.rst
@@ -34,29 +34,25 @@ If you are unsure what drive type is best for you, get an external SSD with a US
 
 3 - For the SD card, any type will work, and 16GB is recommended.  A larger card will not offer any benefit.  These are $5-10USD. EmbassyOS will be stored on this card.
 
-4 - For the powered USB hub, any kind will work as long as it has it's own power supply and is USB 3.0 capable.
-
 What size drive do I need?
 --------------------------
 This will depend on how you want to use your Embassy.  We recommend a minimum of 1TB if you intend to run a pruned Bitcoin node, or no Bitcoin node at all, and a 2TB minimum if you intend to run a full archival node, which will add a lot more functionality.
 
 If you intend to run your own "cloud", then consider the amount of data you are storing.  If you have lots of video files, for example, you may start filling up the disk fairly quickly.  Any service you are currently using should have a simple way for you to view your data usage.  Make sure to leave plenty of room for expansion.
 
-Finally, remember that you can always expand to a larger drive in the future.  EOS will also be adding the ability to store on multiple drives, and other advanced storage features, in the near future.
+Finally, remember that you can always expand to a larger drive in the future.  EOS will also be adding additional advanced storage features in the near future.
 
 I want to add an HDD later, in addition to my SSD, what are the performance consequences of doing this?
 -------------------------------------------------------------------------------------------------------
-After additional drive support is added (v0.3.x, no current ETA), we will recommend using uniform drives, but it will not be required.  If you choose to add a lower performance HDD to an existing SSD in order to increase storage capacity, the reads and writes to the HDD will obviously be slower, but otherwise there will not be any issues.
-
-The reason we will recommend uniform drives is because we will be adding the ability to create redundancy (drive mirroring, as an advanced feature), if you are interested.  This will only be necessary if uptime is very important to you, such as when running a Lightning routing node, or serving a popular .onion site.  Most users will find that a single drive, adding drives as space is needed, will suit their needs just fine.
+At this time, we recommend against this as the Raspberry Pi cannot deliver enough power.  We will be revisiting in future, but a powered usb hub would be a minimum requirement for this setup.
 
 Can I use an internal SSD with a USB 3 enclosure?  I've heard these may have issues?
 ------------------------------------------------------------------------------------
 Yes, you may, and our original upgrade kits come with this style of drive.  We have addressed the known issues in software, and in the rare event of hardware failure, we are here to help.
 
 Does my external drive need its own power supply?
 -------------------------------------------------
-We are recommending the use of a powered USB hub to connect drives with (and power the Pi if it has USB-C).  However, you may use powered disk drives if you prefer.
+You may use powered disk drives if you prefer, but if only connecting one SSD, it is not necessary.
 
 Can I re-use the SD Card from my Embassy for the new version?
 -------------------------------------------------------------
diff --git a/source/support/FAQ/dev-faq.rst b/source/support/FAQ/dev-faq.rst
@@ -17,16 +17,15 @@ What considerations go into selecting an application to package?
 With sufficient effort, most any software with the ability to be self-hosted could make its way onto EmbassyOS.  That being said, the following features will make service packaging much easier:
 
 - Already built with self-hosting in mind
-- Active development
-- Built-in tor support
+- Active development / community
+- Native proxy/tor support
 - Already 'dockerized'
 
 Which possible formats can I use to write the :code:`manifest`, :code:`config_spec`, and :code:`config_rules` files?
----------------------------------------------------------------------------------------------------------------------
+--------------------------------------------------------------------------------------------------------------------
 JSON, TOML, or YAML are valid options.
 
 I'm getting errors on the `embassy-sdk pack` step.  What's going on?
 --------------------------------------------------------------------
 There is something either missing or incorrect in regard to one of the :code:`manifest`, :code:`configs`, :code:`instructions`, or :code:`icon` files.
 
-
diff --git a/source/support/FAQ/setup-faq.rst b/source/support/FAQ/setup-faq.rst
@@ -58,4 +58,8 @@ This has been fixed in newer updates.  Please first make sure to update to the l
 
 Is it true that iOS has some limited functionality in regard to the Embassy?
 ----------------------------------------------------------------------------
-The short answer is yes, but not much.  Unfortunately, Apple does not allow any ability for Tor to run in the background (everything on the Embassy runs over Tor).  Most of your Embassy services can be run with Tor-native apps, inside Consulate, or with another Tor browser, with the exception of RTL, Spark, and Matrix.  Zap and Zeus wallets can be used in place of RTL/Spark, and we hope a Tor-native Element client will be available soon to allow for the use of Matrix.
+The short answer is yes, but not much.  Unfortunately, Apple does not allow any ability for Tor to run in the background (everything on the Embassy runs over Tor).  Most of your Embassy services can be run with Tor-native apps, inside Consulate, or with another Tor browser, with the exception of RTL, Spark, and Matrix.  Zap and Zeus wallets can be used in place of RTL/Spark, and we hope a Tor-native Element client will be available soon to allow for the use of Matrix.
+
+I'm having trouble using Firefox for Tor addresses on Lineage, what can I do?
+-----------------------------------------------------------------------------
+Unfortunately, there seems to be a bug in Lineage that makes using Firefox over Tor currently unusable.  Currently, this feature works fine on Calyx and Graphene.
