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

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

  1. Install the nginx bundle.

    sudo swupd bundle-add nginx
    
  2. 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
    
  3. 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
    
  4. Grant $USER permission to run the web server.

    sudo tee -a /etc/nginx/nginx.conf << EOF
    user $USER;
    EOF
    
  5. 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
    
  6. Restart the daemon, enable nginx on boot, and start the service.

    sudo systemctl daemon-reload
    
    sudo systemctl enable nginx --now
    
  7. 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

  1. Create a top-level directory to hold all apps.

    mkdir ~/my-3rd-party-apps && pushd $_
    
  2. 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.

  1. Install the mixer tool.

    sudo swupd bundle-add mixer
    
  2. Create a mixer workspace.

    mkdir ~/mixer && cd $_
    
  3. Initialize a mix without any default bundles.

    mixer init --no-default-bundles
    
  4. 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>"
    
  5. 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
    
  6. 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
    
  7. Add both bundles to the mix.

    mixer bundle add os-core
    mixer bundle add helloclear
    
  8. 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>/.

  1. 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
    
  2. Query the list of bundles from the repo.

    sudo swupd 3rd-party bundle-list -a
    
  3. Add the helloclear bundle.

    sudo swupd 3rd-party bundle-add helloclear
    
  4. List installed 3rd-party bundles.

    sudo swupd 3rd-party bundle-list
    
  5. Look in /opt/3rd-party to confirm they were installed there.

    tree /opt/3rd-party
    

    Example out:

    /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:

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

On the client side:

  1. Run sudo swupd 3rd-party update to update to the latest version of your mix.
  2. Now, you can see and add the new bundles.

Some limitations of 3rd-party bundles

  1. 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.
  2. 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.