280 lines
9.4 KiB
ReStructuredText
280 lines
9.4 KiB
ReStructuredText
SPOC user manual
|
|
==================
|
|
|
|
.. image:: attachments/schema-spoc-user.png
|
|
:alt: Deliverable lifecycle - User consumption schema
|
|
:align: center
|
|
|
|
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.html>`_ 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
|