Skip to content

Latest commit

 

History

History
155 lines (116 loc) · 5.7 KB

DEV_INSTALL.md

File metadata and controls

155 lines (116 loc) · 5.7 KB
Raw

Development installation

Docker

This is only recommended for local testing. Docker 17+ and Docker Compose 1.18+ are required.

git clone -b master --depth=1 [email protected]:scalableminds/webknossos.git
cd webknossos
docker-compose pull webknossos
./start-docker.sh

Open your local WEBKNOSSOS instance on localhost:9000 and complete the onboarding steps in the browser. Now, you are ready to use your local WEBKNOSSOS instance.

See the wiki for instructions on updating this development setup.

For non-localhost deployments, check out the installation guide in the documentation.

Dependencies

MacOS

# WEBKNOSSOS needs to be run from x86_64 environment (only applicable for arm64-based Macs)
arch -x86_64 /bin/zsh

# Install Homebrew package manager
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install git, node.js, postgres, sbt, gfind, gsed
brew install openjdk@14 openssl git node postgresql sbt findutils coreutils gnu-sed redis yarn

# Set env variables for openjdk and openssl
# You probably want to add these lines manually to avoid conflicts in your zshrc
echo 'if [ $(arch) = "i386" ]; then' >> ~/.zshrc
echo '  export PATH="/usr/local/opt/openjdk@14/bin:$PATH"' >> ~/.zshrc
echo '  export PATH="/usr/local/opt/openssl/bin:$PATH"' >> ~/.zshrc
echo '  export LDFLAGS="-L/usr/local/opt/openssl/lib"' >> ~/.zshrc
echo '  export CPPFLAGS="-I/usr/local/opt/openssl/include"' >> ~/.zshrc
echo 'fi' >> ~/.zshrc

# Start postgres and redis
brew services start postgresql
brew services start redis

# Create PostgreSQL user
createdb
psql -c "CREATE DATABASE webknossos;"
psql -c "CREATE USER postgres WITH ENCRYPTED PASSWORD 'postgres';"
psql -c "ALTER USER postgres WITH SUPERUSER;"
psql -c "GRANT ALL PRIVILEGES ON DATABASE webknossos TO postgres;"

# Checkout the WEBKNOSSOS git repository
git clone [email protected]:scalableminds/webknossos.git

Note: On arm64-based Macs (e.g. M1), you need to run WEBKNOSSOS in an x86_64 environment (Rosetta 2). In case you accidentally started WEBKNOSSOS in an arm64 environment, it is advisable to delete several caches ~/.m2, ~/ivy2, ~/.sbt, ~/.yarn-cache and run ./clean. Since Postgres and Redis are isolated processes, they can be run either from arm64 or x86_64 environments.

Ubuntu 20.04 LTS

sudo apt install -y curl ca-certificates wget
# Adding repositories for nodejs, sbt and yarn
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
echo "deb https://repo.scala-sbt.org/scalasbt/debian all main" | sudo tee /etc/apt/sources.list.d/sbt.list
echo "deb https://repo.scala-sbt.org/scalasbt/debian /" | sudo tee /etc/apt/sources.list.d/sbt_old.list
curl -sL "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x2EE0EA64E40A89B84B2DF73499E82A75642AC823" | sudo apt-key add
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

sudo apt update
sudo apt install -y nodejs git postgresql postgresql-client scala sbt openjdk-14-jdk yarn redis-server build-essential libblosc1

# Assign a password to PostgreSQL user
sudo -u postgres psql -c "ALTER USER postgres WITH ENCRYPTED PASSWORD 'postgres';"
# Clone the git repo to the current directory
git clone -b master --depth=1 https://github.com/scalableminds/webknossos.git

If you already have a different Java version installed, set the default version to Java 14:

  • run sudo update-alternatives --config java
  • when prompted, select the desired version

On older Ubuntu distributions: Please make sure to have the correct versions of node, PostgreSQL and java installed.

Manual Installation

Java
  • Install Java JDK 14 (from Oracle or OpenJDK)
  • make sure JAVA_HOME and JDK_HOME are set and PATH contains the path to JDK
sbt

See: http://www.scala-sbt.org/release/docs/Getting-Started/Setup.html

PostgreSQL
Redis
node.js & yarn

Run locally

First, install all frontend dependencies via

yarn install

Note: During this installation step, it might happen that the module gl cannot be installed correctly. As this module is only used for testing WEBKNOSSOS, you can safely ignore this error.

To start WEBKNOSSOS, use

yarn start

This will fetch all Scala, Java and node dependencies and run the application on Port 9000. Make sure that the PostgreSQL and Redis services are running before you start the application.

Upgrades

For upgrades, please check the changelog & migration guide.

Tests

# Frontend linting
yarn run lint

# Format frontend code
yarn format-frontend

# Format backend code
yarn format-backend

# Frontend type checking
yarn flow

# Frontend tests
yarn test-verbose

# End-to-end tests
docker-compose run e2e-tests