Developing for the Ubports Installer

This post goes over adding a new device to the ubports installer for Ubuntu Touch and helps ensure that the configs were valid.

You need to have python, nodejs and npm installed.

Set up the installer

git clone
cd ubports-installer

The README file tells you to run the setup-dev script, but it’s safer to validate ourselves what it does.

# Install required programs and npm packages
# Same as:
apt install nodejs npm libgconf-2-4
npm install

We can now launch the installer with npm start. For more verbose output, use npm start -- -vv.

There are other “scripts” available to run via run run, for example npm run lint. You can discover all available commands in package.json under the scripts: {...} section.

Set up device configs

To begin setting up our own device in the installer, we need to update the separately-kept installer configs.

git clone
cd installer-configs
npm install

Make your changes to v2/<device>.yml, then check if the YAML syntax is valid with npm run validate.

The spec for the YAML schema is documented well, and you can look at existing devices for inspiration.

Once we have created or updated our own installer configs, we need to let the installer know about them. Let the build command convert the configs into JSON files and serve them via a simple HTTP server:

npm run buildconfigs
cd public
python -m http.server

Now, we instruct the installer to fetch our updated configs from our own endpoint.

By default, the installer fetches available devices and configs from

The URL to fetch from is set in src/core/api.js, and the installer expects a response in JSON format.


baseURL: "",


baseURL: "http://localhost:8000/v2/",

We also need to change the function fetching the index file a bit, from:

const getIndex = () => api.get("/").then(({ data }) => data);


const getIndex = () => api.get("/index.json").then(({ data }) => data);

Now the installer fetches your local configs and you can test whether it succeeds.

Further ideas

This post was inspired by my quest to update the installer configs for the Xperia XZ and X Performance and hunting down a pernicious bug. I validated my fix and went on to also add the XZ to the official Ubuntu Touch device list.

Published by

Edit source on Github