Create, Install, and Manage 3rd-party Bundles (#1075)

Closes #528

Signed-off-by: Bun K Tan <bun.k.tan@intel.com>
This commit is contained in:
bktan8
2020-03-19 17:43:25 -07:00
committed by GitHub
parent 57929c7af8
commit 2417f133c6
2 changed files with 300 additions and 28 deletions
+27 -28
View File
@@ -1064,58 +1064,57 @@ a firewall.
.. rst-class:: content-collapse
.. _set-up-nginx-web-server-start:
Set up a nginx web server for mixer
===================================
A web server is needed to host your update content. In this example, we use
the nginx web server, which comes with |CL|.
A web server is needed to host your update content. In this example,
the nginx web server is used.
Set up a nginx web server for mixer with the following steps:
#. Install the :command:`nginx` bundle:
#. Install the :command:`nginx` bundle.
.. code-block:: bash
sudo swupd bundle-add nginx
#. Make the directory where mixer updates will reside:
#. Create a symbolic link to the mixer update content directory.
.. code-block:: bash
sudo mkdir -p /var/www
#. Create a symbolic link between your workspace updates and the updates on
the local nginx web server. In this example, `$HOME/mixer` is the
workspace for the mix.
.. code-block:: bash
sudo ln -sf $HOME/mixer/update/www /var/www/mixer
#. Set up ``nginx`` configuration:
#. Set up nginx configuration files.
.. code-block:: bash
sudo mkdir -p /etc/nginx/conf.d
#. Copy the default example configuration file:
sudo cp -f /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf
#. Grant ``$USER`` permission to run the web server.
.. code-block:: bash
sudo cp -f /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf
sudo tee -a /etc/nginx/nginx.conf << EOF
user $USER;
EOF
#. Configure the mixer update server. Create and add the following server
configuration content to :file:`/etc/nginx/conf.d/mixer.conf` (sudo required):
#. Configure the mixer update server.
.. code-block:: console
.. code-block:: bash
sudo tee -a /etc/nginx/conf.d/mixer-server.conf << EOF
server {
server_name localhost;
location / {
root /var/www/mixer;
autoindex on;
}
server_name localhost;
location / {
root /var/www/mixer;
autoindex on;
}
}
EOF
#. Restart the daemon, enable nginx on boot, and start the service.
@@ -1123,13 +1122,13 @@ Set up a nginx web server for mixer with the following steps:
sudo systemctl daemon-reload
sudo systemctl enable nginx
sudo systemctl enable nginx --now
sudo systemctl start nginx
#. 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``.
#. Verify the web server is running at \http://<ip-address>,
where <ip-address> is the same one that you captured in
`Example 1: Mix set up`_.
.. _set-up-nginx-web-server-end:
Related topics
**************
+273
View File
@@ -0,0 +1,273 @@
.. _swupd-3rd-party:
swupd 3rd-party
###############
Upstream |CL| offers a plethora of `bundles`_ to choose from. 
For users who want access to additional software outside of the distro,
|CL| provides support for 3rd-party bundles.
There are two components to 3rd-party bundles:
* Use :command:`mixer` to create 3rd-party bundles
* Use the :command:`swupd` subcommand :command:`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.
.. contents::
:local:
:depth: 1
Prerequisite
*************
* Familiarity with :command:`mixer`
* Familiarity with :command:`swupd`
* You must be running |CL| version 32570 or higher
.. include:: ./mixer.rst
:start-after: set-up-nginx-web-server-start:
:end-before: set-up-nginx-web-server-end:
Create directory to hold 3rd-party app
**************************************
#. Create a top-level directory to hold all apps.
.. code-block:: bash
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.
.. code-block:: bash
# 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
:file:`/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 :command:`rpm2cpio <RPM>| sudo cpio -idv`.
Create bundle of 3rd-party app with mixer
*****************************************
Next, use :command:`mixer` to create a bundle for each of the apps from the previous
section.
#. Install the mixer tool.
.. code-block:: bash
sudo swupd bundle-add mixer
#. Create a mixer workspace.
.. code-block:: bash
mkdir ~/mixer && cd $_
#. Initialize a mix without any default bundles.
.. code-block:: bash
mixer init --no-default-bundles
#. Configure :file:`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.
.. code-block:: bash
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. :command:`swupd` client expects the
`os-core` bundle to exist in a mix even if it’s empty.
.. code-block:: bash
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.
.. code-block:: bash
mixer bundle create helloclear --local
echo "content($HOME/my-3rd-party-apps/helloclear/)" >> local-bundles/helloclear
#. Add both bundles to the mix.
.. code-block:: bash
mixer bundle add os-core
mixer bundle add helloclear
#. Build the bundles and generate the update content.
.. code-block:: bash
sudo mixer build bundles
sudo mixer build update
Install and manage 3rd-party bundle on client system
****************************************************
Finally, use the :command:`swupd` client tool to install and
manage the bundle created with :command:`mixer` earlier.
All installed 3rd-party bundles reside in :file:`/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.
.. code-block:: bash
sudo swupd 3rd-party add my-3rd-party-repo \
http://<IP-address-of-web-server> --allow-insecure-http
.. note::
By default, the :command:`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 :command:`swupd`, enter:
.. code-block:: bash
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.
.. code-block:: bash
sudo swupd 3rd-party bundle-list -a
#. Add the `helloclear` bundle.
.. code-block:: bash
sudo swupd 3rd-party bundle-add helloclear
#. List installed 3rd-party bundles.
.. code-block:: bash
sudo swupd 3rd-party bundle-list
#. Look in :file:`/opt/3rd-party` to confirm they were installed there.
.. code-block:: bash
tree /opt/3rd-party
Example out:
.. code-block:: console
/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 :command:`mixer versions update`.
#. Follow the remaining mixer process to add and build bundles.
On the client side:
#. Run :command:`sudo swupd 3rd-party update` to update to the latest version of your mix.
#. 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.
Related topics
**************
* :ref:`autospec`
* :ref:`mixer`
* :ref:`bundles`
* :ref:`swupd-guide`
.. _bundles:
https://clearlinux.org/software
.. _bundle definition:
https://docs.01.org/clearlinux/latest/guides/clear/mixer.html#id16