Start9/documentation
2
0
Fork 0
mirror of https://github.com/Start9Labs/documentation.git synced 2026-03-26 10:21:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

change embassyOS to StartOS & nuance (#357)

Browse Source 
* change embassyOS to StartOS & nuance

* Update conf.py

* Update manifest.rst

* say start9 instead of embassy in two links

* progress

* scrubbed faqs - basic-use, lightning, service-packaging, services, startos

* add a few fixes

* more

* more 'embassy' cleanup

* more

* the last of embassy (aside from sdk and cli commands, links, etc)

* some fixes

* update icon, logo, and theme

* Update site/source/user-manual/upgrade-hardware/upgrade-pro.rst

* Update site/source/developer-docs/packaging.rst

* Update site/source/developer-docs/specification/config-spec.rst

* Update site/source/learn/concepts/networks.rst

* Update site/source/learn/concepts/networks.rst

* Update site/source/user-manual/customize.rst

* Update site/source/support/faq/faq-basic-use.rst

* Update site/source/user-manual/upgrade-hardware/naspi-upgrade.rst

* Update site/source/user-manual/upgrade-hardware/upgrade-pro.rst

* Update site/source/support/faq/faq-bitcoin.rst

* Update site/source/support/faq/faq-bitcoin.rst

* Update site/source/support/faq/faq-general.rst

* Update site/source/support/faq/faq-general.rst

* Update site/source/support/faq/faq-general.rst

* Update site/source/support/faq/faq-general.rst

* Update site/source/support/faq/faq-services.rst

* Update site/source/support/faq/faq-general.rst

* Update site/source/support/faq/faq-startos.rst

* Update site/source/support/faq/faq-troubleshooting.rst

* Update site/source/support/faq/faq-startos.rst

* Minor fixes

* Fix build errors, ready to roll

* Add Beethoven

* More fixes

* More nother fix

* More nother fixes agin

* Remove sentence

* cards instead

---------

Co-authored-by: Matt Hill <matthewonthemoon@gmail.com>
Co-authored-by: Shadowy Super Coder <musashidisciple@proton.me>
Co-authored-by: Lucy Cifferello <12953208+elvece@users.noreply.github.com>
Co-authored-by: kn0wmad <39687477+kn0wmad@users.noreply.github.com>
Co-authored-by: agent <kn0wmad@protonmail.com>
This commit is contained in:
BitcoinMechanic
2023-05-23 12:58:32 -07:00
committed by GitHub
parent 404182cffa
commit 60f83aa683
130 changed files with 879 additions and 1030 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
site/source/support/common-issues.rst
View File

@@ -8,42 +8,42 @@ Common Issues
:depth: 2
:local:
Sometimes things don't go as planned. Check here for solutions to common problems with your Embassy.
Sometimes things don't go as planned. Check here for solutions to common problems with StartOS.
Embassy will not boot
StartOS will not boot
---------------------
If the device will not power on at all (no lights whatsoever), then the only issues could be that the Pi is not getting the power it needs, or it is completely dead (extremely rare). If you sourced your own parts, please ensure that the power supply meets the minimum required specifications in the :ref:`DIY Guide<diy>`. If you received your device from us and it will not power up at all, please :ref:`Contact us<contact>` for assistance.
Embassy boots into "Diagnostic Mode"
StartOS boots into "Diagnostic Mode"
------------------------------------
Diagnostic Mode is a new UI that will launch in the event that no drive, or an incorrect drive (such as one from another Embassy) has been plugged into Embassy. Simply plug your external drive in and reboot (power off and on again).
Diagnostic Mode is a new UI that will launch in the event that no drive, or an incorrect drive (such as one from another StartOS server) has been plugged into your server. Simply plug your external drive in and reboot (power off and on again).
.. _setup-troubleshoot:
During initial setup, I am unable to connect to "embassy.local".
During initial setup, I am unable to connect to "start.local".
----------------------------------------------------------------
* Confirm that your Embassy is plugged into both power and Ethernet.
* Confirm that the server is plugged into both power and Ethernet.
* Confirm the Embassy emitted two :ref:`sounds<sounds>` when powering on: a bep and a chime.
* Confirm the the server emitted two :ref:`sounds<sounds>` when powering on: a bep and a chime.
* Confirm your phone is **not** connected to a “Guest” network
* Confirm your phone is **not** using a VPN.
If you still cannot connect, try logging into your router (the directions for which can be found with a simple web search for your router model and 'how to log in'). Once you are in your router, find the device labeled 'Embassy,' and visit it's associated IP address, which will look something like: ``192.168.1.9``
If you still cannot connect, try logging into your router (the directions for which can be found with a simple web search for your router model and 'how to log in'). Once you are in your router, find the device labeled ``start``, and visit it's associated IP address, which will look something like: ``192.168.1.9``
I am unable to reach Embassy via it's embassy-xxxxxxxx.local (LAN) address
I am unable to reach my server via its *<custom-address>.local* (LAN) address
------------------------------------------------------------------------------
Make sure you have successfully followed the :ref:`LAN Setup<connecting-lan>` instructions for your device. If you are using Windows, your problem is almost certainly with Bonjour - follow the directions to reinstall, even if you have already done so. If you still cannot connect, try all the solutions listed under :ref:`initial setup <setup-troubleshoot>`.
I am unable to reach Embassy via it's xxxxxxxxxxxxxxxxxx.onion (Tor) address
I am unable to reach my server via its xxxxxxxxxxxxxxxxxx.onion (Tor) address
--------------------------------------------------------------------------------
#. **Test** - Try connecting to your Embassy using the preferred :ref:`Tor Browser <tor-browser>`.
#. **Test** - Try connecting to your server using the preferred :ref:`Tor Browser <tor-browser>`.
#. **If Tor Browser works** - It means the issue is either with the Tor daemon on your device or with the browser settings.
@@ -51,19 +51,19 @@ I am unable to reach Embassy via it's xxxxxxxxxxxxxxxxxx.onion (Tor) address
#. If you are not yet running a Tor daemon on your device, follow :ref:`these instructions <tor-os>`. If you are already running a Tor daemon, restart it, or in the case of Android, restart your phone.
#. If you are using Firefox, ensure it has been :ref:`properly configured <tor-firefox>` to work with .onion URLs.
#. **If Tor Browser does not work** - It means there is an issue with your Embassy or with the Tor network.
#. **If Tor Browser does not work** - It means there is an issue with your server or with the Tor network.
#. **Test** - Try visiting your Embassy over :ref:`LAN<connecting-lan>` from a non-Tor browser such as Firefox, Chrome, or Safari.
#. **Test** - Try visiting your server over :ref:`LAN<connecting-lan>` from a non-Tor browser such as Firefox, Chrome, or Safari.
#. **If LAN works** - it means the issue is an issue your Embassy's Tor connection.
#. **If LAN works** - it means the issue is an issue your server's Tor connection.
#. **Solutions**
#. Check if there are any ongoing network-wide service issues with Tor at `the Tor Project status page <https://status.torproject.org/issues/>`_
#. Wait an hour or so to allow Tor on your Embassy to fix itself.
#. Restart your Embassy through the UI (Embassy -> Restart).
#. **If LAN does not work** - It means your Embassy is experiencing general networking issues.
#. Wait an hour or so to allow Tor on your server to fix itself.
#. Restart your server through the UI (System -> Restart).
#. **If LAN does not work** - It means your server is experiencing general networking issues.
#. **Solutions** - Power cycle your Embassy by unplugging it and plugging it back in, then wait a few minutes before trying to connect again.
#. **Solutions** - Power cycle your server by unplugging it and plugging it back in, then wait a few minutes before trying to connect again.
I'm having an issue with a particular Service
---------------------------------------------

10
site/source/support/contact.rst
View File

@@ -21,9 +21,9 @@ Community Channels
* `Matrix <https://matrix.to/#/#community:matrix.start9labs.com>`_ - Community channel that will gradually replace Telegram (now bridged to Telegram for convenience).
* `Matrix Dev <https://matrix.to/#/#community-dev:matrix.start9labs.com>`_ - Primary channel for collaboration on embassyOS development and service packaging.
* `Matrix Dev <https://matrix.to/#/#community-dev:matrix.start9labs.com>`_ - Primary channel for collaboration on StartOS development and service packaging.
* `Matrix Tor (Tor required) <https://matrix.to/#/!iRwnQntcjpWfLxdgav:matrix.privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion?via=matrix.start9labs.com&via=matrix.privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion&via=oayal5vhil3zhj7ylixvpi4nr2xvhypdnenji4sx5q4kvaotevjvsxad.onion>`_ - Tor-only community channel for Embassy users
* `Matrix Tor (Tor required) <https://matrix.to/#/!iRwnQntcjpWfLxdgav:matrix.privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion?via=matrix.start9labs.com&via=matrix.privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion&via=oayal5vhil3zhj7ylixvpi4nr2xvhypdnenji4sx5q4kvaotevjvsxad.onion>`_ - Tor-only community channel for StartOS users
Social Media
------------
@@ -33,3 +33,9 @@ Social Media
* `Twitter <https://twitter.com/start9labs>`_
* `GitHub <https://github.com/start9labs>`_
Email
-----
* security@start9.com - for reporting sensitive information or security concerns.
* affiliate@start9.com - for those interested in becoming a Start9 affiliate.

4
site/source/support/external-support.rst
View File

@@ -11,8 +11,8 @@ External Support
If you ever need direct support from the developers or community of a particular service or integration, you can find it here.
Embassy Services
----------------
Start9 Sponsored Services
-------------------------
Bitcoin Core
============

46
site/source/support/faq/faq-basic-use.rst
View File

@@ -10,40 +10,36 @@ Basic Use FAQ
Is it easy to use?
------------------
Yes! The Embassy is designed to be plugged into power and internet, and after a short setup, is immediately ready to use. Getting Services is as easy as getting apps for a smartphone.
Yes! A Start9 server is designed to be plugged into power and internet, and after a short setup, is immediately ready to use. Getting Services is as easy as getting apps for a smartphone.
As with anything new, you should expect to spend a little time learning the functions and features, and keep in mind that some Services may be more complex to understand and use than others.
So I can run my own cloud?
--------------------------
Yes! No special skills or knowledge are required to host all your own services and replace those previously thought "necessary" for modern digital life.
Can I run multiple Embassies?
-----------------------------
Can I run multiple Start9 servers?
----------------------------------
Yes, but there is currently no way to synchronize or federate them. We are working on ways to make this possible in the future.
Can I still use my VPN?
-----------------------
The short answer is yes, but they can cause some conflicts when accessing your Embassy. If you need to troubleshoot, turning off your VPN is a good place to start. The following VPNs are known to not interfere with the proper settings:
The short answer is yes, but they can cause some conflicts when accessing your server. If you need to troubleshoot, turning off your VPN is a good place to start. The following VPNs are known to not interfere with the proper settings:
- Mullvad - Go to "Settings -> VPN Settings -> Local Network Sharing" - enable this option to be able to access your Embassy's ``.local`` addresses.
- ProtonVPN - Go to "Preferences -> Connection -> Allow LAN Connections" - enable this option to be able to access your Embassy's ``.local`` addresses.
- IVPN - Go to "Settings -> IVPN Firewall -> LAN settings -> Allow LAN traffic when IVPN firewall is enabled" - enable this option to be able to access your Embassy's ``.local`` addresses.
- Mullvad - Go to "Settings -> VPN Settings -> Local Network Sharing" - enable this option to be able to access your server's ``.local`` addresses.
- ProtonVPN - Go to "Preferences -> Connection -> Allow LAN Connections" - enable this option to be able to access your server's ``.local`` addresses.
- IVPN - Go to "Settings -> IVPN Firewall -> LAN settings -> Allow LAN traffic when IVPN firewall is enabled" - enable this option to be able to access your server's ``.local`` addresses.
What if I forget my Embassy password?
What if I forget my StartOS password?
-------------------------------------
Please follow the :ref:`password reset guide<reset-password>`.
My Embassy is set up, now what?
-------------------------------
Check out the :ref:`Dashboard Overview<dashboard-overview>` for some details on your Embassy. You can now access your Embassy and find the Services you want from the "Marketplace" tab, then clicking "Install." The Service will let you know if you need any "dependencies," or pre-requisite Services, first. After you have a Service installed, don't forget to "Start" the service.
Can I move my Embassy to another location? What happens when I do this?
Can I move my server to another location? What happens when I do this?
------------------------------------------------------------------------
Yes, you can move the Embassy to another network. Your service tor addresses will remain the same. Remember that you can only access via LAN if you are accessing with a device on the same network as your Embassy.
Yes, you can move your server to another network. Your service tor addresses will remain the same. Remember that you can only access via LAN if you are accessing with a device on the same network as your server.
What's the advantage of using the .local address over the .onion address?
-------------------------------------------------------------------------
If you are in your home/office network with an Embassy, it is both faster and more private since the connection never leaves your household/office. The downside is that it won't work if you're on the go.
If you are in your home/office network with your server, it is both faster and more private since the connection never leaves your household/office. The downside is that it won't work if you're on the go.
Can I use the .local addresses over the Tor Browser?
----------------------------------------------------
@@ -53,9 +49,9 @@ Can I use .local addresses on Android?
--------------------------------------
This will depend on your Android device. This support was added in Android 12. For custom ROMs, such as Calyx and Graphene, version 13 is required.
Can I have multiple users on my Embassy?
Can I have multiple users on StartOS?
----------------------------------------
Currently, the Embassy itself is designed 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 do support multiple users (aka multi-tenancy, aka the Uncle Jim model) where people who trust you (and vice versa) 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.
Currently, StartOS itself is designed for a single user. There is no way to grant others access to your server without sharing your personal, master password, which is not recommended. There are certain services, however, such as Bitwarden, File Browser, and Mastodon, that do support multiple users (aka multi-tenancy, aka the Uncle Jim model) where people who trust you (and vice versa) can create their own, personal accounts for these services. 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 a server of their own.
Multi-tenancy is a desired future OS feature. Stay tuned.
@@ -65,7 +61,7 @@ Unfortunately, Orbot can be finicky. The best solution to connection issues is
If I uninstall a service, then re-install it, does any data remain?
-------------------------------------------------------------------
No. When uninstalling a service, you completely destroy everything associated with it. This is because each service runs in it's own 'container', which includes all the required software and operating system environment that it needs to function. When uninstalling, this container is wiped from your Embassy's system, and with it, any associated service data that you have not backed up.
No. When uninstalling a service, you completely destroy everything associated with it. This is because each service runs in it's own 'container', which includes all the required software and operating system environment that it needs to function. When uninstalling, this container is wiped from StartOS, and with it, any associated service data that you have not backed up.
This can be useful, as you may want to wipe a service and start anew. For example, you might want to receive a fresh Tor .onion address, or to spin up a new Lightning node. However, if you do this, YOU MUST BE 100% CERTAIN THAT YOU ARE PREPARED TO LOSE ALL DATA for this service. Also, keep in mind that other services may depend on the service you are uninstalling.
@@ -73,24 +69,24 @@ Do I need to delete existing backups before doing a new backup? Or does a new ba
-------------------------------------------------------------------------------------------------------------
No, you don't need to delete the old backups. The technology we use updates the existing backup. This is known as a "diff-based" model, where the "difference" in backups is what is recorded.
Can I clone my Embassy SSD for backup purposes?
Can I clone my SSD for backup purposes?
-----------------------------------------------
.. warning:: **DO NOT do this if you are running LND or CLN**. If you clone the SSD, then go back to running LND or CLN, and you *ever* try to restore the SSD, there is a good chance you will lose *all your channel funds*. Also, if you try to use the SSD 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.
.. warning:: **DO NOT do this if you are running LND or CLN**. If you clone the SSD, then go back to running LND or CLN, and you *ever* try to restore the SSD, there is a good chance you will lose *all your channel funds*. Also, if you try to use the SSD for a 2nd server, that will also result in loss of funds. This has nothing to do with Start9 or StartOS; it is inherent to the architecture of Lightning.
It is neither necessary, nor recommended to do this. The backup solution available in embassyOS (v0.3.0+) allows all data to be written to another drive remotely, and this can mean another SSD, attached to a computer on your network. You may also do a backup to a local drive if it has external power. Please follow the directions in the backup UI for more details.
It is neither necessary, nor recommended to do this. The backup solution available in StartOS (v0.3.0+) allows all data to be written to another drive remotely, and this can mean another SSD, attached to a computer on your network. You may also do a backup to a local drive if it has external power. Please follow the directions in the backup UI for more details.
Why would I even buy this when I can just build it for free?
------------------------------------------------------------
(1) You will get white glove support in your preferred format, from email to text chat to screen sharing conference calls.
(2) Supporting the project. Buying an Embassy from Start9 is your way of supporting the development of the project. And it's not just out of gratitude, but rather, a recognition that if the project isn't funded, the cool software stops coming.
(2) Supporting the project. Buying a server from Start9 is your way of supporting the development of the project. And it's not just out of gratitude, but rather, a recognition that if the project isn't funded, the cool software stops coming.
(3) Convenience. This is the big one. It's true, some people will choose to use the software without buying an Embassy, but most will not. Very few people on Earth are comfortable using the command line, compiling code, and configuring an OS. Furthermore, hardware is necessary. Sure, some people already have a Raspberry Pi, and others may try to re-purpose an old laptop, but many people would be choosing between buying the Embassy hardware components themselves and assembling vs buying pre-assembled at a reasonable markup.
(3) Convenience. This is the big one. It's true, some people will choose to use the software without buying a server, but most will not. Very few people on Earth are comfortable using the command line, compiling code, and configuring an OS. Furthermore, hardware is necessary. Sure, some people already have a Raspberry Pi, and others may try to re-purpose an old laptop, but many people would be choosing between buying the hardware components themselves and assembling vs buying pre-assembled at a reasonable markup.
Bottom line...We are charging a very marginal rate for something incredibly powerful, and we think the convenience of a plug-and-play device, free service marketplace, and free white glove support is where the money is. Anyone could build their own couches too, but here is a reason furniture stores exist. How much is your time worth?
The fastest way to get support is via our :ref:`Community channels<contact>`. Please do not hesitate to reach out!
I bought an Embassy before Q3 2022 and it came with a 'product key,' what is that?
----------------------------------------------------------------------------------
I bought a server from Start9 before Q3 2022 and it came with a 'product key,' what is that?
--------------------------------------------------------------------------------------------
This will entitle you to white glove support as well as future benefits yet to be announced. Newer products ship with a similar (anonymous) key for these purposes.

36
site/source/support/faq/faq-bitcoin.rst
View File

@@ -10,7 +10,7 @@ Bitcoin FAQ
Why does the Bitcoin service take so long to be ready?
------------------------------------------------------
On first install, the Bitcoin service must verify the entire history of transactions in order to verify transactions going forward. This can take up to a week depending on your internet connection. On a fast connection, you can expect 3-4 days. You can continue to use your Embassy normally in the meantime.
On first install, the Bitcoin service must verify the entire history of transactions in order to verify transactions going forward. This can take up to a week depending on your internet connection. On a fast connection, you can expect 3-4 days. You can continue to use your server normally in the meantime.
You can learn more about the Initial Block Download in `this video <https://www.youtube.com/watch?v=OrYDehC-8TU>`_.
.. youtube:: OrYDehC-8TU
@@ -18,11 +18,11 @@ You can learn more about the Initial Block Download in `this video <https://www.
Can the IBD (Initial Block Download) be made faster? Or can wait times be improved?
------------------------------------------------------------------------------------
IBD was made significantly faster with the new hardware scheme of version 0.3.0 and up. Going forward the only way to improve IBD speeds will be on more powerful hardware, such as Embassy Pro.
IBD was made significantly faster with the new hardware scheme of version 0.3.0 and up. Going forward the only way to improve IBD speeds will be on more powerful hardware.
Does the Embassy run a full archival Bitcoin node or a pruned one?
------------------------------------------------------------------
Previous Embassy versions (pre-0.3.0) only allowed a pruned node, but the option is now yours. In the Bitcoin Config, find the section on pruning, and set to 'Manual' or 'Automatic' to to prune to specified sizes, or turn pruning off entirely for a full archival node. Please keep in mind that a full archival node will take up between 400-500GB of your drive as of 2022.
Does StartOS run a full archival Bitcoin node or a pruned one?
--------------------------------------------------------------
Previous versions of StartOS (pre-0.3.0) only allowed a pruned node, but the option is now yours. In the Bitcoin Config, find the section on pruning, and set to 'Manual' or 'Automatic' to to prune to specified sizes, or turn pruning off entirely for a full archival node. Please keep in mind that a full archival node will take up between 400-500GB of your drive as of 2022.
What actions, specifically, are only possible with an archival, or 'unpruned' node?
-----------------------------------------------------------------------------------
@@ -32,11 +32,11 @@ Many wallets also do not yet support pruned nodes, which is one big reason that
Is it insecure to run a pruned node?
------------------------------------
As a user, pruned nodes and archival nodes provide you the same security. In a larger sense, if 100% of people ran pruned nodes, the security of the network could be in dire circumstances and be put at risk if no nodes kept history, as then no one could bootstrap new nodes. The reality however, is that most Embassy owners are new node operators, so there is no net systemic risk introduced if users decide to run a pruned node.
As a user, pruned nodes and archival nodes provide you the same security. In a larger sense, if 100% of people ran pruned nodes, the security of the network could be in dire circumstances and be put at risk if no nodes kept history, as then no one could bootstrap new nodes. The reality however, is that most StartOS users are new node operators, so there is no net systemic risk introduced if users decide to run a pruned node.
The Bitcoin Service is different from the GUI version I am used to using (bitcoin-qt). How do I use this like I used to?
-------------------------------------------------------------------------------------------------------------------------
At present, the Embassy does not offer its own node visualization tool. You can view certain properties about your node inside the "Properties" section, but not in an animated GUI. If you want to use bitcoin-cli, you may do so by adding an SSH key onto your Embassy and :ref:`exec-ing into the bitcoind docker container<service-container>`. Otherwise, the main way to actually *use* your node is through a wallet. The QT GUI is not usable because it cannot be served through the browser (which is necessary here), and last we checked, the QT desktop client was incapable of connecting to a remote node over Tor.
At present, StartOS does not offer its own node visualization tool. You can view certain properties about your node inside the "Properties" section, but not in an animated GUI. If you want to use bitcoin-cli, you may do so by adding an SSH key to your server and :ref:`exec-ing into the bitcoind docker container<service-container>`. Otherwise, the main way to actually *use* your node is through a wallet. The QT GUI is not usable because it cannot be served through the browser (which is necessary here), and last we checked, the QT desktop client was incapable of connecting to a remote node over Tor.
Is a wallet vulnerable to hacking if it's always online??
---------------------------------------------------------
@@ -44,7 +44,7 @@ Funds are not stored on the node typically. The node simply serves as a source
Most successful attacks seem to be either fake/doctored software or a social attack (tricking you into installing some malware or giving your seed outright or something like that).
Keep in mind, however, the more value there is out there to steal, the more sophisticated attacks will get automated (bots, crawlers etc). So its not just the risk profile of today, but also tomorrow you have to consider. That's why something like a hardware wallet or dedicated mobile device for key signing is a good idea.
Even if your wallet is plugged into your Embassy, whether your wallet is hot or cold depends on the hardware that stores the keys.
Even if your wallet is plugged into your server, whether your wallet is hot or cold depends on the hardware that stores the keys.
How does Bitcoin Proxy request (and verify) data when that data is needed by some app using it?
-----------------------------------------------------------------------------------------------
@@ -52,24 +52,24 @@ Proxy fetches blocks from your pruned node if it still has them, and fetches the
How do I use Bitcoin Core as a wallet?
--------------------------------------
Bitcoin Core is a full node that also contains wallet functionality. Some will be familiar with Bitcoin-QT, which is a Bitcoin Core GUI that for a long time was the only available wallet. This is currently not compatible with the Embassy.
Bitcoin Core is a full node that also contains wallet functionality. Some will be familiar with Bitcoin-QT, which is a Bitcoin Core GUI that for a long time was the only available wallet. This is currently not compatible with StartOS.
You can use the wallet in Bitcoin Core, however it is for advanced users and is only available in the command line via SSH.
It is helpful to think of the Bitcoin Core service on the Embassy as your own personal Bitcoin Server. This is your own verified source of truth of the Bitcoin ledger, that requires no permission for you to set up and own. The job of your Bitcoin server is to verify that the transactions you want to make and receive are valid.
There are modern wallets that have the ability to use your personal Bitcoin node as a source of truth, and with the advantages of additional security and advanced features. This also follows the Unix mantra of "do one thing and do it well." The recommended way to use Bitcoin with your Embassy’s Bitcoin node is with an external wallet.
It is helpful to think of the Bitcoin Core service on StartOS as your own personal Bitcoin Server. This is your own verified source of truth of the Bitcoin ledger, that requires no permission for you to set up and own. The job of your Bitcoin server is to verify that the transactions you want to make and receive are valid.
There are modern wallets that have the ability to use your personal Bitcoin node as a source of truth, and with the advantages of additional security and advanced features. This also follows the Unix mantra of "do one thing and do it well." The recommended way to use your Bitcoin node is with an external wallet.
The available wallets are listed in the following FAQ.
Which wallets can I use that sync with my Embassy Bitcoin and/or Lightning nodes?
---------------------------------------------------------------------------------
Which wallets can I use that integrate with my Bitcoin and/or Lightning nodes?
------------------------------------------------------------------------------
Please see the :ref:`Bitcoin Service Guides<bitcoin-service>` for all the current options.
I want to use my hardware signer, such as Coldcard or Trezor, with my Embassy. How does this work?
---------------------------------------------------------------------------------------------------
I want to use my hardware signer, such as Coldcard or Trezor, with my Bitcoin node. 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)
Node (on StartOS) <— Wallet (Specter, Sparrow, Electrum) <— Hardware signer (Coldcard, Trezor)
You would use your hardware signer with your wallet, then instruct that wallet to use Embassy as its node.
You would use your hardware signer with your wallet, then instruct that wallet to use your Bitcoin node as its node.
- Nodes are for interacting with the Bitcoin network: enforcing consensus rules, validating and relaying blocks/transactions, and broadcasting transactions.
@@ -77,4 +77,4 @@ You would use your hardware signer with your wallet, then instruct that wallet t
- 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).
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 StartOS).

7
site/source/support/faq/faq-contributing.rst
View File

@@ -10,9 +10,10 @@ Contributing FAQ
We ❤️ contributions!
How can I contribute to embassyOS?
----------------------------------
Please follow the guide `here <https://github.com/Start9Labs/embassy-os/blob/master/CONTRIBUTING.md>`_ and reach out to the `Community Dev <https://matrix.to/#/#community-dev:matrix.start9labs.com>`_ channel on Matrix with any questions.
How can I contribute to StartOS?
--------------------------------
Please follow the guide `here <https://github.com/Start9Labs/start-os/blob/master/CONTRIBUTING.md>`_ and reach out to the `Community Dev <https://matrix.to/#/#community-dev:matrix.start9labs.com>`_ channel on Matrix with any questions.
Do I need to be a professional developer or have coding experience to contribute?
---------------------------------------------------------------------------------

89
site/source/support/faq/faq-embassy.rst
View File

@@ -1,89 +0,0 @@
.. _faq-embassy:
===========
Embassy FAQ
===========
.. contents::
:depth: 2
:local:
Can I run embassyOS on a VPS or VM?
-----------------------------------
Yes! The :ref:`DIY Guide <diy>` will take you through the setup steps.
Is it possible to use embassyOS on my own hardware?
---------------------------------------------------
Yes! The :ref:`DIY Guide <diy>` will take you through the setup steps. This option is great for people who already own the necessary hardware or who live outside the US and want to save on shipping and customs fees.
Additionally, embassyOS is available for you to download or build from source under the Start9 Personal Use `License <https://start9.com/license>`_, for free. The caveat is that you will miss out on the perks that come along with purchasing from us, such as white-glove support, and others, which will grow over time.
Do I plug my Embassy into my computer?
---------------------------------------
No. Your Embassy only needs to be plugged into power and internet, just like your router. You can set it up right by your router and, similar to a router, generally forget about it.
Do I plug in a monitor, keyboard, and mouse?
--------------------------------------------
Typically, no. It is not necessary or recommended to do this as embassyOS runs in "headless" mode - meaning that you will access it from your computer or mobile device. However, we have recently added "Kiosk Mode," which allows the installation (and use) of embassyOS with a monitor/keyboard/mouse. For directions on setting this up, please check out the :ref:`x86_64 DIY Guide <diy-x86>`.
How much storage does Embassy have?
-----------------------------------
Currently, Embassy ships with a 1 or 2TB SSD, but you may use a larger drive if you prefer. We advise against HDDs at this time for perfomance reasons.
Are my Internet requests anonymous and secure?
----------------------------------------------
embassyOS and every service on our Marketplace serve their own Tor Hidden Services with unique Tor addresses. The private keys used to create these addresses are generated on your phone or computer when you first set up Embassy. No one, not even Start9, has any idea what your Tor addresses are, let alone the password(s) you choose to authenticate with them.
Does Start9 have access to my Embassy's encryption keys?
--------------------------------------------------------
No. Your keys are generated on your device using the password you create so we CAN NOT, nor would we like to, see your private keys.
Can multiple Embassies be setup to run redundantly in physically separate locations?
------------------------------------------------------------------------------------
Currently no, but we have plans for a feature that will enable Embassies to provide encrypted, automated backup services for one another.
How does Embassy compare to other Bitcoin nodes or personal servers?
--------------------------------------------------------------------
The cheapest way to run a Bitcoin/Lightning node is to buy a Raspberry Pi (or equivalent), download or compile embassyOS for free, and host everything on Tor. This takes even technical people significant time to accomplish. On the other end of the spectrum is something like Embassy, which "just works". In between is stuff like MyNode, Nodl, RoninDojo, Umbrel, and Raspiblitz, which all require some degree of command line effort and network configuration. The biggest benefit of Embassy is that it is infinitely extensible to all of open-source, self-hosted software. The service listing will expand enormously over time in ways the other platforms may choose not to, or have difficulty implementing.
Would you consider (Umbrel, Nodl, RoninDojo, etc) a competitor to Embassy, or are they different enough to be compatible?
--------------------------------------------------------------------------------------------------------------------------
Other node devices are competitors, and there are distinct trade-offs to each platform, but we are definitely moving toward the same future, which is a win for everyone!
One difference with Start9 is that we began with a plan to create an OS for general-purpose sovereign hosting of server-side software. No other project in the space (that we know of) started this way. There's also no reason you can't use more than one device. As an example, some users prefer Embassy for their data and RoninDojo for their Bitcoin stack.
Some other things that embassyOS offers that others do not:
- Graphical configuration of services (instead of command line)
- System backups (pretty important)
- Encrypted connection over the home network (https)
- Health Checks for quick-glance understanding of the status of your services
- Unique user experiences created by service-packagers, including "Actions" (custom commands at the click of a button!)
From an architectural perspective, embassyOS is a true operating system, giving you the ability to understand and control what is going on. Many other systems are black boxes offering little insight or agency to you. If something goes wrong, you'll have to put in your engineer hat and go command line diving. Lastly, our team is very responsive and helpful. We pride ourselves on providing incredible customer support.
Since it is often requested, we have put together an :ref:`Umbrel comparison guide<umbrel-compare>`
How can I migrate from Umbrel to Embassy and keep my lightning channels intact?
-------------------------------------------------------------------------------
We've created a guide to help you `transform your Umbrel's bitcoin stack into an Embassy <https://community.start9.com/t/howto-migrate-from-umbrel-0-5-x-to-embassy/56>`_.
Alternatively, if you have an Umbrel and an Embassy and they're on the same network, you can just select *Services > Lightning Network Daemon > Actions > Import from Umbrel* in your Embassy's web interface and your LND settings and channels will be automatically migrated.
Can I mine Bitcoin with this?
-----------------------------
You do **not** want to do that.
Does Embassy only work over Tor? No http or VPN?
-------------------------------------------------
Embassy's current primary communication is over Tor. In many cases we use HTTP over Tor (they are not mutually exclusive), you can see this by navigating to the Tor address in a browser and see the “http” in front of it. A VPN is a feature we're exploring as an alternative to Tor to make things faster without meaningfully impacting privacy. You can also connect directly via LAN if you are on the same network as your device.
What if someone gets physical access to my device, can they read the contents? Is it encrypted?
-----------------------------------------------------------------------------------------------
The data is currently encrypted at rest, but not in a way that would prevent a sophisticated attacker from accessing it. This is a step towards better security in the near future. At-rest encryption on servers is a serious challenge, because of the need for remote availability. For example, you may not be at home to enter an encryption password following a power outage, leaving you without access to your server.
Services like Bitwarden, however, do not store plaintext information, so your passwords will not be compromised unless they know your master 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. See this `article <https://community.torproject.org/onion-services/advanced/https/>`_ from the Tor Project for more details.

84
site/source/support/faq/faq-general.rst
View File

@@ -10,110 +10,106 @@ General FAQ
What is Start9 Labs?
--------------------
Start9 Labs is a small, but quickly growing group of builders based in Denver, CO (with a global team) that build Embassy and embassyOS.
Start9 Labs is a small, but quickly growing group of builders based in Denver, CO (with a global team) that build Start9 servers and StartOS.
What is Embassy?
----------------
Embassy is a "shelf-top" personal server running embassyOS software.
What is a Start9 server?
------------------------
A Start9 server is a "shelf-top" personal computer running StartOS as its operating system.
The internet as we know it is organized into questioners, or clients, and answerers, or servers. When you open a mobile email app, say Gmail, the app (client) begins asking questions: "have I received new mail?", "what are my last 50 messages?", "what drafts am I in the midst of writing?", and so on. Your app's questions are sent to and heard by a Google-run server which then provides answers back to the client and are subsequently displayed to the screen.
Embassy is exactly that: your very own "answerer", just like Google's, except managed simply and with ease by and for you alone.
A server is exactly that: your very own "answerer", just like Google's, except managed simply and with ease by and for you alone.
In other words, it is a generalized private personal server capable of running all sorts of self hosted open source software.
When you see your credit card information on your banking app, your messages in your texting app, your passwords in your password management app, all of that information comes from somewhere in the cloud: some server run by some company somewhere on the planet. Who can see the data stored in that server? Who can edit it? It's not always clear, but the increasingly common practice of selling your data to advertisers and the high-profile cyber-security breaches of the last decade suggest a pessimistic outlook.
One thing is for certain though: if you control your server, then you control your data. Your finances, your communications, all of it is actually yours -- and only yours -- with Embassy.
One thing is for certain though: if you control your server, then you control your data. Your finances, your communications, all of it is actually yours -- and only yours.
Why do I care?
--------------
As an example, let's talk about the password manager, Bitwarden. It may help convey the concept of a personal server. Currently, if you sign up with Bitwarden, your passwords are stored on a physical device (aka server) owned and operated by the Bitwarden team. Your phone or laptop sends requests to their server when you want to do anything: create an account, create a new password, retrieve existing passwords, etc. Your passwords are stored on their device, encrypted with your Bitwarden password. They are the custodian of your passwords, similar to getting a safe deposit box at the bank. The bank keeps your valuables in their vault, presumably they don't know what's in the box, and any time you want access to your box, you ask the bank for permission. This is exactly how a hosted Bitwarden experience works, as well as just about everything on the internet.
When you install Bitwarden on your Embassy, by contrast, it's like building your own safe deposit box in a private bunker whose location is only known to you and whose keys only you posses. You create an account with yourself, store your passwords with yourself, etc. You are your own custodian. This same concept can be applied to just about everything on the Internet, without losing the convenience of the custodial model, which is what we are out to accomplish. This may sound cool, or neat, but it is so much more than that. The custodial data model is amongst the greatest threats to human liberty the world has ever seen.
When you install Bitwarden on StartOS, by contrast, it's like building your own safe deposit box in a private bunker whose location is only known to you and whose keys only you posses. You create an account with yourself, store your passwords with yourself, etc. You are your own custodian. This same concept can be applied to just about everything on the Internet, without losing the convenience of the custodial model, which is what we are out to accomplish. This may sound cool, or neat, but it is so much more than that. The custodial data model is amongst the greatest threats to human liberty the world has ever seen.
This `podcast <https://www.youtube.com/watch?v=aylDowaSdzU>`_ may help expound upon why this is important.
.. youtube:: aylDowaSdzU
:width: 100%
How does Embassy work?
How does StartOS work?
----------------------
embassyOS (see next question) is based on Linux and handles all operations of your Embassy device. This core element of the technology stack is what enables you to set up, login, access your Embassy's dashboard, and install services.
StartOS (see next question) is based on Linux and handles all operations on your server. This core element of the technology stack is what enables you to set up, login, access your server's dashboard, and install services.
One of these operations is creating and managing Tor addresses, which are uniquely attributed to each service you download, as well as to the Embassy device itself. You can see your uniquely generated Tor address when you complete the setup process using the Setup App. This address is how you view your Embassy's dashboard, which is actually just a website served up from your Embassy itself! It is authenticated, of course, so only you can access it.
One of these operations is creating and managing Tor addresses, which are uniquely attributed to each service you download, as well as to the server itself. You can see your uniquely generated Tor address when you complete the setup process using the Setup App. This address is how you view your server's dashboard, which is actually just a website hosted by your server itself! It is authenticated, of course, so only you can access it.
You can connect to and manage your Embassy from any mobile device, desktop computer, or laptop computer. This is accomplished right through the browser by visiting your Embassy's private and unique URL.
You can connect to and manage your server from any mobile device, desktop computer, or laptop computer. This is accomplished right through the browser by visiting your server's private and unique URL.
Once on Embassy's web page, you can choose what services to install. Then, each installed service also receives its own private and unique URL, such that you can access it from the browser or any mobile app that supports using it as a backend.
Once on your server's web page (the StartOS dashboard), you can choose what services to install. Then, each installed service also receives its own private and unique URL, such that you can access it from the browser or any mobile app that supports using it as a backend.
The list of services will grow rapidly over the coming months and years, such that many things you currently do using cloud-based third party servers can be just as easily accomplished using your own personal cloud serving your own personal apps and storing your own private data. No trusted third parties at all.
What is embassyOS?
------------------
embassyOS is a new kind of Operating System (OS). It is a built from the ground up to allow anyone to easily run their own "cloud," become independent from Big Tech, and own their own data. embassyOS allows anyone to easily host their own software services.
What is StartOS?
----------------
StartOS is a new kind of Linux Operating System (OS). It is a built from the ground up to allow anyone to easily run their own "cloud," become independent from Big Tech, and own their own data. StartOS allows anyone to easily host their own software services.
embassyOS is custom-built Linux distribution with a suite of software tools which make it easy to:
StartOS is custom-built Linux distribution with a suite of software tools which make it easy to:
* Install, uninstall, and upgrade services from a Marketplace (similar to your phone's app store)
* Manage and run services that YOU own and control
* Upgrade your Embassy software with the latest features and security updates
* Upgrade StartOS with the latest features and security updates
* Backup services, and restore from backups if needed
It includes:
* a custom application management layer, specialized for installing, running, and backing up .s9pk packaged services
* a layer responsible for Embassy specific operations, such as Tor, Backups, and Notifications
* a layer responsible for StartOS specific operations, such as Tor, Backups, and Notifications
* a system of :ref:`Health Checks<health-checks>` for simple monitoring
* an SDK for developers, including an "Actions" API to simplify complex operations for the common user
* and much, much more. Please see the corresponding :ref:`Concepts<embassy-os>` section.
* and much, much more. Please see the corresponding :ref:`Concepts<start-os>` section.
The `.s9pk` extension is Start9's custom package format based on `tar`. It encompasses the necessary components to compress, host, and install a service on a Marketplace registry.
What are embassyOS Services?
----------------------------
What are StartOS Services?
--------------------------
A Service can be any piece of software added to the Marketplace. Unlike "apps," services are (usually) "server-side" software, meaning they are intended to run 24/7/365 and listen for requests from your clients (apps). All services are "self-hosted," meaning that you are in complete control of your data. This means you can run your own "cloud!" Learn more about managing services :ref:`here <managing-services>` and see our currently `Available Services <https://marketplace.start9.com/>`_.
Does the Embassy ship worldwide?
--------------------------------
We ship everywhere that DHL ships. Please consider that in some countries, the VAT and Customs fees are so ridiculous that they cost as much as Embassy itself or more. You may wish to consider buying your hardware locally and building your own device, downloading embassyOS from our github, and `donating <https://donate.start9.com/>`_ to us. Please see the :ref:`DIY<diy>` page for details.
Does Start9 ship worldwide?
---------------------------
We ship everywhere that DHL ships. Please consider that in some countries, the VAT and Customs fees are so ridiculous that they cost as much as the server itself. You may wish to consider buying your hardware locally and building your own device, downloading StartOS from our github, and `donating <https://donate.start9.com/>`_ to us. Please see the :ref:`DIY<diy>` page for details.
Does the Embassy have international electrical plugs?
-----------------------------------------------------
Do you have international electrical plugs?
-------------------------------------------
Power supplies for EU, AU, US, and UK are available.
Is the power supply that comes with Embassy 220v compatible?
------------------------------------------------------------
Yes.
Is the power supply 220v compatible?
------------------------------------
Yes. Start9 server power supplies are rated for 100-240V.
Is the software Open Source?
Does StartOS have a license?
----------------------------
Yes! embassyOS is open source under the `Start9 Personal Use License <https://start9.com/latest/about/license>`_. Some of our other projects are currently open sourced under MIT. You can find these in the Start9 `GitHub repository <https://github.com/Start9Labs>`_.
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.
StartOS 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.
Is there a product warranty?
----------------------------
Yes! The full warranty for a device purchased from us is located on the insert in the box (1 year). Furthermore, Start9 commits, to the best of our ability, to serving Embassy users. We will resolve any issue encountered with our provided hardware or software in a personalized manner. We strive to provide highly available, quality customer service.
Yes! The full warranty for a device purchased from us is located on the insert in the box (1 year). Furthermore, Start9 commits, to the best of our ability, to serving our users. We will resolve any issue encountered with our provided hardware or software in a personalized manner. We strive to provide highly available, quality customer service.
What kind of Internet connection is required to use Embassy?
------------------------------------------------------------
In general, any modern Internet connection is usually fine. We have had reports from users on rural satellite connections with high latency (ping), and low up/download speeds who had issues accessing via Tor. You can check your internet connection at `SpeedTest <https://speedtest.net>`_ to find your ping and speed. If your ping is higher than 200ms and/or your speeds are lower than 5Mbps, you may want to host your Embassy somewhere with a better connection. Please don't hesitate to contact us with any questions.
What kind of Internet connection does a server require?
-------------------------------------------------------
In general, any modern Internet connection is usually fine. We have had reports from users on rural satellite connections with high latency (ping), and low up/download speeds who had issues accessing via Tor. You can check your internet connection at `SpeedTest <https://speedtest.net>`_ to find your ping and speed. If your ping is higher than 200ms and/or your speeds are lower than 5Mbps, you may want to locate your server somewhere with a better connection. Please don't hesitate to contact us with any questions.
I run a business, can I use an Embassy for tasks such as password management and file sharing?
----------------------------------------------------------------------------------------------
Absolutely. 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.
I run a business, can I use StartOS for tasks such as password management and file sharing?
-------------------------------------------------------------------------------------------
Absolutely. A Start9 server 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!
What are you using for a store backend? Do you store my data?
--------------------------------------------------------------
Here is our exact situation currently:
Embassy device sales are processed through Shopify, which we do not like, but it was expedient in the early days, especially for shipping, so we went with it. Aside from a master list of email addresses for those who have explicitly opted in to our mailing list, all customer data is contained within Shopify. We do not duplicate it anywhere. We are asking Shopify to delete our customer data, but they claim it will take upward of 3 months to comply and we of course have no guarantee the data will actually be deleted permanently. This is partly why we exist...as such, we will be moving off of Shopify and onto a self-hosted solution, where Start9 alone controls our customer data for Embassy purchases, which we will delete as a matter of policy following a short grace period after delivery.
Server sales are processed through Shopify, which we do not like, but it was expedient in the early days, especially for shipping, so we went with it. Aside from a master list of email addresses for those who have explicitly opted in to our mailing list, all customer data is contained within Shopify. We do not duplicate it anywhere. We are asking Shopify to delete our customer data, but they claim it will take upward of 3 months to comply and we of course have no guarantee the data will actually be deleted permanently. This is partly why we exist...as such, we will be moving off of Shopify and onto a self-hosted solution, where Start9 alone controls our customer data for purchases, which we will delete as a matter of policy following a short grace period after delivery.
In summary: (1) the shipping data we currently have is stored in Shopify (2) we are asking Shopify to delete all our customer data (3) we will be migrating off of Shopify (4) going forward, we alone will control customer data and will purge it regularly (5) you can always assemble the hardware yourself and just download embassyOS for free.
In summary: (1) the shipping data we currently have is stored in Shopify (2) we are asking Shopify to delete all our customer data (3) we will be migrating off of Shopify (4) going forward, we alone will control customer data and will purge it regularly (5) you can always assemble the hardware yourself and just download StartOS for free.
We are currently working on a better solution.

16
site/source/support/faq/faq-lightning.rst
View File

@@ -29,8 +29,8 @@ How is that fee estimation calculated?
--------------------------------------
The commitment fees are automatically negotiated every few blocks with your peer. They are on chain txs like all channel closes but they are not broadcast until you attempt to close the channel.
What would happen if I shut down an Embassy that is running a Lightning node with open channels?
------------------------------------------------------------------------------------------------
What would happen if I shut down StartOS while it is running a Lightning node with open channels?
-------------------------------------------------------------------------------------------------
It is REALLY IMPORTANT to understand that if Lightning services are shut off for long periods of time (several days or more) 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, and you may choose to only open channels with friends that may be a lot nicer to you if your node is not active.
@@ -38,12 +38,12 @@ Is there a solution to this?
----------------------------
Yes, the concept of a Watchtower was originally conceptualized in the LN whitepaper. A Watchtower is simply a lightning node to which you can give the authority to monitor transactions associated with your open payment channels.
Is it possible to run Core Lightning and LND in parallel on Embassy?
Is it possible to run Core Lightning and LND in parallel on StartOS?
--------------------------------------------------------------------
Yes, you may run both. They will operate in their own environments and allow you to run services that depend on either.
How do I connect my Lightning wallet or mobile app to my Embassy?
-----------------------------------------------------------------
How do I connect my Lightning wallet or mobile app to my Start9 server?
-----------------------------------------------------------------------
Please see the :ref:`Lightning Service Guides<lightning-service>` section for more details.
Are my addresses, channels, and balances all stored in LND or in RTL? Core Lightning or Spark, etc?
@@ -52,17 +52,17 @@ This is all on LND, including on-chain funds, and RTL (or ThunderhHub, Zap, etc)
How do I find my LND seed so I can write it down to backup?
-----------------------------------------------------------
All LND backups are best done via Embassy's backup flow. It is not supported to use a seed as backup; LND does not expose this. Everything crucial is backed up by our backup system so you do not need your seed. The seed is ONLY for the onchain wallet and does not backup your channel state.
All LND backups are best done via StartOS's backup flow. It is not supported to use a seed as backup; LND does not expose this. Everything crucial is backed up by our backup system so you do not need your seed. The seed is ONLY for the onchain wallet and does not backup your channel state.
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.
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.
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 StartOS 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.
Is there a way to use the channel backups made within RTL?
----------------------------------------------------------
The only backup flow we officially support is through Embassy's backup system. This does include the channel backups created automatically by LND, but it must be understood that backups in Lightning are very different than they are on Layer 1 Bitcoin. If you restore from backup all your channels will close, and there is a potential, albeit small, probability for you to lose funds.
The only backup flow we officially support is through StartOS's backup system. This does include the channel backups created automatically by LND, but it must be understood that backups in Lightning are very different than they are on Layer 1 Bitcoin. If you restore from backup all your channels will close, and there is a potential, albeit small, probability for you to lose funds.
When attempting to add new peer, RTL says "server is still in the process of starting," but chain state seems to be fully up to date. What can I do?
-----------------------------------------------------------------------------------------------------------------------------------------------------

8
site/source/support/faq/faq-service-packaging.rst
View File

@@ -8,15 +8,15 @@ Packaging FAQ
:depth: 2
:local:
Do I need programming experience to package a service for embassyOS?
--------------------------------------------------------------------
Do I need programming experience to package a service for StartOS?
------------------------------------------------------------------
It would be helpful, but is not a pre-requisite. Linux, dev-ops, and/or systems administration experience would all be helpful as well. Keep in mind that everyone has to start somewhere, and perhaps your journey to development begins with packaging a service for eOS!
What considerations are there when choosing a service for packaging?
--------------------------------------------------------------------
There are several things you will want to consider. Requirements include:
#. Most importantly, pick a service you are passionate about seeing on embassyOS
#. Most importantly, pick a service you are passionate about seeing on StartOS
#. Make sure it is :ref:`Open Source <open-source>`
#. A service that incorporates a 'self-hosting' option, or is capable of being self-hosted
@@ -34,7 +34,7 @@ Config files can be empty( ``{}`` ), if you do not require config. `File Browse
How can my service access the data directory of another service?
----------------------------------------------------------------
#. Provider service needs to expose datadir to other services on embassy
#. Provider service needs to expose datadir to other services on StartOS
#. Consumer services needs to list the provider service as a dependency AND set a particular config value, stating that it wants data from that particular service
Check out `LND <https://github.com/Start9Labs/lnd-wrapper/blob/master/manifest.yaml>`_ and `RTL <https://github.com/Start9Labs/ride-the-lightning-wrapper/blob/master/manifest.yaml>`_ as an example.

32
site/source/support/faq/faq-services.rst
View File

@@ -10,7 +10,7 @@ Services FAQ
What if I cannot connect to a Service?
--------------------------------------
Please make sure the service is started by viewing it in the Services tab in the Embassy dashboard menu. A green indicator bar should be visible.
Please make sure the service is started by viewing it in the Services tab in the StartOS dashboard menu. A green indicator bar should be visible.
Can it be used as a firewall?
-----------------------------
@@ -18,15 +18,15 @@ Potentially. The PiHole service is on our wishlist.
Will there be a VPN?
--------------------
We are looking into adding Wireguard as a service for VPN access when you are not home. A client-to-client Embassy VPN may also be possible in the future.
We are looking into adding Wireguard as a service for VPN access when you are not home. A client-to-client StartOS VPN may also be possible in the future.
Will there be an email server?
------------------------------
We do hope to add this functionality one day, however it has some technical challenges, and is not currently a high priority. If you would like to tackle this and help us get a self-hosted email server on the Embassy, please reach out in our `Matrix Community Dev Channel <https://matrix.to/#/#community-dev:matrix.start9labs.com>`_, and we will be happy to help in any way that we can.
We do hope to add this functionality one day, however it has some technical challenges, and is not currently a high priority. If you would like to tackle this and help us get a self-hosted email server on StartOS, please reach out in our `Matrix Community Dev Channel <https://matrix.to/#/#community-dev:matrix.start9labs.com>`_, and we will be happy to help in any way that we can.
Can the Embassy run 'X' Service??
Can StartOS run 'X' Service??
---------------------------------
Potentially. Here is a `comprehensive list <https://github.com/awesome-selfhosted/awesome-selfhosted>`_ of self-hosted services, any of which can theoretically be run on embassyOS.
Potentially. Here is a `comprehensive list <https://github.com/awesome-selfhosted/awesome-selfhosted>`_ of self-hosted services, any of which can theoretically be run on StartOS.
To get a general idea of what is required of an app, answer these questions:
1. Is it designed to be self-hosted?
@@ -35,14 +35,14 @@ To get a general idea of what is required of an app, answer these questions:
4. Does it ship with it's own web interface? Or is there a Tor-enabled client app?
5. Is there someone willing to put in the time to package it up?
If all answers are yes, then it can run on embassyOS.
If all answers are yes, then it can run on StartOS.
Packing up a service for the Embassy does not require extensive development skills. If you are interested in doing do, please see our :ref:`Developer Docs <developer-docs>`.
Packing up a service for StartOS does not require extensive development skills. If you are interested in doing do, please see our :ref:`Developer Docs <developer-docs>`.
We are aggressively moving away from service development in favor of a more community driven approach. Meaning you, an app development team, or anyone else on Earth, can bring the Service they want to an Embassy Marketplace. You don't need our permission.
We are aggressively moving away from service development in favor of a more community driven approach. Meaning you, an app development team, or anyone else on Earth, can bring the service they want to a Marketplace registry so anyone can run it on StartOS. You don't need our permission.
Does the Embassy operate as a Tor relay node?
---------------------------------------------
Does StartOS operate as a Tor relay node?
-----------------------------------------
No, currently it does not, but we plan to add that functionality in the near future.
Are files on File Browser encrypted on disk?
@@ -51,11 +51,11 @@ Yes, but not in a way that would prevent a sophisticated attacker.
Can others use my Cups instance? How does that work?
----------------------------------------------------
Cups does not have multiple accounts support. Each person would need their own Embassy. We are considering adding multi-account support to Cups, but it's not a priority at the moment.
Cups does not have multiple accounts support. Each person would need their own Start9 server. We are considering adding multi-account support to Cups, but it's not a priority at the moment.
How can I fix issues with Sphinx?
---------------------------------
If you are on Android, make sure Orbot is setup correctly, and if it is, try to restart it or your device. If you still have issues, *back up your keys,* delete all app data from your phone, uninstall, restart the Sphinx service on your Embassy, then reinstall and import your keys.
If you are on Android, make sure Orbot is setup correctly, and if it is, try to restart it or your device. If you still have issues, *back up your keys,* delete all app data from your phone, uninstall, restart the Sphinx service on your Start9 server, then reinstall and import your keys.
I get an error ("Unlock Wallet Failed") when trying to log in to RTL, what can I do?
------------------------------------------------------------------------------------
@@ -70,7 +70,7 @@ What does it mean when Vaultwarden says "This browser requires HTTPS to use the
---------------------------------------------------------------------------------------------------------------------------------------------------------
You will need to tell your browser to treat .onion URLs as a "secure context". You will need to follow this guide to configure :ref:`Tor on Firefox<tor-firefox>`.
Can the browser extension be used with Bitwarden hosted on the embassy?
Can the browser extension be used with Bitwarden hosted on StartOS?
-----------------------------------------------------------------------
Yes, but only in a tor-enabled browser. Just add your .onion address as the server in the extension. Make sure that http:// is at the beginning, and NOT https://, as this will not work.
@@ -78,9 +78,9 @@ You can use your .local address, but remember that you will only be able to sync
I want to use BTCPayServer on my website, but Tor is the only option, how can visitors access my BTCPay on clearnet?
--------------------------------------------------------------------------------------------------------------------
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/Deployment/ReverseProxyToTor/#reverse-proxy-to-tor/>`_.
As StartOS 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/Deployment/ReverseProxyToTor/#reverse-proxy-to-tor/>`_.
We understand that this can be a frustrating limitation, and adding clearnet support is high on our list of priorities for embassyOS. This will allow a number of services to have better interoperability with the broader Web.
We understand that this can be a frustrating limitation, and adding clearnet support is high on our list of priorities for StartOS. This will allow a number of services to have better interoperability with the broader Web.
I'm having issues connecting to users or rooms in Matrix/Synapse, what can I do?
--------------------------------------------------------------------------------
@@ -94,7 +94,7 @@ If you had to create a custom destkop shortcut, it is likely that this was reset
I don't see an answer to my question regarding a certain service. Is there more documentation?
-----------------------------------------------------------------------------------------------
While we are intent on providing the most friendly experience possible to our customers, ultimately it will be impossible for Start9 to create documentation and tutorials for every service we make available on the Embassy. Each service *should* have its own documentation produced by the service developers themselves, and we will do our best keep track, consolidate, and link to it. Also, much of the reason good tutorials don't exist is simply because no one in the community has taken the time to produce it. If you come across something useful or write something up yourself, please let us know and we will promote it. Otherwise we will do our best to answer questions as they arise and gradually build out tutorials where they are lacking.
While we are intent on providing the most friendly experience possible to our customers, ultimately it will be impossible for Start9 to create documentation and tutorials for every service we make available on StartOS. Each service *should* have its own documentation produced by the service developers themselves, and we will do our best keep track, consolidate, and link to it. Also, much of the reason good tutorials don't exist is simply because no one in the community has taken the time to produce it. If you come across something useful or write something up yourself, please let us know and we will promote it. Otherwise we will do our best to answer questions as they arise and gradually build out tutorials where they are lacking.
Please also check out these :ref:`external support channels <external-support>` for assistance.

87
site/source/support/faq/faq-startos.rst Normal file
View File

@@ -0,0 +1,87 @@
.. _faq-startos:
===========
StartOS FAQ
===========
.. contents::
:depth: 2
:local:
Can I run StartOS on a VPS or VM?
---------------------------------
Yes! The :ref:`DIY Guide <diy>` will take you through the setup steps.
Is it possible to use StartOS on my own hardware?
-------------------------------------------------
Yes! The :ref:`DIY Guide <diy>` will take you through the setup steps. This option is great for people who already own the necessary hardware or who live outside the US and want to save on shipping and customs fees.
Additionally, StartOS is available for you to download or build from source under the Start9 Personal Use `License <https://start9.com/license>`_, for free. The caveat is that you will miss out on the perks that come along with purchasing from us, such as white-glove support, and others, which will grow over time.
Do I plug my Start9 server into my computer?
--------------------------------------------
No. Your Start9 server only needs to be plugged into power and internet, just like your router. You can set it up right by your router and, similar to a router, generally forget about it.
Do I plug in a monitor, keyboard, and mouse?
--------------------------------------------
Typically, no. It is not necessary or recommended to do this as StartOS runs in "headless" mode - meaning that you will access it from your computer or mobile device. However, we have recently added "Kiosk Mode," which allows the installation (and use) of StartOS with a monitor/keyboard/mouse. For directions on setting this up, please check out the :ref:`x86 DIY Guide <diy-x86>`.
How much storage does a Start9 server have?
-------------------------------------------
Currently, Start9 servers ship with a 1 or 2TB SSD, but you may use a larger drive if you prefer. We advise against HDDs at this time for perfomance reasons.
Are my Internet requests anonymous and secure?
----------------------------------------------
StartOS and every service on our Marketplace serve their own Tor Hidden Services with unique Tor addresses. The private keys used to create these addresses are generated on your phone or computer when you first set up StartOS. No one, not even Start9, has any idea what your Tor addresses are, let alone the password(s) you choose to authenticate with them.
Does Start9 have access to my personal Start9 server's encryption keys?
-----------------------------------------------------------------------
No. Your keys are generated on your device using the password you create so we CAN NOT, nor would we like to, see your private keys.
Can multiple Start9 servers be setup to run redundantly in physically separate locations?
-----------------------------------------------------------------------------------------
Currently no, but we have plans for a feature that will enable StartOS to provide encrypted, automated backups across multiple servers.
How does StartOS compare to other Bitcoin nodes or personal servers?
--------------------------------------------------------------------
The cheapest way to run a Bitcoin/Lightning node is to buy a Raspberry Pi (or equivalent), download or compile Bitcoin, LND/CLN, etc, and host everything on Tor. This takes even technical people significant time to accomplish. On the other end of the spectrum is something like StartOS, which "just works". In between is stuff like MyNode, Nodl, RoninDojo, Umbrel, and Raspiblitz, which all require some degree of command line effort and network configuration. The biggest benefit of StartOS is that it is infinitely extensible to all of open-source, self-hosted software. The service listing will expand enormously over time in ways the other platforms may choose not to, or have difficulty implementing.
Would you consider (Umbrel, Nodl, RoninDojo, etc) a competitor to StartOS, or are they different enough to be compatible?
--------------------------------------------------------------------------------------------------------------------------
Other node devices are competitors, and there are distinct trade-offs to each platform, but we are definitely moving toward the same future, which is a win for everyone!
One difference with Start9 is that we began with a plan to create an OS for general-purpose sovereign hosting of server-side software. No other project in the space (that we know of) started this way. There's also no reason you can't use more than one device. As an example, some users prefer StartOS for their data and RoninDojo for their Bitcoin stack.
Some other things that StartOS offers that others do not:
- Graphical configuration of services (instead of command line)
- System backups (pretty important)
- Encrypted connection over the home network (https)
- Health Checks for quick-glance understanding of the status of your services
- Unique user experiences created by service-packagers, including "Actions" (custom commands at the click of a button!)
From an architectural perspective, StartOS is a true operating system, giving you the ability to understand and control what is going on. Many other systems are black boxes offering little insight or agency to you. If something goes wrong, you'll have to put in your engineer hat and go command line diving. Lastly, our team is very responsive and helpful. We pride ourselves on providing incredible customer support.
How can I migrate from Umbrel to StartOS and keep my lightning channels intact?
-------------------------------------------------------------------------------
We've created a guide to help you `transform your Umbrel's bitcoin stack into a Start9 server <https://community.start9.com/t/howto-migrate-from-umbrel-0-5-x-to-embassy/56>`_.
Alternatively, if you have an Umbrel and a Start9 server and they're on the same network, you can just select *Services > Lightning Network Daemon > Actions > Import from Umbrel* in your Start9 server's web interface and your LND settings and channels will be automatically migrated.
Can I mine Bitcoin with this?
-----------------------------
You do **not** want to do that.
Does StartOS only work over Tor? No http or VPN?
-------------------------------------------------
StartOS's current primary communication is over Tor. In many cases we use HTTP over Tor (they are not mutually exclusive), you can see this by navigating to the Tor address in a browser and see the “http” in front of it. A VPN is a feature we're exploring as an alternative to Tor to make things faster without meaningfully impacting privacy. You can also connect directly via LAN if you are on the same network as your device.
What if someone gets physical access to my device, can they read the contents? Is it encrypted?
-----------------------------------------------------------------------------------------------
The data is currently encrypted at rest, but not in a way that would prevent a sophisticated attacker from accessing it. This is a step towards better security in the near future. At-rest encryption on servers is a serious challenge, because of the need for remote availability. For example, you may not be at home to enter an encryption password following a power outage, leaving you without access to your server.
Services like Bitwarden, however, do not store plaintext information, so your passwords will not be compromised unless they know your master 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. See this `article <https://community.torproject.org/onion-services/advanced/https/>`_ from the Tor Project for more details.

38
site/source/support/faq/faq-troubleshooting.rst
View File

@@ -12,24 +12,24 @@ What do I do first?
-------------------
Please check out the :ref:`Initial Setup <initial-setup>` page, and follow the instructions.
How do I know if my Embassy is running?
---------------------------------------
How do I know if my server is running?
--------------------------------------
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. You can hear these sounds on the :ref:`Initial Setup<initial-setup>` page.
My Embassy is really hot! Is this normal?
------------------------------------------
My server is really hot! Is this normal?
-----------------------------------------
On early devices, yes. These cases are actually doing 'double duty' as a heat sync. This means that the metal of the case is actually touching the chips on the circuit board and drawing their heat out and away. This is known as "passive cooling," as no fan (and therefore no noise) is required to cool the system.
You can check the chip temperature of your device under "System -> Metrics".
I'm trying to migrate my old Embassy data, but the device won't boot. What do I do?
------------------------------------------------------------------------------------
I'm trying to migrate my old server data, but the device won't boot. What do I do?
-----------------------------------------------------------------------------------
Remove the external drive and sd card adapter if they are plugged in. Boot the device with just the new (32GB) sd card inserted. After you hear the start-up sounds, you may plug in the external drive and old (128GB) sd card.
I cannot reach embassy.local after hearing the start-up sounds from Embassy. What do I do?
-------------------------------------------------------------------------------------------
* Ensure that you are on the same network as your Embassy. Check that it is not a "Guest" network in your router
* Your browser might try to force https://embassy.local, delete the https:// prefix and try again with just embassy.local or http://embassy.local
I cannot reach start.local after hearing the start-up sounds. What do I do?
----------------------------------------------------------------------------
* Ensure that you are on the same network as your server. Check that it is not a "Guest" network in your router
* Your browser might try to force https://start.local, delete the https:// prefix and try again with just start.local or http://start.local
* Try a different browser, and note that Tor Browser cannot handle .local addresses
* Turn off your VPN if you are using one (you may turn it back on after setup), or "allow LAN connections" if your VPN has such a setting.
* If none of the above work, check your network setup, including your router settings if they are non-standard
@@ -38,7 +38,7 @@ I cannot reach embassy.local after hearing the start-up sounds from Embassy. Wh
Why do I need the Bonjour service (Windows)?
--------------------------------------------
A major use-case of Bonjour is wireless printing over the LAN, but your Windows machine can also use Bonjour to discover and connect with other devices on the :ref:`Local Network<lan>`. In this case your Embassy. If Windows were to add support for reaching ``.local`` addresses, as is done in Linux and Mac, this would no longer be necessary.
A major use-case of Bonjour is wireless printing over the LAN, but your Windows machine can also use Bonjour to discover and connect with other devices on the :ref:`Local Network<lan>`. In this case your Start9 server. If Windows were to add support for reaching ``.local`` addresses, as is done in Linux and Mac, this would no longer be necessary.
Recent updates to Windows may obviate the need for Bonjour, but so far results are mixed.
@@ -48,24 +48,20 @@ This is most likely a transient networking issue that will correct itself in a f
1. On Android/Orbot, the most common solution is to restart your Android device.
2. Access your Embassy over :ref:`LAN <connecting-lan>`, and restart it from the "Embassy" menu. (Restart by removing power if you cannot access via LAN)
2. Access your server over :ref:`LAN <connecting-lan>`, and restart it from the "System" menu. (Restart by removing power if you cannot access via LAN)
3. Restart your router.
Do I need to take any additional security precautions with my device, for example with my router/modem?
-------------------------------------------------------------------------------------------------------
Nothing special is required, however, it is best practice to use good passwords, i.e. for your WiFi and your Embassy. Here's a `comic <https://xkcd.com/936/>`_ explaining how to make strong passwords, simply.
Nothing special is required, however, it is best practice to use good passwords, i.e. for your WiFi and your server. Here's a `comic <https://xkcd.com/936/>`_ explaining how to make strong passwords, simply.
What if I have an unique network issue, for example, with a firewall?
---------------------------------------------------------------------
Embassy is designed to work as simply as possible, for as many as possible, while providing the ability to host in a private manner. If you have an agressive or custom firewall, or other custom network settings, there is a good chance that addtional configuration may be necessary. We will continue to learn about custom networking issues, update our docs with resources, and help in the :ref:`Community Channels <contact>` to the best of our ability.
StartOS is designed to work as simply as possible, for as many as possible, while providing the ability to host in a private manner. If you have an aggressive or custom firewall, or other custom network settings, there is a good chance that addtional configuration may be necessary. We will continue to learn about custom networking issues, update our docs with resources, and help in the :ref:`Community Channels <contact>` to the best of our ability.
Can I use my Embassy from behind a VPN, for example, if my router has a built-in VPN?
-------------------------------------------------------------------------------------
Can I use my server from behind a VPN, for example, if my router has a built-in VPN?
------------------------------------------------------------------------------------
Yes, this is possible, but it adds complexity, which may lead to problems. You will need to understand the setup of your router/VPN and how it supports (or doesn't support) Tor/LAN connections.
If you are having trouble with this, you might consider letting Embassy out "in the clear," since all services are accessible over the Tor network, offering a high level of privacy. Obviously, Start9 cannot support every variation of router and network.
Is it true that my device has some limited functionality in regard to Embassy?
------------------------------------------------------------------------------
The short answer is probably not, and there are often workarounds for the few known limitations. Please see the :ref:`Limitations<limitations>` page for details on your device.
If you are having trouble with this, you might consider letting your server out "in the clear," since all services are accessible over the Tor network, offering a high level of privacy. Obviously, Start9 cannot support every variation of router and network.

4
site/source/support/faq/index.rst
View File

@@ -4,13 +4,13 @@
FAQ
===
Answers to Frequently Asked Questions from Embassy users
Answers to Frequently Asked Questions
.. toctree::
:maxdepth: 2
faq-general
faq-embassy
faq-startos
faq-basic-use
faq-troubleshooting
faq-contributing

169
site/source/support/faq/umbrel-compare.rst
View File

@@ -1,169 +0,0 @@
.. _umbrel-compare:
:orphan:
=================
Umbrel Comparison
=================
This post will attempt to do a deep dive into the features of the Umbrel 0.4.10 and Embassy 0.3.0 personal servers. Many bitcoin and lightning node operators and other privacy conscious individuals use both platforms on a daily basis, so we think this functional comparison will help when choosing which platform to use for your needs.
Definitions
-----------
Each platform will have different terminology, so let's first agree on common terms so the comparisons can be easy to understand.
**Embassy “Service” vs Umbrel “App”**
Each platform has a different name for describing server-side applications. Start9 calls them “services”, Umbrel calls them “apps”. For the remainder of this post, we will refer to them as services, but it means the same thing.
**Embassy Service Marketplace vs Umbrel App Store**
Both platforms publish their services through a web portal that allows the user to download and install the service from directly within the OS. Start9 calls it a “service marketplace” and Umbrel calls it an “app store”. For the remainder of this post, we will refer to it as a marketplace.
Now on to the feature comparisons!
Marketplace
-----------
Both platforms offer a similar experience for discovering and installing services, but beneath the surface there are some important differences.
**Umbrel**
Each version of Umbrel contains a file called registry.json that defines the complete set of possible services and their versions that can be installed on that version of Umbrel. The Umbrel App Store is a graphical interface for examining this file in a visual way, complete with images. When you click “install”, your Umbrel reaches out to dockerhub.io to fetch the docker container for the selected service. In other words, the Umbrel App Store is actually a custom skin for dockerhub.io that exposes a subset of services defined by that version of Umbrel. There are three very important consequences to this architecture:
Dockerhub.io is a single point of failure and de facto dependency of Umbrel. If Dockerhub.io ever goes down or becomes compromised, it will not be possible to reliably install or update services.
**Embassy**
With Embassy, nothing is built-in or pre-installed, not even Bitcoin. This means you can easily run two Embassies: one for Bitcoin services, and another for non-Bitcoin services. Install only the services you want on each device. Packages are entirely modular and self-describing, meaning that you can even install packages to your Embassy that you get from a friend even if that package doesn’t appear on any marketplace.
Moreover, there is no static configuration file that details or limits the set of possible services that can be installed. Installations and updates are done a la carte and are independent of one another. If Start9 releases a new service or updates an existing service, such as an emergency security update for Bitcoin, you can get the new version without needing to update your entire Embassy or any other services.
Finally, anyone can host an alternative or competing marketplace, either on clearnet or over Tor, and users can switch between marketplaces inside the Embassy interface. This means that Start9 does not occupy a central position in the marketplace ecosystem. If Start9 goes down, users can switch to an alternative marketplace and continue to install and update services.
Available Services
------------------
The reason anyone wants a personal server is the same reason anyone wants a personal computer: to do things with it! In other words, services.
**Umbrel**
At the time of this writing, there are 46 services available on Umbrel.
**Embassy**
At the time of this writing, there are 24 services available on Embassy.
Service Contributions
---------------------
There are several services available on both platforms, but even so these platforms are not limited to just what you can find on their respective marketplaces. Both platforms have a developer guide for packaging up your own service from your own repository.
**Umbrel**
Umbrel uses docker containers to package up services, and can be done in any programming language. The only requirement is for the service to serve up a web page, as the regular user is never expected to have cli access on Umbrel.
The docker containers can be tested on a dedicated Umbrel development environment, available for both Linux and macOS, or can be tested directly on an Umbrel. Any dependencies on other services would need to be managed by the service author/developer.
Umbrel uses docker images pushed to Docker Hub to catalog services on the Umbrel marketplace. All services are bundled together in UmbrelOS releases, so once you submit a service to Umbrel, you would need to wait until the next UmbrelOS version release in order to see your service in the Umbrel marketplace.
**Embassy**
Embassy uses the concept of a ‘wrapper’ around a docker container to package custom services and provides detailed documentation on how to package a service for the Embassy using any desired programming language. This wrapper acts as a translation layer such that developers can take advantage of the embassyOS’ various APIs mentioned throughout this writing. Embassy will host the service over Tor and LAN without any additional configuration needed. They also provide a hello-world example to refer to when packaging a custom service.
Services can then be submitted to the Start9 Service Marketplace for review and distribution, or they can be hosted on any alternative marketplace.
Backups
-------
When it comes to digital independence, there is nothing more important than maintaining good backups. If your server is stolen or destroyed, and you don’t have good backups, you can lose everything. Again, Embassy and Umbrel are entirely different when it comes to backups.
**Umbrel**
With Umbrel, you do not have to worry about backing up LND, including your lightning payment channels. Umbrel automatically creates encrypted backups of your LND node on their own server. You can, and should, download these backups regularly to ensure you have the latest backup in case something goes wrong. You can also download a .backup file of your channels and save it locally.
Umbrel does not offer a means of backing up other services. If you want to back up your Bitcoin node, or your data, messages, or passwords from other services, you will need to SSH into your Umbrel, then use the command line to manually export data from each service using an over-the-air protocol such as FTP or SMB. You will need to research each service to determine exactly what data should be exported and in what format, and you will need to perform your own encryption if you want the backups to be encrypted. So except for LND, which is backed up on Umbrel’s server, it is not practical to backup your other services.
**Embassy**
With Embassy, creating a complete encrypted backup of your entire system is a matter of clicking “Create Backup” in the GUI and selecting a target destination. The destination can either be a physical hard drive or a shared network folder, basically any device that is connected to the same Local Area Network as your Embassy. Backups are encrypted using your Embassy master password.
You can restore from backup directly from the GUI by clicking “Restore from Backup”, selecting the drive where the backup exists, and then selecting the services you want to restore.
Service Configuration
---------------------
Services, like client apps on your phone or computer, usually have settings. Unlike these apps, however, services often (1) do not have a user interface or (2) rely on certain settings for their boot process; meaning, by the time you might see a settings menu, it’s too late. So instead of a settings menus, services usually rely on configuration files that instruct the service not only how to initialize, but also how to function once initialization is complete. In Bitcoin, for example, configuration is accomplished by editing the bitcoin.conf file, then starting or restarting the node. Configuration files are often massive, require using the command line, and are generally not validated, meaning it is easy to make a mistake, which can cause the entire service to crash or stop functioning properly. Furthermore, config files rarely self-describe the set of possible options or values for each option, leaving users wondering what is even available to them.
**Umbrel**
Umbrel provides sane defaults for service configurations. If the user wishes to change the defaults, they must use SSH, the command line, and a command line text editor such as vim or nano to modify whatever configuration file the service uses, such as bitcoin.conf. It is left up to the user to research the possible configuration options and modify the files without making a mistake.
**Embassy**
Embassy also provides sane defaults for service configurations. If the user wishes to change the defaults, they can do so through the Embassy GUI using a graphical form, complete with descriptions, toggles, dropdowns, and standard inputs, all fully validated to ensure no mistakes are made.
Health Checks
-------------
Perhaps the most important (and difficult) task of a systems administrator is to constantly monitor the health and availability of their services. And it is not always obvious what constitutes health. For example, if your Bitcoin node is running, does that mean it is healthy? The answer is no. A running Bitcoin node is useless if it hasn’t fully started up or its P2P interface is unreachable. What about if your node is not fully synced. Is a partially synced Bitcoin node considered healthy? The answer is that it depends on who is asking. From LNDs perspective, a partially synced Bitcoin node is not healthy, since until Bitcoin is fully synced, LND cannot do its job. As a systems administrator, monitoring the health of your services from a variety of perspectives and use cases is a serious challenge.
**Umbrel**
There is no health check system for services in Umbrel. It is up to the user to know what constitutes health for each service and to manually inspect logs and use SSH and the command line to determine if their services are healthy.
**Embassy**
In Embassy, package developers define what constitutes health for a given service and write scripts to test for it. Embassy performs these health checks on a continuous basis, presenting results to the user inside the GUI. Users can tell at a glance if Bitcoin is running smoothly, or if LND is satisfied with the state of Bitcoin’s health. In the event that a health check fails, Embassy can issue a notification, informing the user of the failure along with a report for how the issue was resolved or whether resolution requires further action.
Actions
-------
In the course of running your own services, you will often enter commands into the command line to execute certain actions or scripts, such as resyncing the Bitcoin blockchain, or resetting a password. Being aware of these commands and knowing how and when to use them gives you more control over your services and are sometimes necessary for resolving issues. Here, again, we see big differences between Embassy and Umbrel.
**Umbrel**
Umbrel does not make actions available to users. If you want to execute a command, you must use SSH and the command line. From there, you can run any command you want, but there is no guidance or protection from the operating system.
**Embassy**
In Embassy, the Actions interface allows users to execute common commands inside the GUI. Actions are developer defined and can be any command, including commands that take user input. Commands that have not been formally converted into Actions may be executed using SSH and the command line.
LAN SSL
-------
When communicating with your personal server in a browser context, it is important to ensure that your communication is private and secure. For this reason, Both Embassy and Umbrel serve their user interfaces over Tor as V3 Hidden Service. This enables you to access your server from anywhere in the world, right from the browser, by visiting a unique .onion URL. But Tor is slow and clunky. As such, both platforms also serve their user interfaces over the Local Area Network (LAN), such that you can access your server in a more performant manner while connected to the same LAN by visiting a unique .local URL.
**Umbrel**
Umbrel uses an unencrypted http connection for communicating over the LAN. If your LAN is secure, this is not an issue. But anyone with access to your LAN, including guests who have your WiFi password or who plug in via Ethernet, would trivially be able to sniff traffic.
**Embassy**
Embassy acts as its own Certificate Authority (CA), such that it can use an encrypted https connection for communicating over the LAN. This requires a bit of setup, namely downloading your Embassy’s SSL CA certificate and trusting it in both your device and your device’s browser. It takes a few minutes to set up, but once complete, you can be sure that no one can sniff your traffic, even if they have access to your LAN.
Properties
----------
Often, you will want to inspect the data of one of your services or query it for a specific value. We will refer to these values as Properties. For example, what is the sync progress of your Bitcoin node? Or what are the gRPC credentials of your LND node? Or what is the default username and password of your photo sharing service?
**Umbrel**
With Bitcoin and Lightning, Umbrel provides a beautiful GUI that displays properties in real time, such as sync progress and current block height. Umbrel does not, however, have a generalized interface for displaying arbitrary properties for any service. These properties must be obtained by using SSH and the command line.
**Embassy**
In Embassy, what qualifies as a property that is worth displaying is determined by the package developer. Embassy offers a generalized interface for presenting properties to the user, such that they can view, copy, or QR scan important values inside the GUI. Properties that are not made available by the package developer can be obtained by using SSH and the command line.
Notifications
-------------
When it comes to running your own server, knowing what happened and when can be very important for debugging, or for resolving an issue as soon as it arises.
**Umbrel**
Umbrel does not have a notification system. If something goes wrong with your Umbrel or any of its services, you will have to figure it out from unexpected behavior.
**Embassy**
If something important happens (i.e. a service crashes, or a health check fails, or backup completes), Embassy will issue a notification. These notifications are retained and displayed chronologically inside the Notifications section of your Embassy. Some notifications also contain metadata. For example, a notification about a completed backup will contain a detailed report of that backup.

4
site/source/support/index.rst
View File

@@ -28,7 +28,7 @@ View frequently asked questions, troubleshoot common issues, or contact support.
:class: large-5
:anchor: View
Answers to Frequently Asked Questions from Embassy users
Answers to Frequently Asked Questions from StartOS users
.. topic-box::
:title: Contact
@@ -46,7 +46,7 @@ View frequently asked questions, troubleshoot common issues, or contact support.
:class: large-5
:anchor: Get help
Get help for third party apps that connect to your Embassy services
Get help for third party apps that connect to your StartOS services
.. raw:: html