Documentation:

How to modify the configuration of your Site

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. 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, 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 App are deployed at each 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 --host example.com --json

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

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

That will print the Site JSON for the 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 file is immaterial; in our example we call it the same as the hostname with the extension .json, such as:

% sudo ubos-admin showsite --host 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 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 or 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 context path of an App

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

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

    "context" : "/blog",
    

    to:

    "context" : "/news",
    
  • 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 UBOS Device can be accessed from the public internet. If you have your UBOS device behind a firewall, you need to run Pagekite or open up a port in your router.

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

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

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

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

  • Redeploy your modified Site JSON file as described above.

How to add another App to an existing Site

  • Save your Site JSON to a file as described above.
  • You can manually add an entire AppConfiguration section in your appconfigs section. However, that tends to be a bit tedious and easy to get wrong. So we suggest copy-paste instead:
  • 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 host name and Accessories, as you want it to be on your existing Site.
  • 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.
  • Redeploy your modified Site JSON file as described above.

How to remove an App from an existing Site

  • Save your Site JSON to a file as described above.
  • 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.)
  • Redeploy your modified Site JSON file as described above.

How to add an Accessory to an AppConfiguration

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

  • 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”, you would modify this to read:

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

  • Redeploy your modified Site JSON file as described above.

How to remove an Accessory from an AppConfiguration

  • Save your Site JSON to a file as described above.
  • 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.
  • Redeploy your modified Site JSON file as described above.