Documentation Overview

  1. Operation documentation
    1. 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 on an Amazon Web Services EC2 virtual server
      5. Run UBOS on Raspberry Pi 5
      6. Run UBOS on ESPRESSObin
      7. Run UBOS in a Linux container on a PC (64bit)
      8. 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. Managing Sites and Apps
    6. Backup and restore
    7. Upgrading and keeping UBOS current
    8. The UBOS Staff
    9. 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
    10. Device-specific Notes
      1. ESPRESSObin
      2. Raspberry Pi
    11. Advanced management
      1. Enabling non-standard package repositories
      2. Migrating from one App to another
      3. Pinning resources
    12. Command reference
    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 run UBOS in a Docker container?
      5. Can I use UBOS without purchasing a domain name?
      6. Cannot access MySQL database. File missing: /etc/mysql/root-defaults-ubos.cnf
      7. Cannot boot UBOS from boot stick on a PC
      8. Cannot connect to the public internet from a UBOS container
      9. Cannot create a temporary backup; the backup directory is not empty
      10. Failed to create file /sys/devices/system/cpu/microcode/reload
      11. How are the various UBOS images different from each other?
      12. How can I install more than one web App on the same Device?
      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 is it called UBOS?
      41. 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
  2. Developer documentation
    1. Developer setup
      1. Developing using Arch Linux on VirtualBox x86_64 with a systemd-nspawn container
      2. Developing using a UTM Arch Linux VM on Apple Silicon computers with UBOS in a systemd-nspawn container
      3. Alternate developer setups
        1. Developing using a systemd-nspawn container (Linux host only)
        2. Developing using Arch Linux using Parallels on Apple Silicon with a systemd-nspawn container
        3. Developing using a UTM Arch Linux VM on Apple x86_64 computers with UBOS in a systemd-nspawn container
    2. Developer tutorials for standalone UBOS apps (not UBOS Mesh)
      1. Build and run your first UBOS standalone App
      2. How to package UBOS standalone Apps built with a variety of languages
        1. Hello World
        2. Glad-I-Was-Here (PHP, Mariadb)
        3. An Accessory for Glad-I-Was-Here (PHP, Mariadb)
        4. Glad-I-Was-Here (PHP, Postgresql)
        5. Glad-I-Was-Here (Python, Mariadb)
    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 as a UBOS development system
        1. How to create a UBOS development VM for VirtualBox on x86_64
        2. How to create a UBOS development VM for UTM on x86_64 Apple computers
        3. How to create a UBOS development VM for UTM on Apple Silicon computers
        4. How to create a UBOS development VM for Parallels Desktop on Apple Silicon computers
      4. Creating cloud images
        1. Amazon Web Services EC2
    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. Is it possible to run UBOS Gears or Mesh on an operating system other than UBOS Linux?
      5. Can I manage apps packaged as Docker containers with UBOS?
  3. Architecture
  4. Glossary
    1. Accessory
    2. App
    3. AppConfigId
    4. AppConfigItem
    5. AppConfiguration
    6. Arch
    7. Arch Linux
    8. Attribute
    9. blessing
    10. Bot
    11. Context Path
    12. Customization Point
    13. Data Transfer Protocol
    14. Deployment
    15. Depot
    16. Device
    17. Device Class
    18. diet4j module framework
    19. EntityType
    20. Flock
    21. Gradle
    22. Handlebars
    23. History
    24. Home Server
    25. HostId
    26. Hostname
    27. IDE
    28. Installation
    29. LetsEncrypt
    30. mDNS
    31. MeshBase
    32. MeshObject
    33. MeshObjectIdentifier
    34. MeshType
    35. MeshTypeIdentifier
    36. Middleware
    37. Model
    38. Network Configuration
    39. Package
    40. Pagekite
    41. Parallels Desktop
    42. Personal Server
    43. PKGBUILD
    44. Property
    45. PropertyType
    46. Relationship
    47. RelationshipType
    48. Release Channel
    49. Repository
    50. Retention Bucket
    51. Role
    52. RoleAttribute
    53. RoleProperty
    54. RoleType
    55. Rolling Release
    56. Shepherd
    57. Site
    58. Site JSON
    59. Site JSON Template
    60. SiteId
    61. Transaction
    62. Transaction Log
    63. UBOS Gears
    64. UBOS Linux
    65. UBOS Manifest
    66. UBOS Mesh
    67. UBOS Mesh code generator
    68. UBOS Project
    69. UBOS Staff
    70. unblessing
    71. UTM
    72. VirtualBox
    73. VMWare
    74. Wildcard hostname

How to modify the configuration of your Site

/docs/operation/faq-howto-troubleshooting/howto-modifysite/

Let’s say you have a Site running on your Device, with an App or several, and you’d like to make changes to your configuration, such as adding or removing Apps or Accessories. Here are some ideas how to go about it for common scenarios.

Common to all these scenarios that you need to obtain your Site’s Site JSON (a text file), make a modification to that Site JSON, and then redeploy it. So let’s first talk about this.

First, let’s figure out what Sites are currently running on your Device:

% ubos-admin listsites

This lists the Sites by their hostnames, and some information about which Apps are deployed at which Site.

To obtain the full Site JSON for a Site with hostname example.com, including all secret credentials (which is needed if you want to redeploy):

% sudo ubos-admin showsite --hostname example.com --json

If your Site has hostname * – the Wildcard hostname – you need to put that star into single quotes, otherwise your shell will get in your way:

