Welcome to the Kiosc documentation!¶
Kiosc is a web application to control Docker containers that run a webserver.
It was conceived to facilitate presenting analysis results interactively (but is not limited to that) by running Docker images that are constricting any application that offers a web interface. Any image can be loaded, and Kiosc manages the access to the web interface of the application.
What Kiosc is and what it is not¶
Kiosc is a web interface for
loading Docker images and creating containers from it,
controlling the state of Docker containers,
controlling access to containers based on the user management provided by SODAR,
providing access to the app running in a container.
Kiosc is NOT
a tool to create Docker images,
for running Docker images without webserver (you can do that, but you won’t benefit from it),
for directly loading or sharing data (this has to be managed by the Docker image).
Note
You can find the official version of this documentation at readthedocs.io. If you view these files on GitHub, beware that their renderer does not render the ReStructuredText files correctly and content may be missing.
Overview¶
General Idea¶
Kiosc was developed to share analysis results with customers and collaborators that are best displayed using an app – an interactive client-side tool that is based on a webserver. The idea was to bundle the webserver in a custom-build Docker image with an application of choice. Upon starting, the container loads the data by setting the environment variables or passing a parameter to the command when starting the Docker container.
Kiosc takes the role of providing functionality to create, configure, manage and control Docker containers from such Docker images, allowing to set up the environment variables or the start command of the container, and to give access to the web interface of the container using a reverse proxy. Technically, Kiosc can be used to pull and start any Docker image, however, one would not benefit from that as it is specifically designed for Docker images hosting a web server.
A typical workflow scheme is then as follows:
Kiosc launches a previously configured docker container
The container downloads and initializes necessary data objects and starts a web server on a specified port serving the preconfigured app
Kiosc allows the access to the webserver via reverse proxy.
Users can navigate to the app served by the container from the Kiosc entry page.
SODAR Universe¶
Kiosc is based on the SODAR core framework and be linked to an upstream SODAR instance to receive projects, users and role assignments. Based on the project information, Docker containers can be created from available Docker images and shared with collaborators and customers.
Technical Description¶
Docker environment
Technical description of networks
Reverse proxy
Installation¶
We ship Kiosc as a Docker container, and provide Docker compose file to start also other required containers. This part describes how to use Kiosc as a Docker container, and also the manual is based on this.
Disclaimer: It is possible to run Kiosc as is (mode host), but this requires additional work to set up the database
and scheduler. This is not described in this manual. Also, this has impact on how the Docker containers the user creates
are organized and presented. This is also not described in this manual.
The Kiosc Docker container is served via Github Container Registry (gchr).
Docker compose¶
Set up the Docker compose by cloning the repository:
$ git clone https://github.com/bihealth/kiosc-docker-compose.git
$ cd kiosc-docker-compose
Initialize the folder structure required. Among others, the database will be stored in there, such it is available after restarting the container:
$ bash init.sh
Copy the env.example file to .env:
$ cp env.example .env
Here you can change Kiosc and Django parameters. Most of them are set to reasonable defaults, but changing the
DJANGO_SECRET_KEY is a good idea:
DJANGO_SECRET_KEY=CHANGEMEchangemeCHANGEMEchangemeCHANGEMEchangemeCH
When done, start the Docker containers:
$ docker-compose up
The Kiosc installation can now be reached by accessing localhost with your browser.
Configuration¶
Kiosc can be configured via environment variables. Docker compose can digest a .env file. It is a good idea to
leave the values as they are.
The environment file could look like this:
# Postgres configuration ----------------------------------------------------
POSTGRES_USER=kiosc
POSTGRES_PASSWORD=password
POSTGRES_DB=kiosc
POSTGRES_HOST=postgres
# Kiosc configuration -------------------------------------------------------
DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}/${POSTGRES_DB}"
DJANGO_ALLOWED_HOSTS="*"
DJANGO_SECRET_KEY="CHANGEMEchangemeCHANGEMEchangemeCHANGEMEchangemeCH"
DJANGO_SETTINGS_MODULE="config.settings.production"
PROJECTROLES_SITE_MODE=SOURCE
CELERY_BROKER_URL="redis://redis:6379/0"
KIOSC_SERVER_VERSION=main-0
KIOSC_NETWORK_MODE=docker-shared
KIOSC_DOCKER_NETWORK=kiosc-net
KIOSC_DOCKER_WEB_SERVER=kiosc-web
kIOSC_DOCKER_ACTION_MIN_DELAY=1
KIOSC_DOCKER_MAX_INACTIVITY=1
KIOSC_DOCKER_ACTION_MIN_DELAY=7
KIOSC_EMBEDDED_FILES=1
Note that setting PROJECTROLES_SITE_MODE=TARGET requires an upstream SODAR instance
that is running in SOURCE mode and that the Kiosc instance is registered to.
If no SODAR instance is available or connecting Kiosc to the SODAR instance is not intended,
set the PROJECTROLES_SITE_MODE=SOURCE. Further description of the SOURCE/TARGET
mode can be found in the SODAR Core documentation.
Optionally the LDAP can be configured with up to two LDAP servers:
# LDAP configuration --------------------------------------------------------
ENABLE_LDAP=1
AUTH_LDAP_SERVER_URI=...
AUTH_LDAP_BIND_PASSWORD=...
AUTH_LDAP_BIND_DN=...
AUTH_LDAP_USER_SEARCH_BASE=...
AUTH_LDAP_USERNAME_DOMAIN=...
AUTH_LDAP_DOMAIN_PRINTABLE=...
ENABLE_LDAP_SECONDARY=1
AUTH_LDAP2_SERVER_URI=...
AUTH_LDAP2_BIND_PASSWORD=...
AUTH_LDAP2_BIND_DN=...
AUTH_LDAP2_USER_SEARCH_BASE=...
AUTH_LDAP2_USERNAME_DOMAIN=...
AUTH_LDAP2_DOMAIN_PRINTABLE=...
If the KIOSC_ environment variables are not set, Kiosc selects the defaults as stated
in the following table.
Environment variable |
Default |
Description |
|---|---|---|
KIOSC_NETWORK_MODE |
|
Can be |
KIOSC_DOCKER_NETWORK |
|
Name of the Docker network for the users Docker containers. |
KIOSC_DOCKER_WEB_SERVER |
|
Name of the web server Docker container. |
KIOSC_DOCKER_ACTION_MIN_DELAY |
|
Min delay in seconds for Docker container actions. |
KIOSC_DOCKER_MAX_INACTIVITY |
|
Max threshold for inactive running Docker containers in days. |
KIOSC_EMBEDDED_FILES |
|
Enable the feature to upload small files to Kiosc that can be served to the Docker containers. |
Interface¶
When accessing the Kiosc web interface, one is greeted with the Kiosc logo and a login form. You need to have an account with Kiosc or the LDAP must be configured to be able to log in with your institute account. Approach your system administrator about that matter if you are unsure.
Once logged in, you will see an overview of all the projects you are assigned to, alike SODAR. If you do expect to have access to a project you do not have access to, ask the leader or delegate of that project to grant you access to that project. If the Kiosc instance is linked to a SODAR instance, the access is set in SODAR and must then be synchronized to Kiosc by the administrator.
To be able to access the Kiosc apps, click on a project. On the left-hand side you will have access to multiple apps, three of them are of interest:
Containers for creating and controlling Docker containers.
Container Template for creating templates for Docker containers.
Small Files for uploading smaller files that the containers can then access.
Additionally, in the top-right corner is a drop-down menu for account settings and site apps. This gives access to the site-wide container template app. This hosts container templates that are accessible site-wide and not project-wide.
Roles¶
Kiosc provides the same roles as SODAR Core as it is based on this framework. However, this section will clarify what each role is allowed to do within Kiosc.
Containers¶
Role |
Create/Update |
Delete |
Start |
Stop |
(Un)pause |
View |
|---|---|---|---|---|---|---|
Administrator |
OK |
OK |
OK |
OK |
OK |
OK |
Owner |
OK |
OK |
OK |
OK |
OK |
OK |
Delegate |
OK |
OK |
OK |
OK |
OK |
OK |
Contributor |
OK |
OK |
OK |
OK |
OK |
OK |
Guest |
(OK)* |
OK |
* Guests can’t start the container directly, but do so indirectly by requesting to view a not running container.
Container Templates¶
Project-wide¶
Role |
Create/Update |
Delete |
Copy*/Duplicate |
View |
|---|---|---|---|---|
Administrator |
OK |
OK |
OK |
OK |
Owner |
OK |
OK |
OK |
OK |
Delegate |
OK |
OK |
OK |
OK |
Contributor |
OK |
OK |
OK |
OK |
Guest |
OK |
* Copy project-wide or site-wide templates.
Cookbook¶
Contents
Guest accessing the web interface of a container¶
You are a guest of a project. You can list the containers of the project, and access the details of each container. You can’t change the status of a container, except indirectly by viewing a container that is not running. Probably you like to access the web interface provided by the container.
To proceed, click on a project and then select the Container app. This will display a list of all containers in the project. On the right-hand side of each container is a button with an eye icon. The button might be either gray-outlined with a crossed-out eye, or with a blue background with an open eye. The crossed-out eye indicates that the container is not running and this will also be reflected in the state. The blue open eye indicates that the container is available. No matter the state, clicking the icon will open the web interface provided by the container. The difference is that in the crossed-out state Kiosc tries to start the container before accessing the web interface which might take some time while in the running state the web interface will be displayed immediately.
Create a container running …¶
To create a container switch to the Containers app
and select Create Container. This will be the starting point for the following tutorials.
After the creation of the container you will be redirected
the details of the container. The state will be set to
initial which indicates that there is the container object
but no actual Docker container (yet). You can find the operations menu (cog icon)
on the top right of the details page. Open the dropdown
menu by clicking the cog icon and select Start, or click
the crossed-out eye icon to start and access the container directly.
Shiny (using environment variables)¶
For this tutorial we provide you with a pre-build Docker image with a Shiny application. Use the linked repository as a base to create your own Docker image.
This example sets up a simple Shiny application loading the popular iris dataset.
The data set is loaded by setting the dataset variable in the environment.
Fill out the following fields and click Create:
Title |
Set a unique title that helps you identify the container easily. |
Repository |
|
Tag |
|
Container Port |
|
Environment |
|
The Environment field should contain a JSON object literal, which corresponds to a Python dictionary with the exception that only double quotes are allowed, or nothing.
The value in the Environment field will be transformed and passed to the environment of the container. In the above example, the Docker container will hold two environment variables. Imagine that inside the container the following lines will be performed upon start:
$ export title="Kiosc Shiny App example"
$ export dataset=iris
Dash (using environment variables)¶
For this tutorial we provide you with a pre-build Docker image with a Dash application. Use the linked repository as a base to create your own Docker image.
In this example we are running a Dash application. As we are behind
a reverse proxy, the Dash application needs some tweaks to make it load
all scripts and stylesheets into the container when started. The Dash
application was extended by accepting an environmental variable named
PUBLIC_URL_PREFIX, and for this to work, you have to set up this
environment variable and set it to the value __KIOSC_URL_PREFIX__.
This acts as a place holder that is substituted with the path to the
container how it is known to the outside. Fill out the following fields and click Create:
Title |
Set a unique title that helps you identify the container easily. |
Repository |
|
Tag |
|
Container Port |
|
Environment |
|
The Environment field should contain a JSON object literal, which corresponds to a Python dictionary with the exception that only double quotes are allowed, or nothing.
The value in the Environment field will be transformed and passed to the environment of the container. In the above example, the Docker container will hold two environment variables. Imagine that inside the container the following lines will be performed upon start:
$ export PUBLIC_URL_PREFIX=containers/proxy/abcdef123...
seaPiper¶
For this tutorial we provide you with a pre-build Docker image with a seaPiper application. Use the linked repository as a base to create your own Docker image.
seaPiper is based on Shiny. Fill out the following fields and click Create:
Title |
Set a unique title that helps you identify the container easily. |
Repository |
|
Tag |
|
Container Port |
|
cellxgene (using a command)¶
This example takes a publicly available container and passes a command that is run when starting the container. In this case, the cellxgene application is started immediately when running the container. The data is loaded by passing the data URL to the command. Fill out the following fields and click Create:
Title |
Set a unique title that helps you identify the container easily. |
Repository |
|
Tag |
|
Container Port |
|
Command |
|
cellxgene (using a command with small files)¶
This example is the same as above but using a file uploaded to Kiosc. A command to copy-and-paste can’t be provided as the link to the file depend on the UUID that is randomly created. To get the file into Kiosc, download the file from the official server and upload it to Kiosc:
Download example data.
Go to a Kiosc project and select the Small Files app.
Upload the
pbmc3k.h5adfile. It is now available during container creation.
Now continue with the container creation. To make use of the uploaded file, when inserting the command, place the cursor at the mentioned position in the command, select the file and click Insert.
This will place a link at the cursor position.
Title |
Set a unique title that helps you identify the container easily. |
Repository |
|
Tag |
|
Container Port |
|
Command |
|
Files |
|
ScElvis (using a command and environment variables)¶
This example sets up the ScElvis. ScElvis is based on Dash.
For this to work, you have to set up two environment variables,
SCELVIS_URL_PREFIX helps the application alter the URL path
to load scripts and style sheets into the container and
SCELIVS_DATA_URL sets the data that is to be loaded into the
container. Fill out the following fields and click Create:
Title |
Set a unique title that helps you identify the container easily. |
Repository |
|
Tag |
|
Container Port |
|
Environment |
|
Command |
|
The Environment field should contain a JSON object literal, which corresponds to a Python dictionary with the exception that only double quotes are allowed, or nothing.
The value in the Environment field will be transformed and passed to the environment of the container. In the above example, the Docker container will hold two environment variables. Imagine that inside the container the following lines will be performed upon start:
$ export SCELVIS_URL_PREFIX=containers/proxy/abcdef123...
$ export SCELVIS_DATA_SOURCES=https://cellxgene-example-data.czi.technology/pbmc3k.h5ad
In addition to the user defined variables, the title, description and
container_port are also exposed as environment variables to the Docker container
(as TITLE, DESCRIPTION and CONTAINER_PORT respectively):
$ export TITLE="Some unique title"
$ export DESCRIPTION="Some description"
$ export CONTAINER_PORT=8050
Containers¶
Container objects hold the information to create and afterwards to control the underlying Docker containers. All information the user enters is used during the creation of the container (which happens when the container is started). They also hold information about the current state and include the logs reported by any process associated with the container.
Overview¶
Find the Containers icon in the left-hand menu to open the Container
app. This will list all available containers and offers the menus to
create new containers, control and delete containers and show details including
its logs.
Create¶
Contents
Click the Create Container button to enter the form for creating
a new container object. This does not create a Docker container yet but
only gathers information. The actual Docker container is created when
starting the container.
Fill in at least the mandatory fields, marked with a star (*). Some of
them are pre-filled with a reasonable default value. Change only if required.
Others like Title, Repository, Tag and Container Port have to
be set by the user. Below is a detailed description of each form field. In the example
screenshots, we set up a Shiny app.
Fill in a reasonable title that helps you identify the container. The title must be unique. A description is helpful, but not required.
Fill in the repository, tag and container port.
Click the Create button to create the container object.
This does not create the actual Docker container yet.
Container templates¶
To make use of the container templates, select a template from the
top-hand dropdown menu and click Get. This will populate all form fields
that are set in the template with you create form. Anything you already
entered will be overwritten. The prefix [Site-wide] or [Project-wide]
indicates whether this template is either a site-wide or a project-wide
template.
Environment¶
Environment variables can be specified using a JSON dictionary. Top-level keys in the dictionary become the environmental variables visible to the app launched in the container:
{
"ID": "My container",
"LIST": [ "A", "B", "C" ]
}
Given the above example, two environment variables will be defined: ID
and LIST. The contents of ID will be My container; the contents of
LIST will be [ 'A', 'B', 'C' ]. Note that the double quotes will be
changed to single quotes.
These variables are available to the web app of the container, and can be used to specify e.g. a data source or other parameters for the container web app.
In addition to the user defined variables, the title, description and
container_port are also exposed as environment variables to the Docker container
(as TITLE, DESCRIPTION and CONTAINER_PORT respectively).
The complete list looks like this:
{
"ID": "My container",
"LIST": [ "A", "B", "C" ],
"TITLE": "Some title",
"DESCRIPTION": "Some description",
"CONTAINER_PORT": 8080,
}
Environment secret keys¶
Environment secret keys is a comma-separated list of sensitive keys to environment variables that have to
have a corresponding key defined in the JSON dictionary in the environment field.
Those variables will be masked when editing them or viewing the details of the container.
Container path¶
The container path is the folder structure appended to the web address of the container.
Timeout¶
The timeout is set in seconds and is set as the time limit for any Docker action (start/stop/etc..) to complete.
Heartbeat URL (inactive)¶
The heartbeat URL can be used to check whether the container app runs correctly. (Feature is currently inactive)
Files¶
This dropdown provides the files that were uploaded to Kiosc via the Small Files
app to the project the current container is created in.
To get the internal link to the file the container then can access, click Insert
and the link will be appended to the command field.
Max retries¶
Maximal number of retries for an action in case of failure. If an action (e.g. starting a container) fails, it will be retried this many times.
Inactivity threshold¶
Number of days the container is allowed to run without proxy access. If this threshold is hit, the container will be stopped.
Details¶
Click on the title of a container to access its details and the logs. You will also be forwarded to the details once you created a container object. A detailed description of all the fields can be found below.
Contents
Initial container¶
When you created a container, the detail page will provide you with information about the container object. Please note that the container is still in initial state and not running yet. Thus, the button to access the proxy (eye icon) is not active.
In the bottom of the page the logs are displayed. In this case the logs only contain one entry, indicating that the object has been created.
To start the container, open the operator menu located on the
right-hand side of the title and click the Start item. The Docker container
will be created and started. This menu also provides you with the
options to edit (Update) or Delete the container.
Running container¶
Once the container is running, the detail page for the container
changes. The operator menu will change its entries, the button
to access the proxy server with the eye icon will turn blue and
the state of the container will be set to running.
The logs will be updated and now contain the logs coming from the Docker container.
When a user accesses the container via the proxy URL (which
is triggered by clicking the button with the eye icon),
this will also be displayed in the logs. Look out for an entry
that is provided by (Proxy), starting with Accessing [...].
Fields¶
Environment & Environment Secret Keys¶
Names of sensitive environment variables can be entered in the Environment secret keys field.
If you have set an environment and registered environment_secret_keys,
the value of the corresponding items in the environment dictionary are displayed in Kiosc
as <masked>, indicating that they are available to the system but
are not displayed for security reasons. However, they will still be visible
in plain in the container environment.
State¶
The current state is presented and highlighted:
initial, indicating that the database object has been created but no actual Docker container exists yet.
running
failed, indicating that something went wrong
exited
paused
If there is a small bell icon next to the state, this indicates that the last user action and the current state of the Docker container do not match.
Last action¶
The last action performed on the container of any user is displayed, if available. If there is an inconsistency found between the actual Docker state and the last user action (indicated by the bell icon right to the state), a cron job running every few minutes tries to perform the last known issued user action. The first number next to the action is a counter, indicating how many times it tried to re-perform the action, with the maximal limit indicated by the second number.
Date of latest Docker log¶
When a Docker log has been fetched in the past, this date indicates the timestamp of the latest Docker log and synchronisation of the Docker state. Docker logs are not displayed immediately in the log file but fetched by a background process every few minutes. This line is missing when there are no fetched Docker logs.
Logs¶
The logs will update themselves every half minute. As described above, Docker logs are also fetched only every few minutes from the Docker container, thus there can be a bit of latency until logs are displayed.
The log window combines logs from multiple sources. The structure of a log entry is:
[YYYY-MM-DD HH:MM:SS <LOG_LEVEL> <USER>] (<PROCESS>) <MESSAGE>
For example:
[2021-09-08 22:57:26 INFO anonymous] (Task) Syncing last registered container state (running) with current Docker state (exited)
Currently the following sources can contribute to the log:
Task: Logs reported by automatically running background tasks. Usually they are issued by
anonymous.Docker: Logs reported by Docker for this container. They are fetched every half minute, so they might not appear immediately.
Action: Any action the user issues on the container.
Proxy: Issued when accessing the proxy.
Object: Issued when changes in the database object are made that represents the Container in Kiosc.
Access & Controls¶
Contents
Access (via Proxy)¶
The web application running inside of the container can be accessed when clicking the button with the eye icon. A grey and crossed-out eye indicates that the container is currently not running. A click on the button will start the container and access the web application afterwards.
A blue button with an eye icon indicates that the container is running. The access will happen immediately when clicking the button.
Controls¶
The Controls dropdown menu (cog icon) comprises
multiple actions that can be issued on a container,
displayed depending on the state the container is currently in.
In the details page this menu is presented by the cog icon + Controls,
while in the list this is presented by the cog icon only.
The Controls button on the details page:
The Controls button on the container list:
When a container is stopped, the selection includes the actions
Start, Update and Delete, given the permissions.
When a container is running, the selection includes the actions
Stop, Pause, Restart, Update and Delete,
given the permissions.
Start¶
Create a container from a Docker image and start it. If the image isn’t cached yet, it is pulled from the specified repository. An existing container is always wiped before performing the starting action.
Internally, the following cadence is performed:
docker rm
docker pull
docker create
docker run
The state should be running when performed successfully.
Stop¶
Stop a running Docker container. Only available when Docker container state is reported as running.
Internally, a docker stop is performed.
The state should be exited when performed successfully.
Pause¶
Pause a running Docker container. Only available when Docker container state is reported as running.
Internally, a docker pause is performed.
The state should be paused when performed successfully.
Unpause¶
Unpause a paused Docker container. Only available when Docker container state is reported as paused.
A docker unpause is performed.
The state should be running when performed successfully.
Restart¶
Restart a running container. Only available when Docker container state is reported as running.
Internally, the following cadence is performed:
docker stop
docker rm
docker pull
docker create
docker start
(It’s NOT a docker restart as the name would suggest.)
The state should be running when performed successfully.
Update¶
This leads to the form to update the setting of the current container.
Please note that values of items in the environment dictionary are
displayed as <masked> if listed in the environment_secret_keys.
When left as <masked>, the value itself will not change. To set a
new value, simply change the value.
If the Docker container state is reported as running, a restart as described above will be performed to account for the changes.
Container Templates¶
Container templates were conceived to facilitate the creation of containers by offering default settings that can be copied during the creation of an actual container. Container templates themselves can be duplicated and copied to different projects. They do exist as a project-wide for every user, and as site-wide only available for the administrators.
Overview¶
Find the Container Templates icon in the left-hand menu to open the Container Template
app. This will list all available container templates and offers the menus to
create, update and delete templates.
Note that the new templates will be visible in all your projects on the KIOSC site.
Site-wide templates¶
The site-wide container templates can be found in the settings menu.
The difference between project-wide templates and site-wide templates is that only administrators can create site-wide templates, and as the name suggests are available on the entry site, i.e. can be used in every project. Project-wide templates are created in a specific project but can be accessed in every project the user has access to.
Create¶
Click Create to enter the form to create a template.
The only mandatory field is Title, which is also unique.
Everything else can be left out,
although some values should be set as the template makes no sense otherwise.
Create the template by clicking Create.
In the overview, the container template will be listed.
Details¶
Click on the title of a container template in the overview to enter the details of a container template. These are the same details that need to be provided when creating a container.
Copy¶
Select a template from the top-hand dropdown menu and click Copy to make
a copy of the selected template.
A new template with the same title will show
up in the list, only that the title is extended by (Copy).
In the dropdown menu all templates are listed the current user has access to, plus the site-wide templates. This enables the user to copy templates from other projects.
Controls¶
The Controls dropdown menu (cog icon) comprises
multiple actions that can be issued on template.
Duplicate¶
Duplicate is similar to the Copy action, only that you will make a copy or duplicate
of the template this menu is referring to. A new template with the same title will
show up in the list, only that the title is extended by (Duplicate).
The result is otherwise the same as when the user would make a copy of that template
with the Copy action. This means it is just a shortcut to copy templates around
within a template, while the Copy action is designed to copy templates across projects
or to copy site-wide templates.
Small Files¶
Overview¶
Kiosc has activated an app provided by SODAR Core that allows the user to upload files of smaller size (several MB, but not GB).
Find the Small Files icon in the left-hand menu to open the Small Files
app. This will list all uploaded files and allow to upload or delete files.
Those files then can be accessed by the containers created. For this
to work, a dropdown menu of files uploaded to a project is provided
during container creation that allows to insert an internal
link to that file into the command field. This link can only be
accessed by containers that are associated running inside the same
project the files is associated with.
The intention is that the application running inside of the container uses links to load the files anyway, and those links now can be replaced with internal links to files that are uploaded to Kiosc. This also requires the application inside the container to accept links as file source, another way to provide the file is not possible.
For further description on how to use the app, please have a look at the part in the SODAR Core manual.
When accessing the container form, the uploaded files are available
in a dropdown, and a link will be inserted into the command field
when Insert is clicked.
Overview¶
To access the administration interface for Kiosc containers (which is not to confuse with the Django administration interface), click on the user menu in the top right corner and choose Kiosc Admin.
This will open a page with three tabs: Containers, Not in Kiosc and Other Docker Entities.
Containers¶
This tab lists all available containers that were created in Kiosc, with their current status and the control menu to adjust the status of the container, or delete it.
Not in Kiosc¶
This tab lists all running Docker containers that are not connected to a container object in Kiosc. This is meant to list orphaned Docker containers, but it will also keep a list of Docker containers that are part of the Kiosc server itself. They are grayed out.
Other Docker Entities¶
This tab lists other Docker entitites that are not containers and comprises three lists, Docker networks, Docker volumes and Docker images.
Docker networks list among other the identifier and the connected containers as well as the subnet and gateway of the network.
Docker images list the identifier and the repository and tag name.
Docker volumes list the identifier and mountpoint.
Commands¶
Remove Stopped Containers¶
Usage: python manage.py remove_stopped --remove
This command removes all of the stopped containers.
To prevent accidentally deleting containers, the --remove
parameter has to be provided. Omitting this parameter
only dry-runs the command.
Stop All Containers¶
Usage: python manage.py stop_all
This command sets all containers to exited status, no
matter their current state.
Stop Unused Containers¶
Usage: python manage.py stop_unused
This command stops all containers that haven’t been accessed by the reverse proxy for a defined period of time (the parameter can be set in the container object itself, but there is an upper limit of 7 days).
Periodic Tasks¶
The user has no influence on periodic tasks, but the periodic tasks in return influence the user experience.
They are designed to keep the Docker containers consistent with the information the user enters into the web interface, and to fetch logs and information from the Docker containers.
Contents
Get logs and status from Docker container¶
Runs every 30 seconds.
This task fetches the logs that are provided by the Docker container, which includes logs from whatever runs inside of the Docker container. It also sets the Docker container status in the container database object, which means that the Docker container can change without the users intention (e.g. in case the Docker container exists unexpectedly).
Synchronize Docker container state with last user action¶
Runs every minute.
This task synchronizes the last user action performed on the container with the actual Docker container status if and only if this information differs. For example, if the Docker container exited for whatever reason but the last user action was to start the container, the task tries to run the Docker container.
Stop inactive containers¶
Runs every day at 1:11am.
This task stops inactive containers that were not accessed by the proxy for a defined period of time. This can be set by the user for each container individually, but there is maximum of 7 days. If the user omits the setting, it defaults to the 7 days maximum.
Synchronize with upstream SODAR instance (if configured)¶
Runs every five minutes.
This task synchronizes the projects and users with the upstream SODAR instance. Only if this site is in target mode.
Overview¶
Requirements¶
A token is required to validate against the REST API. When logged in to Kiosc, you can find the API Tokens link in your user dropdown menu in the top right corner of the site. Select Create Token from the Token Operations dropdown to create a new token. You will only see the token once, so make sure to copy it to clipboard at this point. Deleting existing tokens can be done from the token list.
Legend¶
The token used in the following examples is 1234567890abcdef
but the generated token will be much longer.
The project SODAR UUID used in the following examples is 00000000-0000-0000-0000-000000000000.
The container SODAR UUID used in the following examples is cccccccc-cccc-cccc-cccc-cccccccccccc.
Containers¶
Contents
Create Container¶
Create container in a project.
URL |
/containers/api/create/<PROJECT_SODAR_UUID> |
Method |
|
Data type |
JSON dictionary |
Example cURL:
curl -X POST -H "Content-Type: application/json" -H "Authorization: token 1234567890abcdef" --data '{"title": "Nginx echo headers", "repository": "brndnmtthws/nginx-echo-headers", "tag": "latest"}' https://kiosc.bihealth.org/containers/api/create/00000000-0000-0000-0000-000000000000
Delete Container¶
Delete container from a project given a container SODAR UUID.
URL |
/containers/api/delete/<CONTAINER_SODAR_UUID> |
Method |
|
Example cURL:
curl -X DELETE -H "Authorization: token 1234567890abcdef" http://kiosc.bihealth.org/containers/api/delete/cccccccc-cccc-cccc-cccc-cccccccccccc
List Containers¶
List all containers available in a project.
URL |
/containers/api/<PROJECT_SODAR_UUID> |
Method |
|
Example cURL:
curl -H "Authorization: token 1234567890abcdef" http://kiosc.bihealth.org/containers/api/00000000-0000-0000-0000-000000000000
Container Details¶
Show details and logs of a given container.
URL |
/containers/api/detail/<CONTAINER_SODAR_UUID> |
Method |
|
Example cURL:
curl -H "Authorization: token 1234567890abcdef" http://kiosc.bihealth.org/containers/api/detail/cccccccc-cccc-cccc-cccc-cccccccccccc
Start Container¶
Start a given container.
URL |
/containers/api/start/<CONTAINER_SODAR_UUID> |
Method |
|
Example cURL:
curl -H "Authorization: token 1234567890abcdef" http://kiosc.bihealth.org/containers/api/start/cccccccc-cccc-cccc-cccc-cccccccccccc
Stop Container¶
Stop a given container.
URL |
/containers/api/stop/<CONTAINER_SODAR_UUID> |
Method |
|
Example cURL:
curl -H "Authorization: token 1234567890abcdef" http://kiosc.bihealth.org/containers/api/stop/cccccccc-cccc-cccc-cccc-cccccccccccc