You are not reading the latest stable version of this documentation. If you want up-to-date information, please have a look at master.

EmbassyOS Version 0.3.0

WHEN will the new version be released?

We are as eager to share this major OS overhaul with you as you are to use it. At this time we are in the testing phase. We will update with an ETA as soon as we can.

I have an Embassy already, what do I need to do?

You have 2 options:

1 - Do nothing. Your Embassy will continue to work as it has, however there will likely be no further updates to the 0.2.x series.

2 - Upgrade by adding the required hardware and then install the new version. v0.3.0 will be a free software upgrade to all existing users.

I want to buy an Embassy, what do I need to do?

Currently we are selling the v0.2.x Embassy. These are shipped immediately and can be upgraded when v0.3.0 is available. We are also selling upgrade kits, which contain all the required hardware for v0.3.0. These will be shipped when the update is complete and will contain a pre-flashed SD card with EmbassyOS v0.3.0. The software update is free.

I want to build an Embassy myself, what do I need to do?

You’ll simply need to gather the required hardware, then wait until the release of v0.3.0, at which time you can purchase the OS, or build from source yourself. New build documentation is forthcoming.

I would like to purchase my own hardware. What factors do I need to consider?

1 - Please check the DIY guide for the necessary Raspberry Pi hardware. * (Skip this step if you already have an Embassy) *

2 - The most important piece of additional hardware is the external drive. It MUST have a USB 3.x connection (3.0, 3.1, etc are fine). You may use a HDD, an SSD, or an M.2 SSD / NVME. HDDs are cheaper, and the storage capacities can be much higher, however this is at a big performance sacrifice. SSDs are significantly faster (all services and user data will be stored on your external drive), and more generally more reliable than an HDD. This is what we strongly recommend and sell with our official upgrade kits. An M.2 SSD is simply an SSD with a smaller form factor. An NVME SSD is even more performant than an SSD, however that performance will not be accessible due to the USB bottleneck that the data must traverse to the Pi. Drives will range in price radically depending on what you choose.

If you are unsure what drive type is best for you, get an external SSD with a USB 3.0 connection, such as a Samsung T5. These are around $130USD for 1TB and around $240 for 2TB.

3 - For the SD card, any type will work, and 16GB is recommended. A larger card will not offer any benefit. These are $5-10USD. EmbassyOS will be stored on this card.

What size drive do I need?

This will depend on how you want to use your Embassy. We recommend a minimum of 1TB if you intend to run a pruned Bitcoin node, or no Bitcoin node at all, and a 2TB minimum if you intend to run a full archival node, which will add a lot more functionality.

If you intend to run your own “cloud”, then consider the amount of data you are storing. If you have lots of video files, for example, you may start filling up the disk fairly quickly. Any service you are currently using should have a simple way for you to view your data usage. Make sure to leave plenty of room for expansion.

Finally, remember that you can always expand to a larger drive in the future. EOS will also be adding additional advanced storage features in the near future.

I want to add an HDD later, in addition to my SSD, what are the performance consequences of doing this?

At this time, we recommend against this as the Raspberry Pi cannot deliver enough power. We will be revisiting in future, but a powered usb hub would be a minimum requirement for this setup.

Can I use an internal SSD with a USB 3 enclosure? I’ve heard these may have issues?

Yes, you may, and our original upgrade kits come with this style of drive. We have addressed the known issues in software, and in the rare event of hardware failure, we are here to help.

Does my external drive need its own power supply?

You may use powered disk drives if you prefer, but if only connecting one SSD, it is not necessary.

Can I re-use the SD Card from my Embassy for the new version?

ONLY if you have no data that you want to transfer. If you have existing files, Lightning channels, etc, then you will need to migrate to the new drive first. Keep in mind that this SD card is major overkill for newer versions of EmbassyOS, which will only require a 16GB SD card. This is because all service and user data will be stored on external drives going forward. You can use the original 128GB card for other purposes, sell it, etc.