diff --git a/source/contributing/services/config.rst b/source/contributing/services/config.rst index b82949d..d00dced 100644 --- a/source/contributing/services/config.rst +++ b/source/contributing/services/config.rst @@ -17,9 +17,9 @@ The outcome of this step is two files: :ref:`config_rules.yaml ` -These files contain a detailed mapping of configuration options with acceptable values, defaults and relational rule-sets. +These files contain a detailed mapping of configuration options with acceptable values, defaults, and relational rule-sets. -For example, if the user chooses config option A, then config option B must be between 5 and 10. This enables a simple GUI configuration experience, complete with validations and protections, for users. They do not have to worry about the consequences of a wrong value in a ``.conf`` file. +For example, if the user chooses config option A, then config option B must be between 5 and 10. This enables a simple GUI configuration experience, complete with validations and protections, for users. They do not have to worry about the consequences of a wrong value in a ``.conf`` file. .. _config_spec: @@ -84,7 +84,7 @@ The following section contains implementation specifications for the ``config_sp :ref:`pointer ` - In the examples for each value spec type below, ``Option`` means the key is optional. Otherwise, the key is required. -- Descriptions are optional but recommended +- Descriptions are optional, but recommended - Name corresponds to the name of the config field - Find a complete example :ref:`here ` - Change warning text displays when the value is altered @@ -152,8 +152,8 @@ ValueSpec Type: List ^^^^ -The list type describes an array of values. The values must consist of the same subtype, which can be any of the ValueSpec types available in the EmbassyOS config specification. -Lists of any type do not contain the default for each item in list. The list *itself* can be have a default. If no default is provided, ``null`` will be the assumed value. +The list type describes an array of values. The values must consist of the same subtype, which can be any of the ValueSpec types available in the EmbassyOS config specification. +Lists of any type do not contain the default for each item in list. The list *itself* can have a default. If no default is provided, ``null`` will be the assumed value. Range is loosely based off mathematical range syntax, with infinity replaced with ``*``: @@ -171,7 +171,7 @@ eg: ValueSpec Type: -.. code:: +.. code:: type: list name: String @@ -237,7 +237,7 @@ Example: Object Type ^^^^^^^^^^^ -A nested representation of a ConfigSpec. The object type takes the same structure under the ``spec`` key as a ConfigSpec: a key indicates the field name, and the value denotes the ValueSpec type for that field. +A nested representation of a ConfigSpec. The object type takes the same structure under the ``spec`` key as a ConfigSpec: a key indicates the field name, and the value denotes the ValueSpec type for that field. There is no default option for the object type. Rather, the option ``null-by-default`` should be used to indicate the default as ``null``. If null by default is true, nullable must be true. If null by default is false, nullable could be either. @@ -379,7 +379,7 @@ ValueSpec Type: target: AppPointerSpecVariants | SystemPointerSpecVariants index: Option (dependent on target being AppPointerSpecVariants) - AppPointerSpecVariants = LanAddress | TorAddress | TorKey | Config + AppPointerSpecVariants = LanAddress | TorAddress | TorKey | Config SystemPointerSpecVariants = HostIp Example: @@ -403,7 +403,7 @@ This type describes a necessary dependency. Multiple variants can be expressed t For example, the Bitcoin Proxy service is united with an instance of Bitcoin. Three variants are defined: internal, external, and a quick connect. In this case, internal refers to the Bitcoin Core instance running on EmbassyOS, and defines the RPC credentials necessary for connecting; external refers to a Bitcoin Core node running on a different device, and defines the RPC credentials necessary for connecting; quick connect refers to yet another method of connecting to a Bitcoin Core node, optimized for convenience. -Default is required and corresponds to one of the variants. +Default is required and corresponds to one of the variants. ``Tag`` is the key that will be rendered on the UI element. @@ -508,7 +508,7 @@ Example: Config Rules ============ -This file defines the configuration rules, or the rule-set that defines dependencies between config variables. +This file defines the configuration rules, or the rule-set that defines dependencies between config variables. A rule is a boolean expression that we demand to be true. It is not true if the expression fails the rule parser. @@ -519,22 +519,22 @@ Rules are composed of two main concepts: * Variables - accessor into a configuration * Terms - either a variable or type literal (ie. a boolean term is a boolean variable, a boolean expression, or a comparison operation between numbers or strings) -Variables can be booleans, numbers, or strings, and have a different syntax depending on the type. These type annotations check your config rules against your config spec and throw an error if invalid. +Variables can be booleans, numbers, or strings, and have a different syntax depending on the type. These type annotations check your config rules against your config spec and throw an error if invalid. - ``?`` - Casts to boolean value. If the value is not a boolean, this notes whether or not the value is null. -- ``#`` - Treat the value as a number. If it is not a number, the value will be parsed as NaN. String numbers are not currently supported. -- ``'`` - Cast the value into a string. Applies to any value except for an object or a list. +- ``#`` - Treat the value as a number. If it is not a number, the value will be parsed as NaN. String numbers are not currently supported. +- ``'`` - Cast the value into a string. Applies to any value except for an object or a list. - ``!`` - Equals not. If application does not satisfy a rule, a set of suggestions should be provided. These suggestions are in the form of the operation to preform: - - ``Set`` - set the value + - ``Set`` - set the value - ``Push`` - add to the value (such as to a list) - ``Delete`` - delete the value -.. code:: typescript +.. code:: typescript enum SuggestionVariant = Set | Delete | Push @@ -589,7 +589,7 @@ Push Examples: to: 'users.[first(item => ''item.name = "c-lightning")].allowed-calls' value: "getnetworkinfo" -Full example from `c-lightning manifest `_: +Full example from `c-lightning manifest `_: .. code:: yaml @@ -611,4 +611,4 @@ Full example from `c-lightning manifest ` \ No newline at end of file +:raw-html:`
` diff --git a/source/contributing/services/makefile.rst b/source/contributing/services/makefile.rst index c2df0ec..16c38f6 100644 --- a/source/contributing/services/makefile.rst +++ b/source/contributing/services/makefile.rst @@ -5,7 +5,7 @@ Service Makefile **************** .. note:: - + *This file is optional* A Makefile serves as a convenience for outlining the build. This helps streamline additional developer contributions to the project. Please reference the GNU `documentation `_ for implementation details. @@ -15,9 +15,9 @@ An alternative to using ``make`` is to use the `nix ` \ No newline at end of file +:raw-html:`
` diff --git a/source/contributing/services/overview.rst b/source/contributing/services/overview.rst index b79b954..978b1d8 100644 --- a/source/contributing/services/overview.rst +++ b/source/contributing/services/overview.rst @@ -4,7 +4,7 @@ Service Package Overview ************************ -There are several main components that comprise a service package for EmbassyOS. This overview will introduce them and following sections will dive into technical specifics. +There are several main components that comprise a service package for EmbassyOS. This overview will introduce them and following sections will dive into technical specifics. First, let's get your system setup with the necessary software dependencies. @@ -36,15 +36,15 @@ Package Components Image ----- -Each service boils down to a Docker image. We're not going to dive into Docker specifics in this guide, since there exists tons of `resources `_ for developing with this containerization tool. +Each service boils down to a Docker image. We're not going to dive into Docker specifics in this guide, since there exists tons of `resources `_ for developing with this containerization tool. -Because the service ultimately runs on a Raspberry Pi, the created Docker image should be a snapshot of a arm based linux environment. The service image is then mounted to the EmbassyOS image during installation. This path is defined in the :ref:`manifest ` configuration file. +Because the service ultimately runs on a Raspberry Pi, the created Docker image should be a snapshot of an arm based linux environment. The service image is then mounted to the EmbassyOS image during installation. This path is defined in the :ref:`manifest ` configuration file. -The image is immutable, meaning that when the service is updated, the image is replaced with a completely new image containing the updated features. +The image is immutable, meaning that when the service is updated, the image is replaced with a completely new image containing the updated features. Volume ------ -Each service application gets a volume allocated to it by EmbassyOS. All service application data is stored in this directory and is persisted across updates. +Each service application gets a volume allocated to it by EmbassyOS. All service application data is stored in this directory and is persisted across updates. The volume directory (for seeding data into the volume) is typically: ``/root/volumes/``. @@ -54,7 +54,7 @@ The volume directory (for seeding data into the volume) is typically: ``/root/vo Dependencies ------------ -When it comes to running your own server, managing dependencies is perhaps the most difficult part. The term "dependency hell" emerged from this sentiment. Even the best developers have lost significant amounts of time trying to find, correct, or clarify documentation for dependencies or dependency configuration. Individuals who manage their own servers have specific technical skills and are willing to devote the time and effort necessary to maintain them. Companies have entire departments dedicated to this feat. +When it comes to running your own server, managing dependencies is perhaps the most difficult part. The term "dependency hell" emerged from this sentiment. Even the best developers have lost significant amounts of time trying to find, correct, or clarify documentation for dependencies or dependency configuration. Individuals who manage their own servers have specific technical skills and are willing to devote the time and effort necessary to maintain them. Companies have entire departments dedicated to this feat. Some other personal server products aimed at non-technical individuals tackle this problem by simply hard coding dependencies. Since EmbassyOS is a platform for running all open-source, self-hosted software, it is not possible to hard code every possible service, service dependency, and service dependency configuration forever. Instead, Start9 built a new, unprecedented operating system that touts a generalized, intuitive approach to dependency management and service configuration. EmbassyOS enables users to easily and selectively install, uninstall, and update any service they want without getting stuck in dependency hell. @@ -75,7 +75,7 @@ This file describes the service and it's requirements. It is used to: Each time a service is updated, the manifest should be updated to include the new version, release notes, and any pertinent updates to the install, uninstall, or restoration flows. All this information is displayed in the marketplace listing, and the optionally denoted alerts will be displayed when appropriate to provide the user with more information about the particularities of the service. -For instance, `LND displays alerts `_ around restoration since data will be overwritten. +For instance, `LND displays alerts `_ around restoration since data will be overwritten. There is nothing you need to do as a developer to enable the service to run over Tor. This is *completely* handled by EmbassyOS - a Tor address will be automatically generated and an Nginx server configured (if a client application) when the service is installed. Just define which version of Tor your service needs in this manifest file! @@ -100,4 +100,4 @@ For reference, the `Hello world ` \ No newline at end of file +:raw-html:`
` diff --git a/source/misc-guides/tor-firefox/android.rst b/source/misc-guides/tor-firefox/android.rst index b95dd13..c496831 100644 --- a/source/misc-guides/tor-firefox/android.rst +++ b/source/misc-guides/tor-firefox/android.rst @@ -9,7 +9,7 @@ Setting up Firefox with Tor on Android Once Tor is setup on your system, you can proceed to setup Firefox: -#. Download `Firefox Beta `_ from the Play Store, or Fennec for F-Droid. +#. Download `Firefox Beta `_ from the Play Store, or `Fennec `_ from F-Droid. #. Next, download a `Proxy Auto Config` file that will use Orbot to resolve `.onion` URLs. We have one hosted `here `_. @@ -43,6 +43,4 @@ Once Tor is setup on your system, you can proceed to setup Firefox: :width: 50% :alt: Firefox whitelist onions screenshot -#. Restart Firefox, and you’re all set! - -You should now be able to navigate to `.onion` URLs in Firefox. This means you can bookmark Cups Messenger, and use your Bitwarden Tor address in the `Bitwarden Password Manager `_ native application. \ No newline at end of file +#. Restart Firefox, and you’re all set! You should now be able to navigate to `.onion` URLs in Firefox. This means you can bookmark Cups Messenger, and use your Bitwarden Tor address in the `Bitwarden Password Manager `_ native application. \ No newline at end of file diff --git a/source/misc-guides/tor-os/android.rst b/source/misc-guides/tor-os/android.rst index 5665d8c..45bfa74 100644 --- a/source/misc-guides/tor-os/android.rst +++ b/source/misc-guides/tor-os/android.rst @@ -4,7 +4,7 @@ Running Tor on Android ********************** -#. First, install the Tor proxy service to your system. To do so, open the Play Store and download `Orbot `_. +#. First, install the Tor proxy service to your system. To do so, download Orbot from the `Play Store `_ , or from `F-Droid `_ . Once you have done so, launch Orbot. #. Once you have done so, launch Orbot. @@ -43,27 +43,27 @@ Orbot's VPN mode allows certain applications to utilize it's Tor service. To set ``Settings > Network & Internet > Advanced > Private DNS > Off`` - .. figure:: /_static/images/tor/private_dns_off.png - :width: 50% - :alt: Private DNS off - - Toggle Private DNS to "off" +.. figure:: /_static/images/tor/private_dns_off.png + :width: 50% + :alt: Private DNS off + + Toggle Private DNS to "off" #. Next, launch Orbot and toggle VPN Mode on while on the main screen: - .. figure:: /_static/images/tor/orbot_vpn.png - :width: 50% - :alt: Orbot vpn mode - - Toggle VPN Mode to "on" +.. figure:: /_static/images/tor/orbot_vpn.png + :width: 50% + :alt: Orbot vpn mode -#. Under `Tor-Enabled Apps`, select the gear to add applications that need to be proxied through VPN mode to utilize Tor. + Toggle VPN Mode to "on" - .. figure:: /_static/images/tor/orbot_apps.png - :width: 50% - :alt: Orbot apps - -Examples of native applications that need this feature are: +Under `Tor-Enabled Apps`, select the gear to add applications that need to be proxied through VPN mode to utilize Tor. + +.. figure:: /_static/images/tor/orbot_apps.png + :width: 50% + :alt: Orbot apps + +Examples of applications that need this feature are: - Bitwarden - Zap diff --git a/source/support/concepts.rst b/source/support/concepts.rst index a7e7b3b..cf68345 100644 --- a/source/support/concepts.rst +++ b/source/support/concepts.rst @@ -1,11 +1,53 @@ .. _concepts: -******** + Concepts ******** Depending on your background, the Embassy platform may deal with some unfamiliar concepts. While it is not strictly *necessary* for you to understand these concepts to use your Embassy, we know many of you would like to. +.. _embassy: + +Embassy +======= + +What is the Embassy? +==================== + +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. + +The Embassy 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 an Embassy. + +How does the Embassy work? +========================== + +The Embassy runs on the Raspberry Pi 4B hardware with a Cortex-a72 CPU, 4GB of RAM, and has 2.4ghz and 5.0ghz IEEE 802.11AC wireless capabilities and a BLE internal speaker for audio feedback of system operations. It also features a high endurance MicroSD card, on which the operating system software is installed. + +EmbassyOS is a stripped down version of Raspbian Buster Lite 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 download 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. + +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. + +Once on Embassy's web page, you can choose what services to install to the Embassy. 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, 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. + + +In depth +-------- + :ref:`tor` + + :ref:`embassyos` + + :ref:`connecting` + .. _embassyos: EmbassyOS @@ -21,7 +63,7 @@ EmbassyOS refers to a custom Linux distribution along with a suite of software t EmbassyOS is a forked branch of the Buster Lite version of Raspberry Pi OS. Start9 Labs augmented this base operating system to include: -* a custom application management layer specialized for installing, running, and backing up .s9pk packaged services +* 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 The .s9pk extension is Start9 Labs' custom package format based on tar. It encompasses the necessary components to compress, host, and install a service on the marketplace. @@ -34,11 +76,11 @@ Open Source The Internet itself was built on free and publicly available code, with the values of collaboration, peer review, communication, and openness built into its very foundation. This decentralized model evolved into the open source movement, which uses these values to discover new ways to solve problems across boundaries and industries. -Open source software centered around the concept of user freedoms: freedom to see, modify, and redistribute the code to make it work for the user in whatever way they needed. It does not necessarily mean free to use. It means that the software will be better, cheaper, and more flexible if it is freely accessible, openly modifiable, and shared. +Open source software centered around the concept of user freedoms: freedom to see, modify, and redistribute the code to make it work for the user in whatever way they needed. It does not necessarily mean free to use. It means that the software will be better, cheaper, and more flexible if it is freely accessible, openly modifiable, and shared. -If anyone can inspect, modify, and distribute the code, bugs are more rapidly resolved, security vulnerabilities are more quickly audited and exposed. Community driven development efforts enable diverse collaboration which increases project reliability and longevity. +If anyone can inspect, modify, and distribute the code, bugs are more rapidly resolved, security vulnerabilities are more quickly audited and exposed. Community driven development efforts enable diverse collaboration which increases project reliability and longevity. -Distinct from open source software is propriety, or closed source, software. Closed source software is strictly moderated, cannot legally be altered, copied, or distributed, and is paid for to be used as intended without modification. Only the code owners have the right to access the code. +Distinct from open source software is proprietary, or closed source, software. Closed source software is strictly moderated, cannot legally be altered, copied, or distributed, and is paid for to be used as intended without modification. Only the code owners have the right to access the code. As a company founded on the principles of freedom, every service we support is open source. We believe in contributing to the future of this vibrant and passionate ecosystem. @@ -48,7 +90,7 @@ As a company founded on the principles of freedom, every service we support is o LAN === -A Local Area Network (LAN) is a computer network that interconnects computers within a limited area such as a residence, school, laboratory, university campus or office building. +A Local Area Network (LAN) is a computer network that interconnects computers within a limited area such as a residence, school, laboratory, university campus, or office building. Devices on a LAN are private and protected, such that only devices connected to the same Ethernet or WiFi network can see or communicate with them. @@ -62,13 +104,13 @@ Your Embassy hosts itself on the LAN and is reachable by visiting its *.local* U SSL === -Visiting websites on the Tor network is slow. We wanted to provide a better option to access the Embassy at home. That’s why we created an address for the Embassy that can be accessed on your Local Area Network. +Visiting websites on the Tor network is slow. We wanted to provide a better option to access the Embassy at home. That’s why we created an address for the Embassy that can be accessed on your Local Area Network. -By default, this `.local` address is served like a regular website, over HTTP. Browser's makes it noticeable visiting a site over HTTP in the URL bar - it could be red, show an unlocked lock, or warn the connection is not secure. +By default, this `.local` address is served like a regular website, over HTTP. Browsers make it noticeable when visiting a site over HTTP in the URL bar - it could be red, show an unlocked lock, or warn that the connection is not secure. -SSL certificates are what enable websites to move from HTTP to HTTPS, which increases security and makes browsers happy. Using the Secure Sockets Layer protocol, HTTPS enabled websites use certificates to establish authenticated and encrypted links between networked computers. It’s the standard technology for keeping an internet connection secure and safeguarding any sensitive data that is being sent between two devices, preventing third parties from reading and modifying any personal information transferred. They also verify ownership of a website. +SSL certificates are what enable websites to move from HTTP to HTTPS, which increases security and makes browsers happy. Using the Secure Sockets Layer protocol, HTTPS enabled websites use certificates to establish authenticated and encrypted links between networked computers. It’s the standard technology for keeping an internet connection secure and safeguarding any sensitive data that is being sent between two devices, preventing third parties from reading and modifying any personal information transferred. They also verify ownership of a website. -Valid SSL certificates are typically issued and obtained from Certificate Authorities. These trusted third parties generate and distribute certificates, signing them with their trusted private key, which allows the clients who use them to verify its authenticity. Websites obtain a certificate from a CA then load it on to their website’s hosting service or server, allowing the website to load over HTTPS and have all traffic to and from the website be encrypted and secure. +Valid SSL certificates are typically issued and obtained from Certificate Authorities. These trusted third parties generate and distribute certificates, signing them with their trusted private key, which allows the clients who use them to verify their authenticity. Websites obtain a certificate from a CA then load it onto their website’s hosting service or server, allowing the website to load over HTTPS and have all traffic to and from the website be encrypted and secure. We decided to have the Embassy act as a Certificate Authority. It creates a self-signed certificate, which means that the private key used to sign the digital certificate is the Embassy’s own private key instead of a third party’s. @@ -89,3 +131,12 @@ If a malicious third party were to intercept a request, they would see a garbled When you use Tor to communicate with services running on the Embassy, all the traffic is onion routed and encrypted, and there are no Tor exit nodes involved - it's totally private with no configuration needed. Furthermore, every service on the Embassy has a different Tor address, including the device itself. This is for privacy reasons - should one Tor address be exposed, the others will not be compromised. Tor addresses are actually ed25519 keys, which means they also provide all the benefits of cryptographically secure private/public keys. + +.. _node: + +Bitcoin Full Node +================= + +The Embassy runs a Bitcoin Full Node. When most people say "full node" what they mean (or should mean) is "fully validating node", meaning that the node is capable of enforcing the consensus rules of Bitcoin by accepting, validating, and relaying every transaction and block produced by the network. Fully validating nodes are necessary for Bitcoin to exist and function properly and are what protect the network from attackers attempting to bypass the consensus rules. A fully validating node (aka full node) does not need to store the entire blockchain to accomplish this. A node that stores the entire blockchain is called a "full archival node". It is the same as a full node, except that it stores every single valid transaction and block ever produced by the network. There are not many reasons why an individual would want to run a full archival node. Most of the benefits of node operatorship are encompassed by a basic full node described above. Full archival nodes have the added benefit of enabling a block explorer. For instace, if you were interested in looking up the history of a particular address or viewing the details of a transaction, neither of which were your own. If an address or transaction is your own, you can view those details using a pruned node. + +All that said, it will soon be possible to run a full archival node with he embassy, should you determine you want block explorer functionality. This will require plugging in an external hard drive to the embassy and changing a setting in the app, and also a resycnhing of the blockchain from genesis. \ No newline at end of file diff --git a/source/support/faq.rst b/source/support/faq.rst index e0a8932..c07cdf6 100644 --- a/source/support/faq.rst +++ b/source/support/faq.rst @@ -4,104 +4,126 @@ FAQ *** +======= +General +======= + +What is Start9Labs? +------------------- +Start9Labs is a company based in Denver, CO that builds the Embassy and EmbassyOS. + What is the Embassy? -==================== +-------------------- +The Embassy is a "shelf-top" computer built using a `Raspberry Pi `_ for hardware and running EmbassyOS software. Learn more :ref:`here `. -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. +What is EmbassyOS? +------------------ +EmbassyOS is a new kind of Operating System (OS). It is built from the ground up to allow anyone to easily run thier own 'cloud,' remove their dependence on Big Tech, and own their own data. EmbassyOS allows anyone to easily self-host their own software services. It handles all operations of the device, including managing the Service Marketplace, Services, Backups, Updates, data, and much more. Learn more :ref:`here `. -The Embassy is exactly that: your very own "answerer", just like Google's, except managed simply and with ease by and for you alone. +What are EmbassyOS Services? +---------------------------- +A Service can be any piece of software added to the Marketplace. 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 :ref:`here ` and see our currently :ref:`Available Services `. -In other words, it is a generalized private personal server capable of running all sorts of self hosted open source software. +Does the Embassy ship worldwide? +-------------------------------- +Yes. -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. +Does the Embassy have international electrical plugs? +----------------------------------------------------- +Power supplies for EU, AU, US, and UK are available. -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 an Embassy. +=========== +Basic Usage +=========== +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. -How does the Embassy work? -========================== - -The Embassy runs on the Raspberry Pi 4B hardware with a Cortex-a72 CPU, 4GB of RAM, and has 2.4ghz and 5.0ghz IEEE 802.11AC wireless capabilities and a BLE internal speaker for audio feedback of system operations. It also features a high endurance MicroSD card, on which the operating system software is installed. - -EmbassyOS is a stripped down version of Raspbian Buster Lite 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 download 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. - -In depth --------- - :ref:`tor` - - :ref:`embassyos` - - :ref:`connecting` - - -I can't connect to my Embassy. -============================== - -If the Embassy is connected to a WiFi network, ensure your phone / computer is connected to the same network. - -If the Embassy is connected via ethernet or to a router, ensure your phone / computer is connected to the same network as the router. - -Ensure that your server has been running long enough for the startup chime noise to sound. - - -Do I plug the Embassy into my computer? -======================================= - -The Embassy does not plug into any other device. It is a just a small computer without a screen designed for constant uptime, aka a server. 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. - -In other words, the interface and admin dashboard for your Embassy is simply a web page/application served up by the Embassy itself into the browser. It's radical, but also very simple. It does not require any technical expertise. - -Once on Embassy's web page, you can choose what services to install to the Embassy. 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, 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. - - -Are my Internet requests anonymous and secure? -============================================== - -EmbassyOS and every service on the Embassy are served on 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 the 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. - -There is also the option to communicate with your Embassy using standard :ref:`ssl` encryption and a uniquely generated `.local` address. This method is faster than Tor, but can only be used on your home network. - - -I cannot connect to a service. -============================== - -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. - +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? -============================= - -Yes, but there is currently no way to synchronize them. Each Embassy will be isolated from the others. In the future, we plan to enable a local mesh network so you enable features storing backup data across devices. - -Is the software open source? -============================ - -Yes! `EmbassyOS `_ is open sourced under the `Start9 Personal Use License `_. - -Some of our other projects are currently open sourced under MIT. You can find these in the Start9 Labs GitHub `repository `_. +----------------------------- +Yes, but there is currently no way to synchronize or federate them. We are working on ways to make this possible in the future. +Is the software Open Source? +---------------------------- +Yes! EmbassyOS is open sourced under the `Start9 Personal Use License `_. Some of our other projects are currently open sourced under MIT. You can find these in the Start9 Labs `GitHub repository `_. Is there a product warranty? -============================ +---------------------------- +Yes! Start9 commits, to the best of our ability, to serving each beta Embassy product released until the wild. We will resolve any issue encountered with our provided hardware or software in a personalized matter. We strive to provide highly available, quality customer service. -Yes. Start9 commits to serving each beta Embassy product released until the wild. We commit, to the best of our ability, to resolve any issue encountered with our provided hardware or software in a personalized matter until resolved. - -Do not hesitate to :ref:`contact`. We strive to also provide quality and available customer service upfront. +The fastest way to get support is via our `Telegram `_ or `Matrix `_ channels. You can also `email us `_. Please do not hesitate to reach out! +============================= +Embassy (Device, OS, and DIY) +============================= Can I run EmbassyOS on a VPS or VM? -=================================== - +----------------------------------- No, and we do not advise this. It is designed to be used on a RaspberryPi. - -Is it possible to DIY the EmbassyOS on my own hardware? -======================================================= - +Is it possible to use the EmbassyOS on my own hardware? +------------------------------------------------------- Yes! You can follow the diy guide :ref:`here `. 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 to build from `source `_ under the `Start9 Personal Use License `_. If you have the time and energy, it will be possible to download and compile EmbassyOS yourself, for free, with the caveat that your "Embassy" will not have a product key generated by us. This means you will miss out on the perks that come along with purchasing from us, which will grow over time. \ No newline at end of file +Additionally, EmbassyOS is available to build from source under the Start9 Personal Use License. If you have the time and energy, it is possible to download and compile EmbassyOS yourself, for free, with the caveat that your “Embassy” will not have a product key generated by us. This means you will miss out on the perks that come along with purchasing from us, which will grow over time. + +Do I plug the Embassy into my computer? +--------------------------------------- +No. The Embassy only needs to be plugged into power and internet, just like your router. You can set it up right by your router and forget about it. + +Are my Internet requests anonymous and secure? +---------------------------------------------- +EmbassyOS and every service on the Embassy 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 the 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. + +Can I mine Bitcoin with this? +----------------------------- +No, you can not. + +========================= +Setup and Troubleshooting +========================= + +What do I do first? +------------------- +Simply plug the device into power and internet, typically from your home internet router. That's it! After this, get the :ref:`Setup App `, and follow the instructions. + +How do I know if my Embassy is running? +--------------------------------------- +After plugging into power and internet, you will hear 2 distinct sounds: first, a “bep” ‐ indicating the device is powering on, and second, a “chime” ‐ indicating the device is ready for setup. + +What if I can't connect to my Embassy? +-------------------------------------- +Please ensure your phone / computer is connected to the same wired or wireless network as your Embassy. Be careful that you are not on a seperate or "guest" network. + +======== +Services +======== + +My Embassy is set up, now what? +------------------------------- +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. + +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. + +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 approximately a week depending on your internet connection. You can continue to use the Embassy normally in the meantime. + +Does the Embassy run a full archival Bitcoin node? +-------------------------------------------------- +The Embassy runs a full node, but does not run a full *archival* node, it's pruned. This means it does not store the entire Blockchain. As it syncs, it discards blocks and transactions it does not need. +It is fully validating and verifying consensus all the way from Genesis. Really, the only reason to store the entire Blockchain is if you want to run a block explorer. Learn more :ref:`here `. + +I want to understand in depth how a Service works and it's available configuration options. Where can I go to learn more? +-------------------------------------------------------------------------------------------------------------------------- +Depending on the app, the config options can be quite involved. Bitcoin Core, for example, has an enormous amount of complex options, almost none of which are useful to a normal user doing normal things. We chose some very sane defaults that should work for normal use cases. Here is an example config from the Bitcoin `GitHub `. +By reading the descriptions in the link above, as well as doing some extra searching on your favorite search engine, you can begin to discover all the crazy ways in which someone can customize their Bitcoin node. Here is another list of `possible options `. +We translated much of (but not all of) the tons of options into a clean and easy-to-use GUI with toggles, dropdowns, inputs, etc, which is what you're seeing in your config screen. If you notice the little "?" icons on the left of each option, clicking them will provide a brief description as to what the option does. Also, our config GUI restricts the possible values you can enter such that you don't accidentally crash Bitcoin. That said, be very careful about just randomly changing things, lest your node starts to behave strangely. + diff --git a/source/user-manual/managing-services/backups.rst b/source/user-manual/managing-services/backups.rst index 93efa86..fe80073 100644 --- a/source/user-manual/managing-services/backups.rst +++ b/source/user-manual/managing-services/backups.rst @@ -2,7 +2,7 @@ Backups ******* -Creating frequent service backups is critical. If anything happens to your Embassy, these backups are you only path to recovering your data. +Creating frequent service backups is critical. If anything happens to your Embassy, these backups are your only path to recovering your data. .. warning:: Backups are encrypted using your Embassy master password. If you forget your password, you lose your backups. @@ -75,7 +75,7 @@ To begin the backup restore process: Restore backup sub-menu options -6. Note the warning that restoring will wipe current data. +6. Note the warning that restoring will wipe current data. .. figure:: /_static/images/backup_warning.png :width: 90% @@ -93,7 +93,7 @@ To begin the backup restore process: 8. "Restoring Backup..." will appear on the service sub menu while the restoration is in process. -.. note:: +.. note:: The service might be momentarily unreachable as it starts back up. This is expected behavior. .. figure:: /_static/images/restoring_backup.png @@ -102,4 +102,4 @@ To begin the backup restore process: Restoring backup view -9. A notification will emit when the backup restoration has successfully completed. \ No newline at end of file +9. A notification will emit when the backup restoration has successfully completed. diff --git a/source/user-manual/managing-services/index.rst b/source/user-manual/managing-services/index.rst index 3227cf3..db27f1b 100644 --- a/source/user-manual/managing-services/index.rst +++ b/source/user-manual/managing-services/index.rst @@ -1,3 +1,5 @@ +.. _managing-services: + ***************** Managing Services *****************