From 055168ad56de847f90a9f685df0c9cbf206eacb1 Mon Sep 17 00:00:00 2001 From: Brian Schlining Date: Sat, 13 Jul 2024 21:59:09 -0700 Subject: [PATCH] Updated README --- README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++-------- build.sbt | 6 +++-- 2 files changed, 64 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index c657076..931a43d 100644 --- a/README.md +++ b/README.md @@ -6,22 +6,72 @@ ## Overview -This is a project to create a RESTful API for managing the naming of organisms. Currently in development, it is meant to be a replacement for and . +This is a project to create a RESTful API for managing a tree structure of names used by annotation tools and data catalogs. We typically call this tree structure a "knowledgebase" (aka "KB"). Tree structures are useful for modeling organism phylogeny. At MBARI, we also include other terms, such as geological features and equipment used for research. + +Currently in development, it is a replacement for and . + +Oni includes APIs for fast search and retrieval of terms, fetching branches of the knowledgebase, and user accounts. Individual nodes in the KB are called _concepts_, and each concept may have one primary name (e.g. the accepted taxa name) and zero or more alternative names (such as synonyms, common names, former taxa names, etc.) ## Usage -This is a normal [sbt](https://www.scala-sbt.org) project. You can compile code with `sbt compile`, run it with `sbt run`, and `sbt console` will start a Scala 3 REPL. +Oni requires an existing [SQL Server](https://www.microsoft.com/en-us/sql-server/sql-server-downloads) or [PostgreSQL](https://www.postgresql.org) database that it can connect to. The easiest way to spin Oni up with a database is to use the [m3-quickstart](https://github.com/mbari-org/m3-quickstart) which handles the setup of the database for you. -## Useful Commands +### Run using [Docker](https://www.docker.com) -1. `stage` - Build runnable project in `target/universal` -2. `universal:packageBin` - Build zip files of runnable project in `target/universal` -3. `scaladoc` - Build documentation, including API docs to `target/docs/site` -4. `compile` then `scalafmtAll` - Will convert all syntax to new-style, indent based Scala 3. +If you have an existing database, you can start Oni using Docker. Note these examples use place holder values for the secrets, server name and database name that you can subtitues with your own. + +#### PostgreSQL + +Here's an example connecting to a PostgreSQL database. You can find the schema to use in [02_m3_kb.sql](it-postgres/src/test/resources/sql/02_m3_kb.sql). + +```sh +docker run -d \ + -p 8080:8080 \ + -e BASICJWT_CLIENT_SECRET="xxxx" \ + -e BASICJWT_SIGNING_SECRET="xxxx" \ + -e DATABASE_DRIVER="org.postgresql.Driver" \ + -e DATABASE_PASSWORD="xxxx" \ + -e DATABASE_URL="jdbc:postgresql://your.serverurl.org:5432/YourDatabaseName?sslmode=disable&stringType=unspecified" \ + -e DATABASE_USER=dbuser \ + --name=oni \ + --restart unless-stopped \ + mbari/oni +``` + +#### SQL Server +The schema for SQL Server is in [init_min.sql](it-sqlserver/src/test/resources/sql/init_min.sql). -## Notes +```sh +docker run -d \ + -p 8080:8080 \ + -e BASICJWT_CLIENT_SECRET="xxxx" \ + -e BASICJWT_SIGNING_SECRET="xxxx" \ + -e DATABASE_DRIVER="com.microsoft.sqlserver.jdbc.SQLServerDriver" \ + -e DATABASE_PASSWORD="xxxx" \ + -e DATABASE_URL="jdbc:sqlserver://database.mbari.org:1433;databaseName=YourDatabaseName" \ + -e DATABASE_USER=dbuser \ + --name=oni \ + --restart unless-stopped \ + mbari/oni +``` -Documentation can be added as markdown files in `docs` and will be included automatically when you run `scaladoc`. +## Documentation + +Once the server is started you can view the documentation at http://:8080/docs + + +## Development + +This is a normal [sbt](https://www.scala-sbt.org) project. You will need Docker installed to run the full test suite. Docker allows this project to start database servers for integration testing. + +## Useful SBT Commands + +1. `stage` - Builds a runnable project in `target/oni/universal/stage` +2. `Docker/stage` - Builds a Dockerfile for Oni at `target/oni/docker/stage` +3. `doc` - Build documentation, including API docs to `target/docs/site` +4. `compile` then `scalafmtAll` - Will convert all syntax to new-style, indent based Scala 3. +5. `test` run all tests +6. `itPostgres/test` or `itSqlserver/test` to only run tests against one of the databases. +7. `itPostgres/testOnly ` or `itSqlserver/testOnly ` to run a single test. -When updating SBT version, make sure to update the devcontainer image in [devcontainer.json](.devcontainer/devcontainer.json). It's versions are `eclipse-temurin-__` diff --git a/build.sbt b/build.sbt index 10bbabd..f950620 100644 --- a/build.sbt +++ b/build.sbt @@ -8,9 +8,9 @@ Compile / doc / scalacOptions ++= Seq( "-project-footer", "Monterey Bay Aquarium Research Institute", "-siteroot", - "oni/src/docs", + "src/docs", "-doc-root-content", - "./oni/src/docs/index.md" + "src/docs/index.md" ) ThisBuild / javacOptions ++= Seq("-target", "21", "-source", "21") @@ -116,6 +116,8 @@ lazy val oni = project ) + + lazy val integrationTests = (project in file("it")) .dependsOn(oni) .enablePlugins(