Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
120 lines (75 loc) · 4.09 KB

CONTRIBUTING.md

File metadata and controls

120 lines (75 loc) · 4.09 KB
Raw

Contributing to Open Foris Arena

Prerequisites

First, install Yarn (a modern npm replacement).

Then, install Node.js (currently we are using LTS version 18.x).

GitHub packages: authentication

Arena requires some GitHub packages (@openforis/arena-core and @openforis/arena-server). In order to do that, you must use a token with (at least) the read:packages scope.

You can authenticate to GitHub Packages with npm by either editing your per-user ~/.npmrc file to include your personal access token or by logging in to npm on the command line using your username and personal access token.

To authenticate by adding your personal access token to your ~/.npmrc file, edit the ~/.npmrc file for your project to include the following line, replacing TOKEN with your personal access token. Create a new ~/.npmrc file if one doesn't exist and replace TOKEN with your personal access token.

//npm.pkg.github.com/:_authToken=TOKEN

To authenticate by logging in to npm, use the npm login command, replacing USERNAME with your GitHub username, TOKEN with your personal access token, and PUBLIC-EMAIL-ADDRESS with your email address.

If GitHub Packages is not your default package registry for using npm and you want to use the npm audit command, we recommend you use the --scope flag with the owner of the package when you authenticate to GitHub Packages.

$ npm login --scope=@OWNER --registry=https://npm.pkg.github.com

> Username: USERNAME
> Password: TOKEN
> Email: PUBLIC-EMAIL-ADDRESS

For more information see Authenticating to GitHub Packages

On the feat/auto-scaling branch, @openforis/arena-server is temporarily linked via a yarn portal:../arena-server reference to a local sibling checkout, instead of a published npm version, so both repos' in-progress auto-scaling work can be developed together locally. There is no sibling checkout in CI, so CI and Docker builds will fail on this branch until the portal link is swapped back to a published @openforis/arena-server release before merging to master.

Development

To install local database:

sudo docker run -d --name arena-db -p 5444:5432 -e POSTGRES_DB=arena -e POSTGRES_PASSWORD=arena -e POSTGRES_USER=arena postgis/postgis:17-3.5

In order to access Arena when it's installed on a remote server, you need to request access to it or being invited to it. When working locally, it is possible to insert a system admin user by passing the environment variables ADMIN_EMAIL and ADMIN_PASSWORD. The user will be created on the first startup.

To restart local database:

docker container restart arena-db

To install dependencies:

yarn install

To run the server and the Web app in parallel with "hot reload" on any changes:

yarn watch

The .env file

The .env file is needed for development and locally running the stack.

must be added to the root directory of the project and must match the template .env.template.

Running the test suite

The following runs the test suite with an isolated Dockerized DB instance.

Note: What's tested is the committed code only. Uncommitted changes are ignored.

yarn test:docker

Running tests locally

First of all, build the project:

yarn build

then start the server locally:

pm2-runtime ./dist/server.js

In another shell tab/window, run the e2e tests:

yarn test:e2e:watch

Run R Studio Server locally

To install RStudio Server as a Docker container run the following command:

  • replace ANALYSIS_OUTPUT_DIR with the value of the ANALYSIS_OUTPUT_DIR environment variable
docker run -d --name arena-rstudio --network=host -v ANALYSIS_OUTPUT_DIR:/home/rstudio -e DISABLE_AUTH=true rocker/rstudio

To restart RStudio server run

docker container restart arena-rstudio

Visit http://localhost:8787 in your browser to access the rStudio server instance.