Used BioNGFF Viewer instead of Vizarr

Author: zonia3000

.env.example

@@ -2,6 +2,6 @@ PORT=3000
 BIND_ADDRESS=0.0.0.0
 FRACTAL_SERVER_URL=http://localhost:8000
 BASE_PATH=/data
-VIZARR_STATIC_FILES_PATH=/path/to/vizarr/dist
+VIEWER_STATIC_FILES_PATH=/path/to/biongff-viewer/sites/app/dist
 AUTHORIZATION_SCHEME=fractal-server
 CACHE_EXPIRATION_TIME=60

.github/workflows/github_release.yaml

@@ -10,7 +10,7 @@ on:
       - 'v[0-9]+.[0-9]+.[0-9]+rc[0-9]+'
 
 jobs:
-  build-vizarr:
+  build-viewer:
     runs-on: ubuntu-latest
 
     steps:
@@ -23,33 +23,35 @@ jobs:
           node-version: 20
           cache: npm
 
-      - name: Clone vizarr
-        run: git clone https://github.com/fractal-analytics-platform/vizarr.git
+      - name: Clone BioNGFF Viewer
+        run: git clone https://github.com/BioNGFF/biongff-viewer.git
 
-      - name: Checkout vizarr commit
+      - name: Init git submodules
         run: |
-          cd vizarr
-          git checkout a04555b6557a42f4ee627850bad4e6b3fe8c8fe1
-
-      - name: Install dependencies
-        run: |
-          cd vizarr
-          npx -y pnpm install
+          cd biongff-viewer
+          sed -i 's|hms-dbmi|fractal-analytics-platform|g' .gitmodules
+          printf "\tbranch = workaround-labels-bug\n" >> .gitmodules
+          git submodule init
+          git submodule update
 
       - name: Generate build artifacts
         run: |
-          cd vizarr
-          npx pnpm run build
+          cd biongff-viewer
+          npx pnpm install
+          npx pnpm --filter viewer run build
+          npx pnpm --filter anndata-zarr run build
+          npx pnpm --filter app run build --base /data/viewer
 
       - name: Generate the package
         run: |
-          cd vizarr
-          tar -czpf fractal-vizarr-${{ github.ref_name }}.tar.gz dist LICENSE
+          cd biongff-viewer
+          mv sites/app/dist .
+          tar -czpf fractal-viewer-${{ github.ref_name }}.tar.gz dist LICENSE
 
       - name: Release
         uses: softprops/[email protected]
         with:
-          files: vizarr/fractal-vizarr-${{ github.ref_name }}.tar.gz
+          files: biongff-viewer/fractal-viewer-${{ github.ref_name }}.tar.gz
 
   build-server:
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -2,6 +2,7 @@ Note: Numbers like (#123) point to closed Pull Requests on the fractal-vizarr-vi
 
 # Unreleased
 
+* Used BioNGFF Viewer instead of Vizarr (\#69).
 * Added workaround to fix labels bug in most recent Chrome versions (\#68);
 
 # 0.4.0

Dockerfile

@@ -2,12 +2,20 @@ FROM node:20
 
 WORKDIR /
 
-RUN git clone https://github.com/hms-dbmi/vizarr.git
-WORKDIR /vizarr
+RUN git clone https://github.com/BioNGFF/biongff-viewer.git
+WORKDIR /biongff-viewer
+
+# modifying .gitmodules to use our vizarr fork
+RUN sed -i 's|hms-dbmi|fractal-analytics-platform|g' .gitmodules
+RUN printf "\tbranch = workaround-labels-bug\n" >> .gitmodules
+
+RUN git submodule init
+RUN git submodule update
 
-RUN git checkout eb2b77fed92a08c78c5770144bc7ccf19e9c7658
 RUN npx -y pnpm install
-RUN npx pnpm run build
+RUN npx pnpm --filter viewer run build
+RUN npx pnpm --filter anndata-zarr run build
+RUN npx pnpm --filter app run build --base /data/viewer
 
 RUN mkdir /fractal-data
 
@@ -20,6 +28,6 @@ ADD tsconfig.json .
 RUN npm install
 RUN npm run build
 
-ENV VIZARR_STATIC_FILES_PATH=/vizarr/dist
+ENV VIEWER_STATIC_FILES_PATH=/biongff-viewer/sites/app/dist
 
 CMD ["node", "/fractal-data/dist/app.js"]

README.md

@@ -8,9 +8,9 @@ The application has 3 endpoints:
 
 - the endpoint `/files/{path-to-zarr}`, that serves the content of Zarr files checking user authorization.
 - the endpoint `/alive`, that returns the status of the service.
-- the optional endpoint `/vizarr`, that serves vizarr static files when the `VIZARR_STATIC_FILES_PATH` environment variable is set.
+- the optional endpoint `/viewer`, that serves [BioNGFF Viewer](https://github.com/BioNGFF/biongff-viewer) static files when the `VIEWER_STATIC_FILES_PATH` environment variable is set.
 
-> To run fractal-data you need to have an active instance of `fractal-server` and an active instance of `fractal-web`. You need to log-in to `fractal-web` from the browser using a user that has been authorized to see the vizarr files. Details about authorization are explained in the next section.
+> To run fractal-data you need to have an active instance of `fractal-server` and an active instance of `fractal-web`. You need to log-in to `fractal-web` from the browser using a user that has been authorized to see the viewer files. Details about authorization are explained in the next section.
 
 ## How it works
 
@@ -36,25 +36,25 @@ If different subdomains are used for fractal-web and fractal-data, the fractal-w
 
 Example: if fractal-data is served on `fractal-data.mydomain.net` and fractal-web is served on `fractal-web.mydomain.net`, then `AUTH_COOKIE_DOMAIN` must be set to `mydomain.net`.
 
-If we need to serve these services on different domains a different authentication strategy has to be chosen, for example something token-based. That results in a more complicated setup, possibly involving some extra changes on the vizarr code.
+If we need to serve these services on different domains a different authentication strategy has to be chosen, for example something token-based. That results in a more complicated setup, possibly involving some extra changes on the viewer code.
 
 ## Install fractal-data from release packages
 
-The release packages include the Node.js server and the Vizarr static files. Starting from version 0.1.3, fractal-data releases provide tar.gz files containing built Vizarr static files and a package of built files for each supported node version.
+The release packages include the Node.js server and the BioNGFF Viewer static files. Starting from version 0.1.3, fractal-data releases provide tar.gz files containing built BioNGFF Viewer static files and a package of built files for each supported node version.
 
-### Install Vizarr static files
+### Install BioNGFF Viewer static files
 
-Vizarr static files can be served using any server like Apache or Ngnix.
+BioNGFF Viewer static files can be served using any server like Apache or Ngnix.
 
-Create a dedicated folder for vizarr on your server. For Apache, it could be `/var/www/html/vizarr`.
+Create a dedicated folder for the viewer on your server. For Apache, it could be `/var/www/html/viewer`.
 
-Navigate to the directory and extract the Vizarr static files:
+Navigate to the directory and extract the BioNGFF Viewer static files:
 
 ```
-FRACTAL_DATA_VERSION=0.4.0 && wget -qO- "https://github.com/fractal-analytics-platform/fractal-data/releases/download/v${FRACTAL_DATA_VERSION}/fractal-vizarr-v${FRACTAL_DATA_VERSION}.tar.gz" | tar -xz
+FRACTAL_DATA_VERSION=0.4.0 && wget -qO- "https://github.com/fractal-analytics-platform/fractal-data/releases/download/v${FRACTAL_DATA_VERSION}/fractal-viewer-v${FRACTAL_DATA_VERSION}.tar.gz" | tar -xz
 ```
 
-**Note**: this will unpack in the current working directory the vizarr `dist` folder.
+**Note**: this will unpack in the current working directory the viewer `dist` folder.
 
 ### Install fractal-data Node.js server files
 
@@ -73,7 +73,7 @@ To start the application installed in this way see the section [Run fractal-data
 - `PORT`: the port where fractal-data app is served;
 - `BIND_ADDRESS`: specifies the IP address for the server to bind to; use `0.0.0.0` (IPv4) or `::` (IPv6) to listen on all interfaces, `127.0.0.1` (IPv4) or `::1` (IPv6) for localhost only; the default value is `0.0.0.0`;
 - `FRACTAL_SERVER_URL`: the base URL of fractal-server;
-- `VIZARR_STATIC_FILES_PATH`: path to the files generated running `npm run build` in Vizarr source folder; this variable is optional and, if present, it will be used to serve Vizarr static files from the `/vizarr` endpoint;
+- `VIEWER_STATIC_FILES_PATH`: path to the files generated by building the BioNGFF Viewer; this variable is optional and, if present, it will be used to serve the BioNGFF Viewer static files from the `/viewer` endpoint;
 - `BASE_PATH`: base path of fractal-data application;
 - `AUTHORIZATION_SCHEME`: defines how the service verifies user authorization. The following options are available:
   - `fractal-server`: the paths that can be accessed by each user are retrieved calling fractal-server API.
@@ -189,25 +189,34 @@ npm install
 
 Copy the file `.env.example` to `.env` and customize values for the environment variables.
 
-### Vizarr setup
+### BioNGFF Viewer setup
 
-In order to display a proper error message related to the missing authorization it is necessary to use a modified version of vizarr.
+BioNGFF Viewer depends on Vizarr and we are using a custom fork of Vizarr, to fix some issues. The .gitmodules file of the BioNGFF Viewer needs to be changed to reference our Vizarr fork.
 
-> Note: for simplicity, we assume that `fractal-data` and `vizarr` are subfolders of the same folder:
+> Note: for simplicity, we assume that `fractal-data` and `biongff-viewer` are subfolders of the same folder:
 
 ```bash
-git clone https://github.com/hms-dbmi/vizarr.git
-cd vizarr
-git checkout eb2b77fed92a08c78c5770144bc7ccf19e9c7658
+git clone https://github.com/BioNGFF/biongff-viewer.git
+cd biongff-viewer
+
+# modifying .gitmodules to use our vizarr fork
+sed -i 's|hms-dbmi|fractal-analytics-platform|g' .gitmodules
+printf "\tbranch = workaround-labels-bug\n" >> .gitmodules
+
+git submodule init
+git submodule update
+
 npx pnpm install
-npx pnpm run build
+npx pnpm --filter viewer run build
+npx pnpm --filter anndata-zarr run build
+npx pnpm --filter app run build --base /data/viewer
 ```
 
-The output is located in the `dist` folder.
+The output is located in the `sites/app/dist` folder.
 
 ### Run fractal-data
 
-Then go back to fractal-data folder and run `npm run start` to start the project. The server will start on port 3000. Remember to set the `VIZARR_STATIC_FILES_PATH`, to serve Vizarr static files from the `/vizarr` endpoint. Vizarr static files need to be served from the same port and domain of the fractal-data service, otherwise you will encounter CORS issues.
+Then go back to fractal-data folder and run `npm run start` to start the project. The server will start on port 3000. Remember to set the `VIEWER_STATIC_FILES_PATH`, to serve BioNGFF Viewer static files from the `/viewer` endpoint. BioNGFF Viewer static files need to be served from the same port and domain of the fractal-data service, otherwise you will encounter CORS issues.
 
 ### Alive endpoint
 

src/app.ts

@@ -29,11 +29,11 @@ app.use(`${config.basePath}alive`, async function (req, res) {
   await aliveEndpoint(req, res);
 });
 
-// Serving Vizarr static files
-if (config.vizarrStaticFilesPath) {
+// Serving viewer static files
+if (config.viewerStaticFilesPath) {
   app.use(
-    `${config.basePath}vizarr`,
-    express.static(config.vizarrStaticFilesPath)
+    `${config.basePath}viewer`,
+    express.static(config.viewerStaticFilesPath)
   );
 }
 

src/config.ts

@@ -59,7 +59,7 @@ function loadConfig(): Config {
     basePath += "/";
   }
 
-  const vizarrStaticFilesPath = process.env.VIZARR_STATIC_FILES_PATH;
+  const viewerStaticFilesPath = process.env.VIEWER_STATIC_FILES_PATH;
 
   logger.debug("PORT: %s", port);
   logger.debug("BIND_ADDRESS: %s", bindAddress);
@@ -68,8 +68,8 @@ function loadConfig(): Config {
   logger.debug("AUTHORIZATION_SCHEME: %s", authorizationScheme);
   logger.debug("CACHE_EXPIRATION_TIME: %d", cacheExpirationTime);
 
-  if (vizarrStaticFilesPath) {
-    logger.debug("VIZARR_STATIC_FILES_PATH: %s", vizarrStaticFilesPath);
+  if (viewerStaticFilesPath) {
+    logger.debug("VIEWER_STATIC_FILES_PATH: %s", viewerStaticFilesPath);
   }
 
   return {
@@ -81,7 +81,7 @@ function loadConfig(): Config {
     cacheExpirationTime,
     testingUsername,
     testingPassword,
-    vizarrStaticFilesPath,
+    viewerStaticFilesPath,
   };
 }
 

src/types.ts

@@ -12,7 +12,7 @@ export type Config = {
   cacheExpirationTime: number;
   testingUsername: string | null;
   testingPassword: string | null;
-  vizarrStaticFilesPath: string | undefined;
+  viewerStaticFilesPath: string | undefined;
 };
 
 export type User = {