aiiinotate 0.2.6 → 0.2.8

package/README.md

@@ -8,23 +8,16 @@ aiiinotate is a fast and lightweight annotation server for IIIF. It relies on `n
 
 ### Install 
 
-TODO: install mongodb
+1. **Install mongodb**.
+    - see [dev installation script for help](./scripts/setup_mongodb.sh)
+    - checkout the [official installation guide](https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-ubuntu/#std-label-install-mdb-community-ubuntu)
 
+2. **Install aiiinotate**
 ```bash
 npm install aiiinotate
 ```
 
-### Usage
-
-The base command is:
-
-```bash
-aiiinotate --env <path-to-your-env-file> -- <command>
-```
-
-It will give full access to the CLI interface of Aiiinotate.
-
-####  Run the app 
+### Setup the app 
 
 0. **Setup your `.env`** file after [.env.template](./config/.env.template).
 
@@ -40,7 +33,11 @@ sudo systemctl start mongod
 aiiinotate --env <path-to-your-env-file> -- migrate apply
 ```
 
-3. **Run**
+### Usage
+
+All commands are accessible through a CLI (`./src/cli`).
+
+#### Run the app 
 
 ```bash
 aiiinotate --env <path-to-your-env-file> -- serve prod
@@ -48,9 +45,17 @@ aiiinotate --env <path-to-your-env-file> -- serve prod
 aiiinotate --env <path-to-your-env-file> -- serve dev
 ```
 
-#### Import data
+#### Run administration commands
 
-TODO
+The base command is:
+
+```bash
+aiiinotate --env <path-to-your-env-file> -- <command>
+```
+
+It will give full access to the CLI interface of Aiiinotate. Run `aiiinotate --help` for more info.
+
+1. Import data - TODO
 
 ---
 
@@ -59,12 +64,25 @@ TODO
 ### Install 
 
 ```bash
-bash setup.sh
+# clone the repo
+git clone git@github.com:Aikon-platform/aiiinotate.git
+
+# move inside it
+cd aiiinotate
+
+# install mongodb
+bash ./scripts/setup_mongodb.sh
+
+# install node
+bash ./scripts/setup_node.sh
+
+# install dependencies
+npm i
 ```
 
-### Usage
+### Setup
 
-#### First steps
+After installing, some setup must be done
 
 0. **Setup your `.env`** file after [.env.template](./config/.env.template) and place it at `./config/.env`.
 
@@ -74,7 +92,15 @@ bash setup.sh
 sudo systemctl start mongod
 ```
 
-#### Run commands
+2. **Configure the database**
+
+```bash
+npm run migrate apply
+```
+
+### Usage
+
+Remember to have your `mongodb` service running: `sudo systemctl start mongod` !
 
 - **Start the app**
 
@@ -98,7 +124,7 @@ npm cli
 
 ```bash
 # create a new migration. NOTE: the `--` is necessary !
-npm run migrate make -- --migrate-name <your migration name>
+npm run migrate make -- --migration-name <your migration name>
 
 # apply all pending migrations
 npm run migrate apply
@@ -107,7 +133,7 @@ npm run migrate apply
 npm run migrate revert
 
 # revert all migrations
