Skip to content

Latest commit

 

History

History
177 lines (121 loc) · 6.2 KB

DEV_INSTALL.md

File metadata and controls

177 lines (121 loc) · 6.2 KB

Development installation

Dependencies

MacOS

# 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, draco
brew install openjdk draco openssl git node postgresql sbt findutils coreutils gnu-sed redis brotli wget

# Set env variables for openjdk and openssl
# You probably want to add these lines manually to avoid conflicts in your zshrc
echo 'export JAVA_HOME=/opt/homebrew/opt/openjdk/libexec/openjdk.jdk/Contents/Home' >> ~/.zshrc
echo 'export PATH="/opt/homebrew/opt/openjdk/bin:$PATH"' >> ~/.zshrc
echo 'export PATH="/opt/homebrew/opt/openssl/bin:$PATH"' >> ~/.zshrc
echo 'export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"' >> ~/.zshrc
echo 'export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"' >> ~/.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;"

# Enable corepack for nodeJs and yarn
corepack enable

# 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 22.04 LTS

sudo apt update
sudo apt install -y curl ca-certificates wget git postgresql postgresql-client unzip zip redis-server build-essential libbrotli1 libdraco-dev cmake

# Install nvm, node 22
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

 # Install sdkman, java, scala and sbt
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install scala 2.13.12
sdk install sbt
sdk install java 21.0.2-tem
# Source sdkman-init.sh again to load environment variables like JAVA_HOME
source "$HOME/.sdkman/bin/sdkman-init.sh"

# 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 [email protected]:scalableminds/webknossos.git
cd webknossos

# Enable node corepack to select the right yarn, install node packages
corepack enable
yarn install

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

Manual Installation

Java

  • Install Java JDK 21 (from Oracle or OpenJDK)
  • make sure JAVA_HOME and JDK_HOME are set and PATH contains the path to JDK
  • Also see SDKMAN! for a convenient way to install and manage Java versions

sbt

PostgreSQL

Redis

node.js & yarn

  • Install node from https://nodejs.org/
  • node version 22+ is required
  • Use corepack to install yarn
  • corepack enable&& yarn install

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.

Note: If you are getting node version incompatibility errors, it is usually safe to call yarn with --ignore-engines.

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

When pulling newer versions, please check the changelog (released and unreleased) and migration guide (released and unreleased).

Note: If the postgres schema changed, you may see compilation errors in the form of value * is not a member of com.scalableminds.webknossos.schema.Tables.* – run the SQL migrations from the migration guide or reset your database with yarn refresh-schema and restart the server to fix those.

Tests and Tools

# Frontend linting & Formatting
yarn fix-frontend

# Format backend code
yarn format-backend

# Frontend type checking
yarn typecheck

# Frontend tests
yarn test

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

For more commands, see the scripts section in package.json.

Passkeys

Passkeys are only supported with HTTPS. You can generate self-signed certificates for local development with ./tools/proxy/gen-ssl-dev-certs.sh.

You must also update conf/application.conf:

  • Set http.uri to https://localhost:<port>
  • Set features.passkeysEnabled to true

You must also update your vite.config.ts: Comment in the server.https related lines.