K-Link/K-Box Setup

Install K-Link or a K-Box on your machine

This is a pre-release software. It will become the next setup, the k-setup

Prerequisites

  • Docker 1.8.0+
  • Docker Compose v 1.4.0

Installation

The setup comes in an executable for Linux, MacOS and Windows. This executable will
help you generate the Docker Compose file to start all the services needed for a K-Link Network or a K-Box installation.

Precompiled Binaries

download the setup version for your OS (currently only 64bit OSes are supported)

From source

You can also build the binaries using node/npm:

npm install -q

npm run production
# (the k-setup binaries for all platforms will be built in ./dist/ )

Quick Start

1. generating a template

To generate the base configuration for the setup type you want to perform:

k-setup template <type>

where <type> can be:

  • k-link
  • k-box

in case you want to access your k-box from the internet, all traffic
should be encrypted. Using the --tls flag will enable a reverse proxy
that uses LetsEncrypt to automatically
set up a encrypted connection. In case the domain can not be reached
from the internet (e.g. local hosts like klink.local), a self-signed
certificate will be used instead.

in this case the command would be:

k-setup template k-box --tls

2. customizing configuration

Open the generated configuration.yml file and change the domain name and the email address.
The domain name is the location you will use to access all the services.

for a detailed explanation of the configuration file, see below.

3. validating configuration file (optional)

You can check if the data entered in the configuration.yml will result in a valid deployment file

k-setup validate <configuration>

4. generating the docker-compose deployment file

after customization, a deployment file can be generated from the configuration file

k-setup deploy ./configuration.yml

5. deploy using docker-compose

now everything can be started with Docker Compose

docker-compose up -d

CLI

The k-setup executable has 3 main commands:

  1. validate
  2. template
  3. deploy

Beside those commands you can execute the k-setup with:

  • -V or --version to get the version of the executable
  • --help to get information about the commands available

validate

Verify that the given <configuration> file is valid

k-setup validate <configuration>

Arguments:

  • <configuration> (required) The path to the configuration file to validate

template

Generate a default configuration file for the specified environment

k-setup template <env>

Arguments:

  • <env> (required) the environment type to generate. Accepted environments are: k-box, k-link

Options:

  • --tls Include the configuration for a tls enabled reverse proxy.
    LetsEncrypt will be used to automatically
    set up a encrypted connection. In case the domain can not be reached
    from the internet (e.g. local hosts like klink.local), a self-signed
    certificate will be used instead.
  • --file <name> The name to use for the configuration file. Default configuration.yml

deploy

Load the given configuration file and generate the deployment script as a docker-compose.yml file

k-setup deploy <configuration>

Arguments:

  • <configuration> (required) The path to the configuration file to deploy

The configuration file, explained

to be documented, for now please check
issue 328

By editing the configuration file, you can influence the installation
process. By default you will only need to change the domain and email
sections to get a working installation.

However, more changes might be required if you already have an existing
installation that you want to re-use

# Version number of the configuration file
version: 1

# Which service this config-file is for; either k-link or k-box
type: k-box

# Name of the institution deploying this k-box, it will be used as the
# core-id.
institution: KLINK

# Timezone this k-box will be deployed for, changes how times are
# displayed. options here:
# https://secure.php.net/manual/en/timezones.php
timezone: Europe/Berlin

# domain this k-box will be deployed on. This has to be a resolvable
# address of the server, since links and redirects will be generated for
# this hostname. (for testing purposes, "localhost" can be used.)
domain: k-box.local

# email address for the administrator. This value is currently ignored.
email: root@example.com

# storage locations for the data. these directories should be backed up
# regulary.
storage:
  k-search-logs: ./storage/k-search/logs
  k-search-thumbnails: ./storage/k-search/data
  k-search-index: ./storage/k-search/index
  k-box-data: ./storage/k-box/data
  k-box-database: ./storage/k-box/database

# Services provide the option to fine-tune service behavior
services:
  k-search:
    version: 2.6.2
    engine: 0.1.0
    appkey: '&#mK)GFhXAfvaZlU^Ok212toVAy(IqS*'
    authentication:
      users: ./config/k-search/users.yml
      tokens: ./config/k-search/tokens.yml
  k-box:
    # this will be the username used for login
    username: admin@klink.local
    # this will be the password used for login
    password: 'FzPw#)gw'
    version: 0.17.1
    appkey: fa)pCvjEm8&CsD2f
    k-search:
      username: admin
      password: 'Q![%x![4'
  database:
    name: dms
    prefix: dms_
    username: dms
    root_password: H9L5PrXe5vo45*8z
    password: hVs0V%O3M$Xrj&(Y

Upgrading from a previous version of the setup?

The procedure is documented in upgrade.md.