-npm run migrate revert-all)
+npm run migrate revert-all
 ```
 
 ---

package/cli/utils/mongoClient.js

@@ -6,7 +6,10 @@ import { MongoClient } from "mongodb";
  */
 function loadMongoClient() {
   try {
-    const client = new MongoClient(process.env.MONGODB_CONNSTRING);
+    const client = new MongoClient(
+      process.env.MONGODB_CONNSTRING,
+      { useUnifiedTopology: false, useNewUrlParser: false }
+    );
     client.db(process.env.MONGODB_DB);
     return client;
   } catch (err) {

package/docker/Dockerfile

@@ -0,0 +1,23 @@
+# syntax=docker/dockerfile:1
+FROM node:23.11 AS aiiinotate
+
+# aiiinotate port
+ARG PORT=4444
+ENV PORT=${PORT}
+
+# set up environment
+ENV TERM=linux
+SHELL ["/bin/bash", "-c"]
+
+# root of the app in the docker container
+WORKDIR /aiiinotate
+# copy the .env in the docker container
+COPY ./config/.env /aiiinotate/.env
+# install the app as an NPM library
+RUN npm i -g aiiinotate
+# migrate the database
+RUN  aiiinotate --env=/aiiinotate/.env -- migrate apply
+# expose the used port
+EXPOSE $PORT
+# start the app
+CMD aiiinotate --env=/aiiinotate/.env -- serve prod

package/docker/docker-compose.yaml

@@ -0,0 +1,21 @@
+services:
+  mongo:
+    image: mongo:8
+    restart: always
+    # environment:
+    #   MONGO_INITDB_ROOT_USERNAME: root
+    #   MONGO_INITDB_ROOT_PASSWORD: example
+
+  web:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+      args:
+        PORT: ${APP_PORT}
+    env_file:
+      - ../config/.env
+    ports:
+      - ${APP_PORT}:${APP_PORT}
+    depends_on:
+      - mongo
+    restart: always

package/migrations/baseConfig.js

@@ -24,8 +24,8 @@ export default (config) => ({
     databaseName: config.dbName,
 
     options: {
-      useNewUrlParser: true, // removes a deprecation warning when connecting
-      useUnifiedTopology: true, // removes a deprecating warning when connecting
+      // useNewUrlParser: true, // removes a deprecation warning when connecting
+      // useUnifiedTopology: true, // removes a deprecating warning when connecting
       //   connectTimeoutMS: 3600000, // increase connection timeout to 1 hour
       //   socketTimeoutMS: 3600000, // increase socket timeout to 1 hour
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiiinotate",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "a fast IIIF-compliant annotation server",
   "main": "./cli/index.js",
   "type": "module",

package/_run.sh

@@ -1,67 +0,0 @@
-#!/bin/env bash
-
-source "./scripts/utils.sh";
-
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
-ENV_FILE="$SCRIPT_DIR/config/.env";
-
-print_usage() {
-    cat<<EOF
-
-    USAGE bash run.sh [-s, -d, -p, -t, -c, -h]
-
-    (use from the scripts defined in 'package.json': 'npm start')
-
-    -s: setup the app
-    -t: test the app
-    -d: run the app in dev mode
-    -p: run the app in prod mode
-    -c: run the command line interface
-    -h: print help and exit
-
-EOF
-}
-
-start () {
-    local mode="$1"
-
-    if [ ! -f "$ENV_FILE" ];
-    then echo -e "\nERROR: .env file not found at '$ENV_FILE'. exiting..." && exit 1;
-    fi;
-
-    start_mongod
-
-    if [ "$mode" = "dev" ]; then
-        dotenvx run -f "$ENV_FILE" -- \
-        node --watch "$SCRIPT_DIR/src/server.js";
-    elif [ "$mode" = "test" ]; then
-        dotenvx run -f "$ENV_FILE" -- \
-        node --test --test-isolation=none;
-    elif [ "$mode" = "cli" ] ; then
-        dotenvx run -f "$ENV_FILE" -- \
-        node "$SCRIPT_DIR/cli/index.js";
-    else echo -e "\nERROR: mode not implemented: '$mode'\n"; print_usage; exit 1;
-    fi;
-}
-
-while getopts 'hdptcs' mode_flag; do
-    case "${mode_flag}" in
-        s) MODE="setup"
-            break;;
-        d) MODE="dev"
-            break;;
-        p) MODE="prod"
-            break;;
-        t) MODE="test"
-            break;;
-        c) MODE="cli"
-            break;;
-        h) print_usage
-           exit 0;;
-        *) print_usage
-           exit 1;;
-    esac
-done
-
-start "$MODE";
-

package/scripts/_migrations.sh

@@ -1,79 +0,0 @@
-#!/bin/env bash
-
-# use through package.json scripts.
-
-# these sripts are used to manage all migrations in parallel
-# on both the main database and the test database.
-#NOTE migrate-init is not implemented.
-
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
-
-source "$SCRIPT_DIR/utils.sh" || exit 1;
-
-MIGRATIONS_CONFIG_MAIN="$MIGRATIONS_DIR/migrate-mongo-config-main.js";
-MIGRATIONS_CONFIG_TEST="$MIGRATIONS_DIR/migrate-mongo-config-test.js";
-MIGRATIONS_CONFIGS=("$MIGRATIONS_CONFIG_MAIN" "$MIGRATIONS_CONFIG_TEST");
-
-##################################################
-# functions
-
-# create a migration
-# NOTE `migrate-mongo create` generates a timestamped file and, since this script is run twice
-# (once per config file), 2 migration files are created. so what we do is mimic migrate-make by
-# copying a blank template file to the `migrationScripts` directory.
-migrate_make() {
-    config_fp=$1;  # path to config file
-    migration_name="$2";  # name of migration to create
-
-    if [ -z "$migration_name" ];
-    then echo "ERROR. a migration name must be given."; exit 1;
-    fi;
-
-    cp "$MIGRATIONS_DIR/migrationTemplate.js" "$MIGRATIONS_DIR/migrationScripts/$(date +'%Y%m%d%H%M%S')-$migration_name.js";
-}
-
-# apply migrations
-migrate_apply() {
-    config_fp=$1;  # path to config file
-    dotenvx run -f "$ENV_FILE" -- npx migrate-mongo up -f "$config_fp";
-}
-
-# rvert the last migration
-migrate_revert() {
-    config_fp=$1;  # path to config file
-    dotenvx run -f "$ENV_FILE" -- npx migrate-mongo down -f "$config_fp";
-}
-
-# undo all migrations
-migrate_revert_all() {
-    config_fp=$1;  # path to config file
-
-    for _ in "$MIGRATIONS_DIR"/migrationScripts/*;
-    do dotenvx run -f "$ENV_FILE" -- npx migrate-mongo down -f "$config_fp";
-    done;
-}
-
-
-##################################################
-# cli
-
-OP=$1
-MIGRATION_NAME=$2  # only used by `migrate_make`
-
-case "$OP" in
-    make) FUNC=migrate_make;;
-    apply) FUNC=migrate_apply;;
-    revert) FUNC=migrate_revert;;
-    revertAll) FUNC=migrate_revert_all;;
-esac;
-
-if [ -z "$FUNC" ];
-then echo "ERROR: unrecognized keyword '$OP'. please use one of 'make', 'apply', 'revert', 'revertAll'. exiting..."; exit 1;
-fi;
-
-start_mongod
-
-for config_fp in "${MIGRATIONS_CONFIGS[@]}"; do
-    $FUNC "$config_fp" "$MIGRATION_NAME";
-done
-

package/scripts/_setup.js

@@ -1,31 +0,0 @@
-#!usr/bin/env node
-import path from "node:path";
-import { execSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-
-import { MongoClient } from "mongodb";
-
-const
-  // path to dirctory of curent file
-  dirScripts = path.dirname(fileURLToPath(import.meta.url)),
-  dirRoot = path.resolve(dirScripts, ".."),
-  dirMigrations = path.resolve(dirRoot, "migrations");
-
-const connString = process.env.MONGODB_CONNSTRING;
-
-(async () => {
-  let client;
-  try {
-    client = new MongoClient(connString);
-    await client.connect();
-    console.log("CONNECTED !")
-    console.log(dirScripts);
-    console.log(dirRoot);
-    console.log(dirMigrations);
-  } finally {
-    if ( client != null ) {
-      client.close()
-    }
-  }
-}
-)();

package/scripts/setup_mongodb_migrate.sh

@@ -1,17 +0,0 @@
-#!/bin/env bash
-
-#NOTE : this setup creates and populates our db WITHOUT users or authentication.
-# it is possible to add users and auth to a mongodb instance, but
-#   - it is a bit convoluted in itself
-#   - it is difficult to automate: we would need to
-#       - create a root user + a user for the app
-#       - create this app user by generating mongosh scripts from the user's .env files (so use Python to write custom JS)
-#       - update the mongodb conf file so that the systemd mongodb service uses auth login, which would need to parse YAML, so to use python
-
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
-ROOT_DIR="$SCRIPT_DIR/../"
-
-cd "$ROOT_DIR"
-
-npm run migrate-apply
-

package/scripts/utils.sh

@@ -1,192 +0,0 @@
-#!/bin/env bash
-
-# directory of the current script
-SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
-# root of the app
-ROOT_DIR=$( dirname "$SCRIPT_DIR" )
-# src/ directory
-SRC_DIR="$ROOT_DIR/src"
-# migrations/ dir
-MIGRATIONS_DIR="$ROOT_DIR/migrations";
-# .env file
-ENV_FILE="$SRC_DIR/config/.env"
-
-
-color_echo() {
-    Color_Off="\033[0m"
-    Red="\033[1;91m"        # Red
-    Green="\033[1;92m"      # Green
-    Yellow="\033[1;93m"     # Yellow
-    Blue="\033[1;94m"       # Blue
-    Purple="\033[1;95m"     # Purple
-    Cyan="\033[1;96m"       # Cyan
-
-    case "$1" in
-        "green") echo -e "$Green$2$Color_Off";;
-        "red") echo -e "$Red$2$Color_Off";;
-        "blue") echo -e "$Blue$2$Color_Off";;
-        "yellow") echo -e "$Yellow$2$Color_Off";;
-        "purple") echo -e "$Purple$2$Color_Off";;
-        "cyan") echo -e "$Cyan$2$Color_Off";;
-        *) echo "$2";;
-    esac
-}
-
-echo_title(){
-    sep_line="========================================"
-    len_title=${#1}
-
-    if [ "$len_title" -gt 40 ]; then
-        sep_line=$(printf "%0.s=" $(seq 1 $len_title))
-        title="$1"
-    else
-        diff=$((38 - len_title))
-        half_diff=$((diff / 2))
-        sep=$(printf "%0.s=" $(seq 1 $half_diff))
-
-        if [ $((diff % 2)) -ne 0 ]; then
-            title="$sep $1 $sep="
-        else
-            title="$sep $1 $sep"
-        fi
-    fi
-
-    color_echo purple "\n\n$sep_line\n$title\n$sep_line"
-}
-
-get_os() {
-    unameOut="$(uname -s)"
-    case "${unameOut}" in
-        Linux*)     os=Linux;;
-        Darwin*)    os=Mac;;
-        CYGWIN*)    os=Cygwin;;
-        MINGW*)     os=MinGw;;
-        MSYS_NT*)   os=Git;;
-        *)          os="UNKNOWN:${unameOut}"
-    esac
-    echo "${os}"
-}
-
-export OS
-OS=$(get_os)
-
-# gets a password and validates it by running a dummy cmd.
-# parent process must call the function with `get_password || exit` to exit the script if `SUDO_PSW` is invalid
-get_password() {
-    if [ -z "$SUDO_PSW" ]; then
-        read -s -p "Enter your sudo password: " SUDO_PSW
-        echo
-        echo "$SUDO_PSW" | sudo -S whoami > /dev/null 2>&1
-        if [ $? -ne 0 ]; then
-            echo "Invalid sudo password. Exiting..."
-            return 1
-        fi
-        return 0
-    fi
-}
-
-# the sed at the end removes trailing non-alphanumeric chars.
-generate_random_string() {
-    echo "$(openssl rand -base64 32 | tr -d '/\n' | sed -r -e "s/[^a-zA-Z0-9]+$//")"
-}
-
-get_env_value() {
-    param=$1
-    env_file=$2
-    value=$(awk -F= -v param="$param" '/^[^#]/ && $1 == param {gsub(/"/, "", $2); print $2}' "$env_file")
-    echo "$value"
-}
-
-get_env_desc() {
-    current_line="$1"
-    prev_line="$2"
-    desc=""
-    if [[ $prev_line =~ ^# ]]; then
-        desc=$(echo "$prev_line" | sed 's/^#\s*//')
-    fi
-    echo "$desc"
-}
-
-ask() {
-    options=("yes" "no")
-    color_echo blue "$1"
-    answer=$(printf "%s\n" "${options[@]}" | fzy)
-    echo ""
-    if [ "$answer" = "no" ]; then
-        exit 1
-    fi
-}
-
-# float arithmetic comparison is not supported by bash and we need to use `bc`
-# usage: if float_comparison "a >= b"; then... ; fi
-float_comparison () {
-    expr="$1"
-    (( $(echo "$expr" |bc -l) ));
-}
-
-# sed replacements in place
-# `sed -i` can't be used in the same way with Linux and Mac: it's `sed -i` on Linux, `sed -i ""` on Mac
-sed_repl_inplace() {
-    sed_expr="$1"
-    file="$2"
-
-    if [ "$OS" = "Linux" ]; then
-        sed -i -e "$sed_expr" "$file"
-    else
-        sed -i "" -e "$sed_expr" "$file"
-    fi
-}
-
-# sudo does not inherit from bash functions so this is a copy of "sed_repl_inplace" with sudo privileges (see: https://stackoverflow.com/a/9448969)
-sudo_sed_repl_inplace() {
-    sed_expr="$1"
-    file="$2"
-
-    if [ "$OS" = "Linux" ]; then
-        [ -n "$SUDO_PSW" ] && echo "$SUDO_PSW" | sudo -S sed -i -e "$sed_expr" "$file" || sudo sed -i -e "$sed_expr" "$file"
-    else
-        [ -n "$SUDO_PSW" ] && echo "$SUDO_PSW" | sudo -S sed -i "" -e "$sed_expr" "$file" || sudo sed -i "" -e "$sed_expr" "$file"
-    fi
-}
-
-# ed replacements to a new file
-sed_repl_newfile() {
-    sed_expr="$1"
-    infile="$2"
-    outfile="$3"
-
-    sed "$sed_expr" "$infile" | tee "$outfile" > /dev/null
-}
-
-sudo_sed_repl_newfile() {
-    sed_expr="$1"
-    infile="$2"
-    outfile="$3"
-
-    sudo sed "$sed_expr" "$infile" | sudo tee "$outfile" > /dev/null
-}
-
-run_script() {
-    local script_name="$1"
-    local description="$2"
-    local SCRIPT_DIR=${3:-${SCRIPT_DIR}}
-    options=("yes" "no")
-
-    color_echo blue "Do you want to run $description?"
-    answer=$(printf "%s\n" "${options[@]}" | fzy)
-    echo ""
-    if [ "$answer" = "yes" ]; then
-        bash "$SCRIPT_DIR/$script_name" \
-        && color_echo green "$description completed successfully" \
-        || color_echo red "$description failed with exit code. Continuing..."
-    else
-        color_echo cyan "Skipping $description"
-    fi
-    echo ""
-}
-
-start_mongod() {
-    if ! systemctl is-active --quiet mongod;
-    then sudo systemctl start mongod;
-    fi;
-}

package/setup.sh

@@ -1,20 +0,0 @@
-#!/bin/env bash
-
-source "./scripts/utils.sh";
-
-# SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
-
-color_echo blue "\nInstalling prompt utility fzy..."
-if [ "$OS" = "Linux" ]; then
-    sudo apt install fzy
-elif [ "$OS" = "Mac" ]; then
-    brew install fzy
-else
-    color_echo red "Unsupported OS: $OS"
-    exit 1
-fi
-
-#NOTE node needs to be installed for mongodb to run, so order is important
-run_script "setup_node.sh" "Node and webapp packages installation"
-run_script "setup_mongodb.sh" "MongoDB installation"
-run_script "setup_mongodb_migrate.sh" "MongoDB database creation"