Spotter-VM/doc/toolchain/spoc-user.rst

276 lines
9.3 KiB
ReStructuredText
Raw Normal View History

2020-06-01 22:05:55 +02:00
SPOC user manual
==================
Usage
-----
In order to consume the images and applications from online repositories, the user needs to set up the online repository URL and ECDSA public key in their ``/etc/spoc/spoc.conf`` file. The configuration file directives are covered on the `architecture <spoc-architecture>`_ page.
Images
------
List images
^^^^^^^^^^^
The user can choose to download any image and spawn a separate standalone container, not tied to any application. To list the images in the respective repositories, ``spoc-image list`` command is used.
.. code-block:: text
usage: spoc-image list [{installed,online,published}]
positional arguments:
{installed,online,published}
Selected repository
Download image
^^^^^^^^^^^^^^
Then the user needs to issue ``spoc-image download`` to download the image and make it available locally.
.. code-block:: text
usage: spoc-image download image
positional arguments:
image Name of the image to download
Delete image
^^^^^^^^^^^^
If the user wishes to delete locally installed image, they need to run ``spoc-image delete``.
.. code-block:: text
usage: spoc-image delete image
positional arguments:
image Name of the image to delete
Cleanup unused images
^^^^^^^^^^^^^^^^^^^^^
If the user wants to clean up all locally installed images which are not used by any container, there is ``spoc-image clean`` to do just that.
.. code-block:: text
usage: spoc-image clean
Containers
----------
Create container
^^^^^^^^^^^^^^^^
To create a container based on locally installed image, the user needs to use ``spoc-container create`` command. This command has a lot of parameters, making it possible to customize every aspect of the container supported by SPOC.
.. code-block:: text
usage: spoc-container create [-d DEPENDS] [-m MOUNT] [-e ENV] [-u UID] [-g GID] [-c CMD] [-w WORKDIR] [-r READY] [-s STOPSIG] container image
positional arguments:
container Name of the container to create
image Name of the image of which the container should be based
optional arguments:
-d DEPENDS, --depends DEPENDS
Add another container as a start dependency
-m MOUNT, --mount MOUNT
Add mount to the container - format volume:mountpoint[:file]
-e ENV, --env ENV Add environment variable for the container - format KEY=value
-u UID, --uid UID Sets the container init UID
-g GID, --gid GID Sets the container init GID
-c CMD, --cmd CMD Sets the container init command
-w WORKDIR, --workdir WORKDIR
Sets the container init working directory
-r READY, --ready READY
Sets the container ready command
-s STOPSIG, --stopsig STOPSIG
Sets the signal to be sent to init on container shutdown
Modify container
^^^^^^^^^^^^^^^^
In similar fashion, ``spoc-container modify`` can be used to update the configuration of existing container.
.. code-block:: text
usage: spoc-container modify [-d DEPENDS] [-m MOUNT] [-e ENV] [-u UID] [-g GID] [-c CMD] [-w WORKDIR] [-r READY] [-s STOPSIG] container
positional arguments:
container Name of the container to modify
optional arguments:
-d DEPENDS, --depends DEPENDS
Add another container as a start dependency - prepend the name with ! to remove the dependency
-m MOUNT, --mount MOUNT
Add mount to the container - format volume:mountpoint - specify empty mountpoint to remove the mount
-e ENV, --env ENV Add environment variable for the container - format KEY=value - specify empty value to remove the env
-u UID, --uid UID Sets the container init UID
-g GID, --gid GID Sets the container init GID
-c CMD, --cmd CMD Sets the container init command
-w WORKDIR, --workdir WORKDIR
Sets the container init working directory
-r READY, --ready READY
Sets the container ready command
-s STOPSIG, --stopsig STOPSIG
Sets the signal to be sent to init on container shutdown
Destroy container
^^^^^^^^^^^^^^^^^
To destroy the container, i.e. to unregister from metadata and remove its LXC configuration, ``spoc-container destroy`` should be used.
.. code-block:: text
usage: spoc-container destroy container
positional arguments:
container Name of the container to destroy
The containers can be started and stopped via commands ``spoc-container start`` and ``spoc-container stop``. The start command allows to override the default init command.
Start / stop container
^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: text
usage: spoc-container start container ...
positional arguments:
container Name of the container to start
command Command to be run instead of the default init command
.. code-block:: text
usage: spoc-container stop container
positional arguments:
container Name of the container to stop
Check container status
^^^^^^^^^^^^^^^^^^^^^^
In order to check status of a container ``spoc-container status`` command can be issued.
.. code-block:: text
usage: spoc-container status [-h] container
positional arguments:
container Name of the container to check
Execute command in a container
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Finally, whenever a command needs to be run in context of the container, ``spoc-container exec`` can be used. This command automatically determines if the container is stopped or started and depending on that, it either created the namespace or just attach to the already existing one.
.. code-block:: text
usage: spoc-container exec [-u UID] [-g GID] container ...
positional arguments:
container Name of the container in which to run the command
command The command to be run
optional arguments:
-u UID, --uid UID Sets the command UID
-g GID, --gid GID Sets the command GID
Applications
------------
List applications
^^^^^^^^^^^^^^^^^
In similar fashion like the images, the user can list also the applications and filter them by repository or status. This is done via ``spoc-app list`` command.
.. code-block:: text
usage: spoc-app list [{installed,online,updates,published,running,stopped}]
positional arguments:
{installed,online,updates,published,running,stopped}
Selected repository or application criteria
Install application
^^^^^^^^^^^^^^^^^^^
To install an application, the user issues ``spoc-app install`` command. SPOC's dependency solver and task queue ensures that the components used by the application are made available first before the application is attempted to be installed.
.. code-block:: text
usage: spoc-app install app
positional arguments:
app Name of the application to install
Update application
^^^^^^^^^^^^^^^^^^
In the same way as installation, the user can update locally installed application via ``spoc-app update``.
.. code-block:: text
usage: spoc-app update app
positional arguments:
app Name of the application to update
Uninstall application
^^^^^^^^^^^^^^^^^^^^^
To uninstall the application, the user runs ``spoc-app uninstall``. Note that this command only uninstalls the application and removes its containers, leaving all the images formerly used by them locally registered and installed. In order to remove them for good, user may execute ``spoc-image clean`` described above.
.. code-block:: text
usage: spoc-app uninstall app
positional arguments:
app Name of the application to uninstall
Start / stop application
^^^^^^^^^^^^^^^^^^^^^^^^
In order to start or stop the application, resp. all its containers in the order given by the dependencies in metadata, the user can issue ``spoc-app start`` and ``spoc-app stop`` respectively.
.. code-block:: text
usage: spoc-app start app
positional arguments:
app Name of the application to start
.. code-block:: text
usage: spoc-app stop app
positional arguments:
app Name of the application to stop
Check application status
^^^^^^^^^^^^^^^^^^^^^^^^
To check the application status, the user can use ``spoc-app status``. The application is just a group of containers, so the output will simply display status of all containers in the given application environment.
.. code-block:: text
usage: spoc-app status app
positional arguments:
app Name of the application to check
Set application autostart
^^^^^^^^^^^^^^^^^^^^^^^^^
To have the application automatically started after the VM boots up (resp. when the host's init executes the SPOC service), one can use ``spoc-app autostart``. This option exists only for applications, not for the individual containers.
.. code-block:: text
usage: spoc-app autostart app {1,on,enable,true,0,off,disable,false}
positional arguments:
app Name of the application to be automatically started
{1,on,enable,true,0,off,disable,false}
Set or unset the applications to be automatically started after the host boots up