swupd 3rd-party¶

Upstream Clear Linux OS offers a plethora of bundles to choose from.

For users who want access to additional software outside of the distro, Clear Linux OS provides support for 3rd-party bundles.

There are two components to 3rd-party bundles:

Use mixer to create 3rd-party bundles
Use the swupd subcommand 3rd-party to manage repos, consume and manage bundles

Follow this guide to set up a web server to host 3rd-party bundles, build an example 3rd-party bundle, install and manage the bundle on a client system.

Prerequisite
Create directory to hold 3rd-party app
Create bundle of 3rd-party app with mixer
Install and manage 3rd-party bundle on client system
Create more bundles and add to client
Some limitations of 3rd-party bundles
Related topics

Also, see our general guidelines on sharing 3rd-party bundles.

Prerequisite ¶

Familiarity with mixer
Familiarity with swupd
You must be running Clear Linux OS version 32570 or higher

Set up a nginx web server for mixer¶

A web server is needed to host your update content. In this example, the nginx web server is used.

Install the nginx bundle.
```
sudo swupd bundle-add nginx
```

Create a symbolic link to the mixer update content directory.

sudo mkdir -p /var/www

sudo ln -sf $HOME/mixer/update/www /var/www/mixer

Set up nginx configuration files.

sudo mkdir -p  /etc/nginx/conf.d

sudo cp -f /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf

Grant $USER permission to run the web server.

sudo tee -a /etc/nginx/nginx.conf << EOF
user $USER;
EOF

Configure the mixer update server.

sudo tee -a /etc/nginx/conf.d/mixer-server.conf << EOF
server {
  server_name localhost;
  location / {
    root /var/www/mixer;
    autoindex on;
  }
}
EOF

Restart the daemon, enable nginx on boot, and start the service.

sudo systemctl daemon-reload

sudo systemctl enable nginx --now

Verify the web server is running at http://<IP-address-of-web-server>. If there’s no mix content yet, the expected response from nginx will be a 404 Not Found.

Create directory to hold 3rd-party app ¶

Create a top-level directory to hold all apps.
```
mkdir ~/my-3rd-party-apps && pushd $_
```
Create a directory for each app and put the content of your software in it.

In this example, the helloclear.sh app simply prints “Hello Clear!” when invoked.
```
# make helloclear directory
mkdir -p helloclear/usr/bin && pushd $_

# create helloclear.sh script
cat > helloclear.sh << EOF
#!/bin/bash
echo "Hello Clear!"
EOF

# make script executable
chmod +x helloclear.sh

popd
```
Note
- You can put whatever you want in your app’s directory. All of the content within each directory will get copied onto the client system under /opt/3rd-party/bundles/<repo-name>/.
- To use a 3rd-party RPM, it is recommended to extract the content of the RPM into a directory. Use rpm2cpio <RPM>| sudo cpio -idv.

Create bundle of 3rd-party app with mixer ¶

Next, use mixer to create a bundle for each of the apps from the previous section.

Install the mixer tool.
```
sudo swupd bundle-add mixer
```
Create a mixer workspace.
```
mkdir ~/mixer && cd $_
```
Initialize a mix without any default bundles.
```
mixer init --no-default-bundles
```
Configure builder.conf to set the default bundle, CONTENTURL, and VERSIONURL. For the “URL”s in this example, it will be IP address of the web server that was set up earlier. Substitute <IP-address-of-web-server> with the IP address of your host.
```
mixer config set Swupd.BUNDLE "os-core"
mixer config set Swupd.CONTENTURL "http://<IP-address-of-web-server>"
mixer config set Swupd.VERSIONURL "http://<IP-address-of-web-server>"
```
Create an empty local os-core bundle. swupd client expects the os-core bundle to exist in a mix even if it’s empty.
```
mixer bundle create os-core --local
```
Using the helloclear app as an example, create the helloclear bundle and use the content() directive with the path to the helloclear directory in the bundle definition.

Refer to bundle definition for addition information on how to define a bundle.
```
mixer bundle create helloclear --local
echo "content($HOME/my-3rd-party-apps/helloclear/)" >> local-bundles/helloclear
```

Add both bundles to the mix.

mixer bundle add os-core
mixer bundle add helloclear

Build the bundles and generate the update content.

sudo mixer build bundles
sudo mixer build update

Install and manage 3rd-party bundle on client system ¶

Finally, use the swupd client tool to install and manage the bundle created with mixer earlier. All installed 3rd-party bundles reside in /opt/3rd-party/bundles/<repo-name>/.

First, add a repo link to the web server. The os-core bundle will be added automatically when adding a repo. It contains items that mixer injected into the mix such as version information, format, CONTENTURL, VERSIONURL, and certificate.
```
sudo swupd 3rd-party add my-3rd-party-repo \
http://<IP-address-of-web-server> --allow-insecure-http
```
Note

By default, the swupd client is designed to communicate with an HTTPS server. For development purposes, the swupd client can talk to an HTTP server if you add the flag --allow-insecure-http.

To avoid adding this flag each time when invoking swupd, enter:
```
sudo mkdir -p /etc/swupd

sudo tee -a /etc/swupd/config << EOF
[GLOBAL]
allow-insecure-http=true
EOF
```
Query the list of bundles from the repo.
```
sudo swupd 3rd-party bundle-list -a
```

Add the helloclear bundle.

sudo swupd 3rd-party bundle-add helloclear

List installed 3rd-party bundles.
```
sudo swupd 3rd-party bundle-list
```

Look in /opt/3rd-party to confirm they were installed there.

tree /opt/3rd-party

Example output:

/opt/3rd-party/
├── bin
│   └── helloclear.sh
├── bundles
│   └── my-3rd-party-repo
│       └── usr
│           ├── bin
│           │   └── helloclear.sh
│           ├── lib
│           │   └── os-release
│           └── share
│               ├── clear
│               │   ├── bundles
│               │   │   ├── helloclear
│               │   │   └── os-core
│               │   ├── update-ca
│               │   │   └── Swupd_Root.pem
│               │   ├── version
│               │   └── versionstamp
│               └── defaults
│                   └── swupd
│                       ├── contenturl
│                       ├── format
│                       └── versionurl
└── repo.ini

12 directories, 12 files

Create more bundles and add to client ¶

From here on, to add new bundles to your mix, follow these steps:

Follow the steps above to add a new directory for each app and put content into it.
In the mixer workspace, run mixer versions update.
Follow the remaining mixer process to add and build bundles.

On the client side:

Run sudo swupd 3rd-party update to update to the latest version of your mix.

Note

If swupd autoupdate is enabled, 3rd-party repositories will update automatically as well during regular swupd update.
Now, you can see and add the new bundles.

Some limitations of 3rd-party bundles ¶

You cannot upload your bundles to a shared community repo because bundles are tied to your particular mix with its own certificate. You have to host your own and share your repo.
As with upstream bundles, 3rd-party bundles installation is simply the unpacking of files onto your system. It cannot perform pre or post-installation actions such as adding a favorite shortcut to the Gnome desktop dock, for example.

swupd 3rd-party¶

Prerequisite¶

Set up a nginx web server for mixer¶

Create directory to hold 3rd-party app¶

Create bundle of 3rd-party app with mixer¶

Install and manage 3rd-party bundle on client system¶

Create more bundles and add to client¶

Some limitations of 3rd-party bundles¶

Related topics¶