Installation and configuration

The code for Kiosc is hosted on GitHub. Kiosc itself is a python web app built using the Django framework and in order to function properly it requires additional components. Thus, the easiest and most recommended way to install Kiosc is through Docker Compose. If you are not familiar with Docker or Docker Compose, head to this short guide for a quick introduction. If you don’t want to use Docker Compose, or if you want to contribute to the Kiosc development, the manual installation method is described in the Development Environment section.

Installation via Docker Compose

We provide a separate repository containing the master docker-compose.yml file for Kiosc. It encloses all the apps and services needed to deploy and develop Kiosc. We crafted this Docker Compose so that it uses the latest stable Kiosc image, which is itself built from the main kiosc-server repository and uploaded to the GitHub Container Registry (ghcr). Here we describe how to deploying Kiosc using the kiosc-docker-compose repository.

Start by cloning the repository:

$ git clone https://github.com/bihealth/kiosc-docker-compose.git
$ cd kiosc-docker-compose

First, initialize the required folder structure. Among others, the database will be stored in there, so that 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 various settings which affect Django, Kiosc, and SODAR Core. Most of them are set to reasonable defaults, but please go through them and change them to values that work in your setup. For example, changing the DJANGO_SECRET_KEY is a good idea:

DJANGO_SECRET_KEY=CHANGEMEchangemeCHANGEMEchangemeCHANGEMEchangemeCH

See “Configuration” below for a detailed description of the main options. When done, start the Docker containers:

$ docker compose --profile=deploy up

Before you can access Kiosc, you need to create at least one superuser. To do so, run this command and follow the interactive prompts:

$ docker compose exec kiosc-web ./manage.py createsuperuser

At this point, you may create local user accounts or connect Kiosc to an existing authentication provider, such as LDAP or OIDC. See the Configuration section for further instructions.

The Kiosc installation can now be reached by accessing https://localhost:443 with your browser. You should be able to access with the superuser account you just created, or as any of the regular users, if you have set them up.

Configuration

Kiosc can be configured via environment variables. The Kiosc container running in our Docker Compose reads the environment variables from the .env file, which is preconfigured for running a demo instance, but you’ll need to make some tweaks to adapt it to your specific requirements.

Here is a description of the most important options.

NETWORK_BRIDGE_NAME

Name of the network where the Kiosc web server will run.

KIOSC_SERVER_VERSION

Version tag for the Kiosc Docker image.

REDIS_VERSION

Version tag for the redis Docker image.

TRAEFIK_VERSION

Version tag for the traefik Docker image.

KIOSC_DATABASE_URL

URL of the database used by Kiosc (do not change this unless you know what you are doing).

KIOSC_DJANGO_ALLOWED_HOSTS

Hosts from which connections are accepted.

KIOSC_DJANGO_SECRET_KEY

Used to secure signed data, please change the value and never share it with anyone.

KIOSC_DJANGO_SETTINGS_MODULE

Settings module used for the Kiosc Django site.

KIOSC_EMBEDDED_FILES

Enable the feature to upload small files to Kiosc that can be served to the Docker containers.

KIOSC_CELERY_BROKER_URL

Used by Celery for keeping track of background tasks.

KIOSC_UVICORN_WORKERS

Number of processes used to handle incoming connections by the web server.

KIOSC_ENABLE_LDAP

Whether to enable LDAP authentication.

KIOSC_ENABLE_LDAP_SECONDARY

Whether to enable the secondary LDAP server for authentication.

KIOSC_ENABLE_OIDC

Whether to enable OIDC authentication.

KIOSC_AXES_ENABLED

Used to enable django-axes, which logs failed login attempts and prevents brute-force attacks.

KIOSC_SITE_TITLE

The title of your website.

KIOSC_SITE_SUBTITLE

The subtitle of your website.

KIOSC_SITE_INSTANCE_TITLE

May be used to e.g. differentiate between site versions used for deployment or staging, use in different organizations, etc.

KIOSC_LOGGING_LEVEL

Logging level used througout Kiosc apps.

KIOSC_LOGGING_FILE_PATH

Logging file used througout Kiosc apps.

Note

The list of settings for projectroles and the other SODAR Core apps is not exhaustive. Consult the SODAR Core documentation to find out more: https://sodar-core.readthedocs.io/en/latest/app_projectroles_settings.html

Configuring authentication may require a special set up, since it will be highly dependent on the environment where Kiosc is hosted. Local users can be created from the Django admin page or with the manage.py script (see the Django docs). For federated authentication through LDAP or OIDC, refer to the relevant documentation in SODAR Core for more details.

Additionally, there are some environment variables which affect specifically the Kiosc apps (as opposed to the whole website). These should also be set in the .env file and are described in the following table.

Environment variable	Default	Description
KIOSC_NETWORK_MODE	docker-shared	Can be host or docker-shared. Indicates whether installation runs in a Docker environment or not.
KIOSC_DOCKER_NETWORK	kiosc-net	Name of the Docker network for the users Docker containers.
KIOSC_DOCKER_WEB_SERVER	kiosc-web	Name of the web server Docker container.
KIOSC_DOCKER_ACTION_MIN_DELAY	1	Min delay in seconds for Docker container actions.
KIOSC_DOCKER_MAX_INACTIVITY	7	Max threshold for inactive running Docker containers in days.
KIOSC_EMBEDDED_FILES	True	Enable the feature to upload small files to Kiosc that can be served to the Docker containers.

Creating a SODAR site in TARGET mode

Kiosc can be run in TARGET mode, drawing projects and users from an upstream SODAR instance. Note that this requires an existing SODAR instance which is running in SOURCE mode and that the Kiosc instance is registered to it. Further description of the SOURCE/TARGET mode can be found in the SODAR Core documentation.

To enable TARGET mode in your site, set PROJECTROLES_SITE_MODE=TARGET and add the following environment variables, changing their value as needed:

# Allow creation of local projects
PROJECTROLES_TARGET_CREATE=1
# Enable synchronization with the source site
PROJECTROLES_TARGET_SYNC_ENABLE=1
# Time interval in minutes for synchronization
PROJECTROLES_TARGET_SYNC_INTERVAL=5