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

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