Documentation Overview

  1. Operation documentation
    1. UBOS Linux installation
      1. Run UBOS on a PC (64bit)
      2. Run UBOS from a boot stick on a PC (64bit)
      3. Run UBOS in a VirtualBox virtual machine (64bit)
      4. Run UBOS with Docker
      5. Run UBOS on an Amazon Web Services EC2 virtual server
      6. Run UBOS on Raspberry Pi 5
      7. Run UBOS on ESPRESSObin
      8. Run UBOS in a Linux container on a PC (64bit)
      9. Run UBOS in an AArch64 Linux container
    2. Setting up your first Site and App
    3. Setting up networking and DNS
    4. How to create a website secured by SSL/TLS
    5. How to set up a website as a Tor hidden service
    6. Managing Sites and Apps
    7. Backup and restore
    8. Upgrading and keeping your Device current
    9. The UBOS Staff
    10. App-specific notes
      1. Reliably send e-mail via Amazon Web Services’ Simple E-mail Service: amazonses
      2. Static website hosting with rsync-based upload: docroot
      3. Notes on Mastodon
      4. Notes on Nextcloud
      5. Notes on Redirect
      6. Notes on Wordpress
    11. Device-specific Notes
      1. ESPRESSObin
      2. Raspberry Pi
    12. Advanced management
      1. Enabling non-standard package repositories
      2. Migrating from one App to another
      3. Pinning resources
    13. FAQ, HOWTOs and Troubleshooting
      1. “Package not found error” when installing a new App or Accessory
      2. A UBOS container comes up degraded
      3. Booting UBOS on a PC starts out fine, but then the screen goes blank
      4. Can I use UBOS without purchasing a domain name?
      5. Cannot access MySQL database. File missing: /etc/mysql/root-defaults-ubos.cnf
      6. Cannot boot UBOS from boot stick on a PC
      7. Cannot connect to the public internet from a UBOS container
      8. Cannot create a temporary backup; the backup directory is not empty
      9. Failed to create file /sys/devices/system/cpu/microcode/reload
      10. How are the various UBOS images different from each other?
      11. How can I install more than one web App on the same Device?
      12. How do I report a bug?
      13. How do I set up WiFi?
      14. How to enable non-standard Package Repositories
      15. How to get help
      16. How to log into your UBOS Device
      17. How to modify the configuration of your Site
      18. How to report a bug or issue
      19. How to use Pagekite to reach your UBOS Device behind a firewall
      20. How to use SSH
      21. I need a Package that isn’t in UBOS
      22. I need root
      23. I own a domain name, and I’d like to use it for my UBOS Device. How do I do that?
      24. I want to move from one device to another, or from/to the cloud to/from a device
      25. I want to run ssh on a non-standard port
      26. I’m running out of disk space, what now?
      27. Installing a new Package or updating fails with a message about “invalid or corrupted package” or “key is disabled”
      28. Installing a new Package or upgrading fails with a message about “unknown trust”
      29. Is it safe to have my Site accessible from the public web?
      30. My non-English keyboard layout is all screwed up
      31. My SD card is much larger than the UBOS image. How do I use the rest of the space?
      32. Nothing happens when UBOS is supposed to be booting
      33. Problems with “IPv6 Packet Filtering Framework”
      34. UBOS is in a “degraded” state
      35. ubos-admin status reports “Systemd unit … has failed”
      36. Verify your downloaded UBOS image
      37. What is the default “root” password?
      38. What text editor can I use on UBOS?
      39. Why did you derive UBOS Linux from Arch Linux, and what is the relationship between UBOS Linux and Arch?
      40. Why does UBOS ask for a domain name when installing a new Site?
      41. Why is it called UBOS?
      42. Writing a disk image to a USB stick or SD card
        1. Writing an image to a USB stick or SD card on Linux
        2. Writing an image to a USB stick or SD card on macOS
        3. Writing an image to a USB stick or SD card on Windows
    14. Command reference
  2. Developer documentation
    1. Developer setup
      1. Developing using Docker (all Intel platforms)
      2. Developing using a systemd-nspawn container (Linux host only)
      3. Developing using Arch Linux on VirtualBox x86_64 with a systemd-nspawn container
      4. Developing using Arch Linux using UTM on Apple Silicon with a systemd-nspawn container
      5. Developing using Arch Linux using Parallels on Apple Silicon with a systemd-nspawn container
    2. Developer tutorials for standalone UBOS Gears apps (not UBOS Mesh)
      1. Build and run your first UBOS Gears App
      2. How to package UBOS Standalone Apps built with a variety of languages
        1. Hello World
        2. Glad-I-Was-Here (PHP, MySQL)
        3. An Accessory for Glad-I-Was-Here (PHP, MySQL)
        4. Glad-I-Was-Here (PHP, Postgresql)
        5. Glad-I-Was-Here (Java, MySQL)
        6. Glad-I-Was-Here (Python, MySQL)
    3. UBOS Gears Reference
      1. UBOS Manifest
        1. Structure of the UBOS Manifest
        2. Info section
        3. Roles section
        4. Customization points section
        5. Appinfo section
        6. Accessoryinfo section
        7. Variables available at deploy or undeploy
        8. Functions that may be applied to variables
        9. Creating random values
        10. Scripts in UBOS Manifests
      2. Site JSON
      3. A complex deployment example
      4. UBOS Networking
      5. Allocating and opening up non-default ports
      6. Logging
      7. UBOS state
      8. UBOS Backup format
      9. Format of the App Status JSON
      10. Testing standalone Apps with “webapptest”
      11. Understanding ubos-admin
        1. Command: ubos-admin backup
        2. Command: ubos-admin backupinfo
        3. Command: ubos-admin createsite
        4. Command: ubos-admin deploy
        5. Command: ubos-admin hostid
        6. Command: ubos-admin init-staff
        7. Command: ubos-admin list-data-transfer-protocols
        8. Command: ubos-admin listnetconfigs
        9. Command: ubos-admin listsites
        10. Command: ubos-admin read-configuration-from-staff
        11. Command: ubos-admin restore
        12. Command: ubos-admin setnetconfig
        13. Command: ubos-admin setup-shepherd
        14. Command: ubos-admin showappconfig
        15. Command: ubos-admin shownetconfig
        16. Command: ubos-admin showsite
        17. Command: ubos-admin status
        18. Command: ubos-admin undeploy
        19. Command: ubos-admin update
        20. Command: ubos-admin write-configuration-to-staff
    4. Release channels and UBOS release process
    5. Miscellaneous
      1. Potentially useful infrastructure for standalone Apps
        1. The UBOS rsync server
      2. Middleware-specific notes
        1. Node.js notes
        2. SMTP notes
      3. Setting up an Arch Linux system
        1. Prepare a PC for installing Arch Linux
        2. Prepare a VirtualBox virtual machine to develop for UBOS using Arch Linux
        3. Continuing the Arch Linux installation on a PC or virtual machine
        4. Finishing the Arch development installation by adding UBOS tools
    6. Developer FAQ
      1. Doesn’t apt / dpkg / yum / pacman etc. does what UBOS Gears does already?
      2. Doesn’t puppet / chef / ansible etc. does what UBOS Gears does already?
      3. Doesn’t Docker do what UBOS Gears does already?
      4. How to profile the UBOS Personal Data Mesh web application
      5. Is it possible to run the other UBOS components on an operating system other than UBOS Linux?
      6. How to create a UBOS development VM for VirtualBox
      7. How to create a UBOS development VM for UTM on Apple computers
      8. How to create a UBOS development VM for Parallels Desktop on Apple Silicon

