Testing new embassyOS packages without a physical Embassy (xpost how-to)

Development
1

If you want to start developing packages for embassyOS (eOS), you’ll need a running copy of eOS to deploy and test your packages. eOS can be installed in minutes on many pieces of hardware, but if you don’t have a spare laptop or Raspberry Pi laying around you may want to install eOS on a virtual machine (VM) instead.

This tutorial will cover:

  1. Installing eOS inside a virt-manager VM
  2. Accessing your eOS instance remotely
  3. Creating and sideloading a new package (S9PK)

Installing eOS on a VM

  1. Download and install virt-manager
  2. Download the embassyOS ISO from Github (v0.3.3 or later)
  3. Open virt-manager
  4. Click “create a new virtual machine”
    image
  5. Choose “Local install media” and click Forward
    image
    image498×534 22.7 KB
  6. Click Browse and choose the ISO that you downloaded
  7. Uncheck “Automatically detect”, and choose Ubuntu 22.04 LTS for your OS. Other versions of Ubuntu will probably work, as well as Generic Linux. Click Forward.
    image
    image497×534 23.3 KB
  8. On the next two pages, choose the resources you would like to allocate.

Minimum OS Requirements

  • Single vCPU Core 2Ghz
  • 4GB RAM
  • 64GB Storage (32GB will also work if you’re just doing package development)

Recommended OS Requirements

If you intend to run Bitcoin or store any meaningful amount of data, you will need

  • Quad-Core CPU 2.5Ghz+
  • 8GB+ RAM
  • 1TB+ Storage

image

image

  1. Give the machine a meaningful name and click Finish
    image
    image496×534 25.9 KB
  2. The VM will open up. Select install embassyOS with your keyboard and hit ENTER
    image
    image709×690 17.7 KB
  3. After a few seconds, a browser window will appear inside the VM. Click the disk (the only disk that will exist is the one you created for the VM) under Select Disk, and then click Install embassyOS.
    image
    You will get a warning that you’re about to erase the disk - that’s fine, there’s nothing on it.
  4. You’ll get an Install Success popup. Click Reboot.
  5. After the reboot, the browser in the VM will show the setup page. If you’re installing for package development, click Start Fresh.
    image
    image1068×897 39.4 KB
  6. Select your only storage drive on the next screen.
  7. Choose a password and click “Finish”.
  8. Success! embassyOS is now installed on your VM. It runs inside a browser window!
    Click to login. (You’ll be prompted for your password.)
    image
    image1063×891 218 KB

Problems during install

If you happen to cancel out of the install, it won’t boot the installer again until you do the following:

  1. Right click the VM and go to Open
  2. Click the light bulb :bulb: to configure the VM
  3. Go to IDE CDROM 1
  4. Under Source Path, click Browse
  5. Under final, select eos-0.3.x-xxxxxxxx_amd64.iso, and click “Choose Volume”
  6. Click Apply
  7. Go to Boot Options
  8. Enable IDE CDROM 1 and position it above IDE Disk 1
  9. Click Apply

Accessing your eOS instance remotely

So far, you have been accessing your eOS instance in “Kiosk mode”, meaning you’ve been interacting with eOS directly in the VM. However, eOS is designed to be predominantly accessed via a remote browser. Consequently, the easiest way to test S9PKs is to sideload them onto your eOS instance via your host’s browser. This next section will cover connecting to your eOS instance remotely. You can connect over TOR or over LAN, depending on your preference.

Accessing your eOS instance over TOR

No setup required, but your connection may be slow.

  1. Download and install the TOR browser on your host machine.
  2. Your eOS instance already has a TOR address. To find it, open your VM, click System in the sidebar, and then click About under Insights. On the About page, find the TOR address.
  3. Next, you’ll need to copy that TOR address and paste it in your host’s TOR browser.

Copying and pasting between VM and host will not work by default. To accomplish this, you could set up virt-manager to share your host’s clipboard. However, this process takes several steps and is highly dependent on your host machine’s configuration, so I won’t be covering it in this tutorial.

A faster option is to use CL1P.NET. CL1P.NET is a website that acts like a clipboard; see link for instructions.
(NOTE: CLIP.NET should never be used for private or sensitive info, and should never be used to copy the TOR address of an eOS instance that contains private data. However, if this eOS instance is ONLY for package testing and contains nothing personal, then it’s a fine option.)

Accessing your eOS instance over LAN

Several additional steps are required, but your connection speed will be as fast as possible.

  1. Open your VM and log into eOS
  2. Open a new tab in your VM’s browser. Navigate to localhost/public/eos/local.crt
    Your .crt file should show up in the browser, and should look something like this:
    image
    This is the local connection certificate that you will be adding to your host to create a trusted connection. Normally you’d
  3. First, you’ll need to copy the entire contents of the .crt file and paste it in a new file on your host.

Copying and pasting between VM and host will not work by default. To accomplish this, you could set up virt-manager to share your host’s clipboard. However, this process takes several steps and is highly dependent on your host machine’s configuration, so I won’t be covering it in this tutorial.

A faster option is to use CL1P.NET. CL1P.NET is a website that acts like a clipboard; see link for instructions.
(NOTE: CLIP.NET should never be used for private or sensitive info, and should never be used to copy the TOR address of an eOS instance that contains private data. However, if this eOS instance is ONLY for package testing and contains nothing personal, then it’s a fine option.)

  1. Create a new file on your host, name it local.crt, paste the content, and save it.
  2. Now that local.crt is on your host, follow these instructions to add the certificate to your host’s browser.
  3. Once your certificate has been trusted, open your VM and click System in the sidebar, and then click About under Insights. On the About page, find the LAN address. It should look something like https://embassy-abc-def.local/
  4. Open a browser on your host and navigate to that LAN address. You should be able to log in to eOS via this remote browser just as you have been logging in via the VM. This is the browser you’ll use to sideload S9PKs.

Packaging services (creating S9PKs) and testing them

Now that you can access eOS in a remote browser, it’s time to make a package.

  1. To begin package development, follow this guide.
  2. Once you’ve created an S9PK that you’d like to test, you’ll need to log into your eOS instance in your host’s browser, and click Sideload Service under Manage.
  3. Next, upload the .S9PK by dragging and dropping or clicking browse, and click “Upload & Install”.
  4. After a few minutes, your S9PK should finish installing, and should be displayed on the services page:
    image
    From here, you can start, stop, and uninstall your new service at will.
2 Likes