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

Static website hosting with rsync-based upload: docroot

/docs/operation/apps/docroot/

docroot is a simple but quite useful web App for static file hosting. It is useful if:

  • You manually edit all HTML files of your website, and your Site does not need to run any kind of server-side scripts.

  • You use a static website generator such as Jekyll, Sphinx or Hugo.

  • You can run PHP scripts simply by uploading them, but there is no server-side infrastructure (like a database) for them. However, they can access whatever local files have been uploaded.

For example, the UBOS website at ubos.net runs docroot at the root of the Site, as all of its content is statically generated.

Here is how to use docroot:

  1. On your computer (not the UBOS Device), pick, or create an SSH key pair that will be used to securely upload your content to your to-be-created Site. This can be the same key pair that you use with your UBOS Staff, or a different key pair. For more info about SSH and how to create an SSH key pair, see How to use SSH.

  2. You create a Site at which to run docroot, using ubos-admin createsite on your UBOS Device. Specify docroot for the App, and any Context Path you wish. ubos-admin createsite will then ask you for the filename of a public key. Enter the path to that file (usually called id_rsa.pub).

  3. After ubos-admin createsite is complete, you can now securely upload data to your new static Site, using rsync over ssh, which is the most efficient and secure method we could think of.

  4. You need only one more piece of information, which is the AppConfigId of the deployment of docroot that you just created. (This is necessary so UBOS knows which one you are talking about, in case you have more than one installation of docroot on the same Device.) You determine it by executing on your UBOS Device:

    % ubos-admin listsites --detail
    

Look for the name of the Site you just created, and the AppConfiguration that runs docroot. It will also show you the AppConfigId (a long hexadecimal number starting with a).

To upload a file, or an entire directory hierarchy of files with your default SSH keypair, use this command:

% rsync -rtlvH --delete-after --delay-updates --safe-links -e ssh <FROM> docroot@<HOST>:<APPCONFIGID>/

where <FROM>> is the local file or directory to upload, <HOST> is the name of the UBOS device to upload to, and <APPCONFIGID> the AppConfigId you just determined. Note that the destination path in this command is not the usual path to the file on the remote Device, but the AppConfigId (plus potentially a local path from there): docroot will figure out the absolute path.

If you want to use a non-default SSH keypair, you need to add which to the command, so the command becomes:

% rsync -rtlvH --delete-after --delay-updates --safe-links -e 'ssh -i <PRIVKEY>' <FROM> docroot@<HOST>:<APPCONFIGID>/

where <PRIVKEY> is the name of the file that contains the private key.

Admittedly, this command is a handful, so let’s unpack this:

  • rsync: we use the rsync command for uploading, as it is smart and can intelligently skip everything you uploaded before, by just transferring data that is new or has changed since the last upload. This is particularly useful for the many static websites where only little content changes from upload to upload.

  • -rtlvH: tell rsync to recursively upload an entire directory hierarchy, and things like that.

  • --delete-after: tell rsync to delete files that were previously uploaded but don’t exist locally on your computer any more.

  • --delay-updates: useful for long uploads; tell rsync to do the actual update of the website in one swoop at the end of the upload, instead of incrementally as files arrive one by one.

  • --safe-links: in case you are using symlinks, keep those links intact during the upload as long as they are safe.

  • -e ssh: tell rsync to transfer data over ssh. This encrypts all uploaded data, and uses SSH access control so only you can upload to your Site, because only you have access to your SSH private key. This uses your default SSH private key.

  • -e 'ssh -i <PRIVKEY>: instead of using the default SSH private key, use the private key contained in file <PRIVKEY>.

If you execute this command regularly, you may want to create an alias or script for it on your local computer.

As soon as the rsync command is complete, when you visit the URL at which you installed docroot, your content should be displayed in your web browser.