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, 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.

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

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

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

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.