Production setup

Setting up webKnossos requires knowledge about creating and maintaining server infrastructure. This is a high-level guide. Please contact us to discuss specific issues.

We recommend deploying webKnossos with Docker. On our systems we run webKnossos on a Kubernetes cluster.

Installation

• Install latest Docker engine and Docker compose
• Get a (sub)domain to run webKnossos on
• Get a SSL certificate for the (sub)domain
• Create binaryData that is owned and writable by (uid=1000 gid=1000)
• Deploy a PostgreSQL instance
• Deploy a FossilDB instance
• Create a configuration file (see below for an example)
• Create a docker container
  • Mounting the necessary volumes (i.e., binaryData, tracingData, deployment.conf)
  • Run the webKnossos command (see below for an example)
  • Run as user 1000:1000 (if you use a different user, make sure that binaryData is writable)
  • Exposes port 9000
• Deploy a reverse proxy that points to port 9000

Setup

• webKnossos automatically creates the schema in PostgreSQL
• Create an organization (append a row directly in PostgreSQL)
• Create dataset folder for your organisation (i.e., binaryData/<organisation>)
• Register your first user. Activate and set as admin directly in PostgreSQL
• Create your other users
• Upload datasets
• Don't forget to create a backup cronjob for your FossilDB and PostgreSQL instances

Run command

bin/oxalis \
  -J-Xmx10G -J-Xms1G \
  -Dlogger.file=conf/application-logger.xml \
  -Dconfig.file=conf/deployment.conf \
  -Djava.io.tmpdir=disk

deployment.conf

include "application.conf"
http {
  uri = "https://TODO"
  address = "0.0.0.0"
  port = 9000
}

datastore {
  enabled = true
  name = "localhost"
  debugMode = false
  oxalis{
    uri = "localhost:"${http.port}
    secured = false
  }
  fossildb.address = "TODO"
}
actor {
  defaultTimeout = 5
}
application {
  authentication {
    enableDevAutoAdmin = false
    enableDevAutoLogin = false
    enableDevAutoVerify = true
  }
  insertInitialData = false
  secret = "TODO: Random key"
}
braingames {
  binary {
    cacheMaxSize = 40
  }
}
braintracing {
  newuserlist = "TODO: Email address"
}
datastore {
  key = "TODO: Random key"
}
google {
  analytics {
    trackingID = "TODO: UA-XXXXXXXX-X"
  }
}
mail {
  enabled = true
  smtp {
    auth = true
    host = "TODO"
    pass = "TODO"
    port = 587
    tls = true
    user = "TODO"
  }
}

PostgreSQL configuration

For SSD servers with ≥32 GB RAM and ≥4 Cores

checkpoint_completion_target=0.9
effective_cache_size=32GB
maintenance_work_mem=8GB
max_parallel_workers_per_gather=4
random_page_cost=1
shared_buffers=16GB
work_mem=2GB