Run UBOS in a Linux container on a PC (64bit)

/docs/operation/installation/x86_container/

If you already run Linux on a 64bit PC, you can run UBOS in a Linux container with systemd-nspawn. This allows you to try out UBOS without having to do a bare metal installation. The only requirement is that your Linux machine runs systemd in a reasonably recent version.

To do so:

  1. Download a UBOS container image from the Depot. Images for x86_64 containers are at depot.ubosfiles.net/green/x86_64/images. Look for a file named ubos_green_x86_64-container_LATEST.tar.xz.

  2. Optionally, you may now verify that your image downloaded correctly by following Verify your downloaded UBOS image.

  3. Uncompress and unpack the downloaded file into a suitable directory by executing:

    % mkdir ubos
    % sudo tar -x -J -C ubos -f ubos_green_x86_64-container_LATEST.tar.xz
    

    on the Linux command line.

    If you are running btrfs as your filesystem, you may want to create a subvolume and unpack into that subvolume instead, as systemd-nspawn is btrfs-aware and that can speed up things and save some disk space. However, use of btrfs is optional.

  4. Run both IPv4 and IPv6 based iptables on your host, otherwise UBOS cannot set up its own firewall and the UBOS container will boot into a degraded state. If you aren’t already doing this, on the host:

    % [[ -e /etc/iptables/iptables.rules ]] || sudo cp /etc/iptables/empty.rules /etc/iptables/iptables.rules
    % [[ -e /etc/iptables/ip6tables.rules ]] || sudo cp /etc/iptables/empty.rules /etc/iptables/ip6tables.rules
    % sudo systemctl enable iptables ip6tables
    % sudo systemctl start iptables ip6tables
    

    This will not actually perform any firewall functionality (the ruleset is empty), but it will allow the UBOS container to set up its own firewall.

  5. Boot the container. systemd-nspawn has a wide variety of options, in particular for how to set up networking. A private network, as we do it here, is one simple option, but you may want to choose a different option, depending on your needs:

    % sudo systemd-nspawn --boot --network-veth --machine ubos --directory ubos
    
  6. When the boot process is finished, log in as user root (for password, see I need root).

  7. Now: wait. UBOS needs to generate a few cryptographic keys before it is ready to use and initialize a few other things on the first boot. That might take 5 or 10 minutes on slower platforms. To determine whether UBOS ready, execute:

    % systemctl is-system-running
    

    The container takes entropy from the host computer, so make sure the host Linux system provides enough. Depending your Linux distro, you may be able to generate more by typing on the keyboard, moving the mouse, generating hard drive activity etc. You can also run:

    % sudo systemctl start haveged
    

    on your host (not container).

  8. Your container should automatically acquire an IP address. You can check with:

    % ip addr
    

    Make sure you are connected to the internet before attempting to proceed. If you have difficulties reaching the internet from your container, consult Cannot connect to the public internet from a UBOS container.

  9. Update UBOS to the latest and greatest:

    % sudo ubos-admin update
    
  10. You are now ready for Setting up your first Site and App. Note that with the private networking setup described on this page, you will only be able to access Apps installed in your UBOS container from the host computer. If you like to access them from anywhere else, you either need to give your container a non-private IP address, or port forward from the host to the container.

  11. To shut down your container, either:

    • hit ^] three times, or
    • in a separate shell, execute sudo machinectl poweroff ubos