% sudo ubos-admin showsite --hostname '*' --json

That will print the Site JSON for that Site to the terminal. Because that’s a bit impractical given we want to make changes to it, we rather save that output to a file. What you call that (temporary) file is immaterial; in our example we call it the same as the hostname with the extension .json, such as:

% sudo ubos-admin showsite --hostname example.com --json > example.com.json

Now you can edit that file – here example.com.json – with a text editor of your choice, such as vim. Which edits you want to make depend on what changes you want to make to your Site – see below.

But once you are done, you redeploy the Site JSON like this:

% sudo ubos-admin deploy --file example.com.json

That’s assuming your changed Site JSON file is called example.com.json.

UBOS will figure out what has changed between the current deployed configuration, and the modified configuration, and make suitable changes to your Device.

Warning

Always make a backup of your Site before you redeploy. UBOS deletes the data of Apps and Accessories you deleted, or whose AppConfigId you changed. As mistakes can happen, a backup before redeploy is always a good idea.

How to change the hostname of a Site

For example, you might have run your Site at example.com but you let that domain expire and now you’d like to run it at example.net instead. Or, you may have initially created your Site with Wildcard hostname * and now you need to give it an official hostname so you can get a SSL/TLS certificate for it.

To do this:

  1. Save your Site JSON to a file as described above.

  2. Find the hostname element and change its value. For example, modify:

    "hostname" : "*",
    

    to:

    "hostame" : "example.pagekite.me",
    
  3. Save the file.

  4. Redeploy your modified Site JSON file as described above.

How to change the context path of an App

For example, you might run Wordpress at root of your Site example.com, but would like to move it to example.com/blog so you can run another App at the same hostname.

  1. Save your Site JSON to a file as described above.

  2. Find the context element and change its value. For example, modify:

    "context" : "",
    

    to:

    "context" : "/blog",
    
  3. Save the file.

  4. Redeploy your modified Site JSON file as described above.

How to add LetsEncrypt TLS to your non-TLS Site

Note

This only works if your Device can be accessed from the public internet. If you have your Device behind a firewall, you need to run Pagekite or open up a port in your router.

  1. Save your Site JSON to a file as described above.

  2. Then add this into your Site JSON file on the first level inside the outer curly braces:

    "tls" : {
        "letsencrypt" : true
    },
    

    Make sure there is a comma each between what you added and what comes before and after.

  3. Check the e-mail address in the admin section of your Site JSON and make sure it is a valid e-mail address.

  4. Save the file.

  5. Redeploy your modified Site JSON file as described above.

How to add another App to an existing Site

  1. Save your Site JSON to a file as described above.

  2. You can manually add an entire AppConfiguration section in the appconfigs section in your Site JSON. However, that tends to be a bit tedious and is easy to get wrong. So we suggest copy-paste instead:

  3. Run ubos-admin createsite -n. (The -n flag prevents UBOS from actually doing the createsite; instead it will only emit Site JSON for the Site it didn’t actually create.). Make up some data for the hostname, admin accounts and the like; those values won’t matter. But enter the App, and all information about it like Context Path and Accessories, as you want it to be on your modified Site.

  4. Once the command has completed, a Site JSON file will be printed to the terminal. Copy the curly-braced section inside the appconfigs section. Then, insert that section into your existing Site JSON file, as a sibling of the section (or sections) that are there already inside appconfigs. Make sure there is a comma before and after what you added if there is a section before or after.

  5. Save the file.

  6. Redeploy your modified Site JSON file as described above.

How to remove an App from an existing Site

Warning

Always make a backup of your Site before you redeploy. UBOS deletes the data of Apps and Accessories you deleted, or whose AppConfigId you changed. As mistakes can happen, a backup before redeploy is always a good idea.

  1. Save your Site JSON to a file as described above.

  2. Find the AppConfiguration in your Site JSON. It would be an element in the appconfigs section, with potentially lots of lower-level entries. Remove all of it. (Of course if you have only one AppConfiguration at your Site, it may be easier to simply undeploy the entire Site.)

  3. Save the file.

  4. Redeploy your modified Site JSON file as described above.

How to add an Accessory to an AppConfiguration

  1. Save your Site JSON to a file as described above.

  2. Find the list of already deployed Accessories. It looks like this:

    "accessoryids" : [
        "nextcloud-contacts",
        "nextcloud-calendar"
    ],
    

    and add the Package name of the Accessory into that array. For example, if you wanted to add the Nextcloud “Deck” to a Nextcloud deployment, you would modify this to read:

    "accessoryids" : [
        "nextcloud-contacts",
        "nextcloud-calendar",
        "nextcloud-deck"
    ],
    
  3. If there aren’t any Accessories yet at your AppConfiguration, you will have to add this array, as a sibling of appid.

  4. Save the file.

  5. Redeploy your modified Site JSON file as described above.

How to remove an Accessory from an AppConfiguration

Warning

Always make a backup of your Site before you redeploy. UBOS deletes the data of Apps and Accessories you deleted, or whose AppConfigId you changed. As mistakes can happen, a backup before redeploy is always a good idea.

  1. Save your Site JSON to a file as described above.

  2. That’s easy! Find the name of the Accessory in the accessoryids section, and remove it. If that was the only Accessory, you can remove the entire `accessoryids`` section, but you don’t need to.

  3. Save the file.

  4. Redeploy your modified Site JSON file as described above.