Easier docker-based server installation

CHANGELOG.md

@@ -12,6 +12,7 @@ For upgrade instructions, please check the [migration guide](MIGRATIONS.md).
 ### Added
 - Added support for datasets with more layers than the hardware can render simultaneously. The user can disable layers temporarily to control for which layers the GPU resources should be used. [#4424](https://github.com/scalableminds/webknossos/pull/4424)
 - Added a notification when downloading nml including volume that informs that the fallback data is excluded in the download. [#4413](https://github.com/scalableminds/webknossos/pull/4413)
+- Added a simpler method to install webKnossos on an own server. [#4446](https://github.com/scalableminds/webknossos/pull/4446)
 
 ### Changed
 - Made the navbar scrollable on small screens. [#4413](https://github.com/scalableminds/webknossos/pull/4413)

README.md

@@ -7,7 +7,7 @@ webKnossos is an open-source tool for annotating and exploring large 3D image da
 * Scale data reconstruction projects with crowdsourcing workflows
 * Share datasets and annotations with collaborating scientists
 
-[Start using webKnossos](https://webknossos.org) - [User Documentation](https://docs.webknossos.org) - [Contact us](mailto:[email protected])
+[Start using webKnossos](https://webknossos.org) - [On your own server](https://docs.webknossos.org/) - [User Documentation](https://docs.webknossos.org) - [Contact us](mailto:[email protected])
 
 [![](	https://img.shields.io/circleci/project/github/scalableminds/webknossos/master.svg?logo=circleci)](https://circleci.com/gh/scalableminds/webknossos)
 [![](https://img.shields.io/github/release/scalableminds/webknossos.svg)](https://github.com/scalableminds/webknossos/releases/latest)
@@ -41,13 +41,16 @@ webKnossos is an open-source tool for annotating and exploring large 3D image da
 
 [Read more about the original publication.](https://publication.webknossos.org)
 
+## Installation
+webKnossos is open-source, so you can install it on your own server.
+
+[Check out the documentation](https://docs.webknossos.org/guides/installation) for a tutorial on how to install webKnossos on your own server.
+
+For installations on localhost, please see below.
 
 ## Development installation
 ### Docker
-This is the fastest way to try webKnossos.
-Docker CE 17+ and Docker Compose 1.18+ is required.
-This is only recommended for testing.
-[For production](https://github.com/scalableminds/webknossos/wiki/Production-setup), a more elaborate setup with persistent file mounts and HTTPS reverse proxy is recommended.
+This is only recommended for local testing. Docker 17+ and Docker Compose 1.18+ are required.
 
 ```bash
 git clone -b master --depth=1 [email protected]:scalableminds/webknossos.git
@@ -56,18 +59,12 @@ docker-compose pull webknossos
 ./start-docker.sh
 ```
 
-Open your local webknossos instance on [localhost:9000](http://localhost:9000).
+Open your local webknossos instance on [localhost:9000](http://localhost:9000) and complete the onboarding steps in the browser.
+Now, you are ready to use your local webKnossos instance.
 
-See the [wiki](https://github.com/scalableminds/webknossos/wiki/Try-setup) for instructions on updating this try setup.
+See the wiki for [instructions on updating](https://github.com/scalableminds/webknossos/wiki/Development-setup) this development setup.
 
-For non-localhost deployments, make sure to use the `webknossos-public` docker-compose service and set the `PUBLIC_URI` environment variable:
-
-```bash
-git clone -b master --depth=1 [email protected]:scalableminds/webknossos.git
-cd webknossos
-docker-compose pull webknossos
-PUBLIC_URI=http://example.org:9000 docker-compose up webknossos-public
-```
+For non-localhost deployments, check out the [installation guide in the documentation](https://docs.webknossos.org/guides/installation).
 
 ### Dependencies
 

docker-compose.yml

@@ -28,8 +28,8 @@ services:
       - -Dapplication.authentication.enableDevAutoLogin=false
       # the following lines need to be adapted for non-localhost deployments
       # - -Dhttp.uri=http://example.org:9000
-      # - -Dtracingstore.publicUrl=http://example.org:9000
-      # - -Ddatastore.publicUrl=http://example.org:9000
+      # - -Dtracingstore.publicUri=http://example.org:9000
+      # - -Ddatastore.publicUri=http://example.org:9000
       # the following lines disable the integrated datastore:
       # - -Dplay.modules.enabled-="com.scalableminds.webknossos.datastore.DataStoreModule"
       # - -Ddatastore.enabled=false
@@ -40,39 +40,6 @@ services:
       - POSTGRES_URL=jdbc:postgresql://postgres/webknossos
     user: ${USER_UID:-1000}:${USER_GID:-1000}
 
-  webknossos-public:
-    build: .
-    image: scalableminds/webknossos:${DOCKER_TAG:-master}
-    ports:
-      - "9000:9000"
-    links:
-      - "fossildb-persisted:fossildb"
-      - "postgres-persisted:postgres"
-    depends_on:
-      postgres-persisted:
-        condition: service_healthy
-      fossildb-persisted:
-        condition: service_healthy
-      redis:
-        condition: service_healthy
-    command:
-      - -Dconfig.file=conf/application.conf
-      - -Djava.net.preferIPv4Stack=true
-      - -Dhttp.address=0.0.0.0
-      - -Dtracingstore.fossildb.address=fossildb
-      - -Dtracingstore.redis.address=redis
-      - -Dslick.db.url=jdbc:postgresql://postgres/webknossos
-      - -Dapplication.insertInitialData=false
-      - -Dapplication.authentication.enableDevAutoLogin=false
-      - -Dhttp.uri=${PUBLIC_URI}
-      - -Dtracingstore.publicUrl=${PUBLIC_URI}
-      - -Ddatastore.publicUrl=${PUBLIC_URI}
-    volumes:
-      - ./binaryData:/srv/webknossos/binaryData
-    environment:
-      - POSTGRES_URL=jdbc:postgresql://postgres/webknossos
-    user: ${USER_UID:-1000}:${USER_GID:-1000}
-
   webknossos-datastore:
     build: webknossos-datastore
     image: scalableminds/webknossos-datastore:${DOCKER_TAG:-master}

docs/getting_started.md

@@ -1,7 +1,7 @@
 # Getting Started
 
 Welcome to the webKnossos documentation.
-webKnossos is a tool for [exploring large-scale 3D image datasets](./tracing_ui.md), [creating versatile skeleton annotations](./skeleton_annotation.md) and [generating 3D training data for automated segmentations](./volume_annotation.md).
+webKnossos is a tool for [exploring large-scale 3D image datasets](./tracing_ui.md), [creating skeleton annotations](./skeleton_annotation.md) and [3D volume segmentations](./volume_annotation.md).
 Since it is a web-based tool, [collaboration](./sharing.md), [crowdsourcing](./tasks.md) and [publication](https://webknossos.org) is very easy.
 
 Feel free to [drop us a line](mailto:[email protected]) or [create a Pull Request](https://github.com/scalableminds/webknossos/pulls) if you have any suggestions for improving the documentation.
@@ -80,66 +80,7 @@ Feel free to explore more features of webKnossos in this documentation.
 * [Task and Project Management](./tasks.md)
 * [FAQ](./faq.md)
 
-If you need help with webKnossos, there is a [Community Support forum](https://support.webknososs.org) where members of the community and scalable minds are happy to answer your questions.
-[scalable minds](https://scalableminds.com) also offers commercial support, managed hosting and feature development services.
-[Please contact us](mailto:[email protected]) if you want to learn more.
+If you need help with webKnossos, feel free to contact us at [[email protected]](mailto:[email protected]).
+scalable minds also offers [commercial support, managed hosting and feature development services](https://webknossos.org/pricing).
 
-
-## webKnossos on Your Own Server
-webKnossos is open-source, so you can install it on your own server.
-We recommend a server with at least 4 CPU cores, 16 GB RAM, and as much disk space as you require for your datasets.
-As prerequisites, you need to install [Git](https://git-scm.com/), [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/) on your server.
-
-### Installation
-To get started, simply clone the Git repository and start the docker containers:
-
-```bash
-git clone https://github.com/scalableminds/webknossos.git
-cd webknossos
-
-docker-compose pull webknossos
-./start-docker.sh
-```
-
-This will start an instance of webKnossos on http://localhost:9000/.
-Open the URL in your browser and configure your organization (see below).
-This will create a folder for your data at `webknossos/binaryData/<organization name>`.
-
-{% hint style='info' %}
-For production setups, we recommend more elaborate configurations with a public domain name and HTTPS support.
-[Please contact us](mailto:[email protected]) if you require any assistance with your production setup.
-{% endhint %}
-
-You may also install webKnossos without Docker.
-This may be useful if you intend to develop features for webKnossos.
-Please refer to the [Code Readme](../README.md) for details.
-
-### Onboarding
-When starting with webKnossos you first need to create an organization.
-An organization represents your lab in webKnossos and handles permissions for users and datasets.
-Choose a descriptive name for your organization, e.g. "The University of Springfield", "Simpsons Lab" or "Neuroscience Department".
-
-![Create your organization](./images/onboarding_organization.png)
-
-In the onboarding flow, you are asked to create a user account for yourself.
-This will be the first user of your organization which will automatically be activated and granted admin rights.
-Make sure to enter a correct email address.
-
-![Create your first user](./images/onboarding_user.png)
-
-
-### Your First Dataset
-Now that you've completed the onboarding, you need to import a dataset.
-Without any data, webKnossos is not fun.
-
-For small datasets (max. 1GB), you can use the upload functionality provide in the web interface.
-For larger datasets, we recommend the file system upload.
-Read more about the import functionality in the [Datasets guide](./datasets.md).
-
-If you do not have a compatible dataset available, you can use one of the [sample datasets](./datasets.md#sample-datasets) for testing purposes.
-
-By default, datasets are visible to all users in your organization.
-However, webKnossos includes fine-grained permissions to assign datasets to groups of users.
-
-![Upload your first dataset](./images/onboarding_data1.png)
-![Confirm the dataset properties](./images/onboarding_data2.png)
+[Read the installation tutorial](./installation.md), if you wish to install webKnossos on your own server.

docs/hello.md

@@ -45,9 +45,8 @@ Try webKnossos on a large selection of published datasets: [https://webknossos.o
 
 webKnossos was developed by [scalable minds](https://scalableminds.com) in collaboration with the [Max Planck Institute for Brain Research](https://brain.mpg.de/connectomics).
 
-If you need help with webKnossos, there is a [Community Support forum](https://support.webknososs.org) where members of the community and scalable minds are happy to answer your questions.
-[scalable minds](https://scalableminds.com) also offers commercial support, managed hosting and feature development services.
-[Please contact us](mailto:[email protected]) if you want to learn more.
+If you need help with webKnossos, feel free to contact us at [[email protected]](mailto:[email protected]).
+scalable minds also offers [commercial support, managed hosting and feature development services](https://webknossos.org/pricing).
 
 <!--
 ## Labs that use webKnossos

docs/index.md

@@ -13,11 +13,11 @@
 * [Managing Users and Access Rights](./users.md)
 * [Managing Tasks and Projects](./tasks.md)
 * [Sharing](./sharing.md)
+* [Installation on your own Server](./installation.md)
 
 ## Reference
 * [Supported Data Formats](./data_formats.md)
 * [Keyboard Shortcuts](./keyboard_shortcuts.md)
-* [FAQ](./faq.md)
 * [Backend REST API](./rest_api.md)
 * [Code Readme](../README.md)
 * [Changelog](../CHANGELOG.md)
@@ -26,5 +26,6 @@
 * [Tooling](./tooling.md) 
 
 ## Getting Help
-* [Community Support](https://support.webknossos.org)
+* [FAQ](./faq.md)
+* [Email Support](mailto:[email protected])
 * [Commercial Support](https://scalableminds.com)

docs/installation.md

@@ -0,0 +1,82 @@
+# Installation on your own Server
+
+webKnossos is open-source, so you can install it on your own server.
+We recommend a server with at least 4 CPU cores, 16 GB RAM, and as much disk space as you require for your datasets.
+
+As prerequisites, you need to install [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/) on your server. Docker 17+ and Docker Compose 1.18+ are required.
+
+This tutorial shows how to install webKnossos on a fresh VM which is available over the public internet and has a domain name (or a subdomain) already configured.
+webKnossos will then be available with over a secured connection (HTTPS) with automatic certificate management.
+
+```bash
+# Create a new folder for webknossos
+mkdir -p /opt/webknossos
+cd /opt/webknossos
+
+# Download the docker-compose.yml for hosting
+wget https://github.com/scalableminds/webknossos/raw/master/tools/hosting/docker-compose.yml
+
+# Create the binaryData folder which will contain all your datasets
+mkdir binaryData
+
+# The binaryData folder needs to be readable/writable by user id=1000,gid=1000
+chown -R 1000:1000 binaryData
+
+# Start webKnossos and supply the PUBLIC_HOST and LETSENCRYPT_EMAIL variables
+# In addition to webKnossos, we also start an nginx proxy with automatic 
+# SSL certificate management via letsencrypt
+# Note that PUBLIC_HOST does not include http:// or https:// prefixes
+PUBLIC_HOST=webknossos.example.com [email protected] \
+docker-compose up webknossos nginx nginx-letsencrypt
+
+# Wait a couple of minutes for webKnossos to become available under your domain
+# e.g. https://webknossos.example.com
+# Set up your organization and admin account using the onboarding screens (see below)
+
+# After the initial run, you can start webKnossos in the background
+PUBLIC_HOST=webknossos.example.com [email protected] \
+docker-compose up -d webknossos nginx nginx-letsencrypt
+
+# Congratulations! Your webKnossos is now up and running.
+
+# Stop everything
+docker-compose down
+```
+
+{% hint style='info' %}
+This setup does not support regular backups or monitoring.
+Please check out [our paid service plans](https://webknossos.org/pricing) if you require any assistance with your production setup.
+{% endhint %}
+
+For installations on localhost, please refer to the [Code Readme](../README.md#docker).
+
+### Onboarding
+When starting with webKnossos you first need to create an organization.
+An organization represents your lab in webKnossos and handles permissions for users and datasets.
+Choose a descriptive name for your organization, e.g. "The University of Springfield", "Simpsons Lab" or "Neuroscience Department".
+
+![Create your organization](./images/onboarding_organization.png)
+
+In the onboarding flow, you are asked to create a user account for yourself.
+This will be the first user of your organization which will automatically be activated and granted admin rights.
+Make sure to enter a correct email address.
+
+![Create your first user](./images/onboarding_user.png)
+
+
+### Your First Dataset
+Without any data, webKnossos is not fun.
+Luckily, there are some sample datasets that you can download directly from the onboarding screens.
+Once you've completed the onboarding, you can also import your own datasets.
+
+For small datasets (max. 1GB), you can use the upload functionality provide in the web interface.
+For larger datasets, we recommend the file system upload.
+Read more about the import functionality in the [Datasets guide](./datasets.md).
+
+If you do not have a compatible dataset available, you can convert your own data using [the webKnossos cuber tool](./tooling.md#webknossos-cuber) or use one of the [sample datasets](./datasets.md#sample-datasets) for testing purposes.
+
+By default, datasets are visible to all users in your organization.
+However, webKnossos includes fine-grained permissions to assign datasets to groups of users.
+
+![Upload your first dataset](./images/onboarding_data1.png)
+![Confirm the dataset properties](./images/onboarding_data2.png)