Skip to content

DEVNOTES.md

Latest commit

 

History

History
134 lines (91 loc) · 5.22 KB

DEVNOTES.md

File metadata and controls

134 lines (91 loc) · 5.22 KB
Raw

Development

Dev Container

If you are using Visual Studio Code (VSCode) and Docker, consider using the Dev Container configuration. This will automatically setup and configure DUOS on your behalf. When opening the project in VSCode, a notification will appear in the bottom right corner to use the Dev Container. Click "Reopen in container".

Next, the terminal will install the dependencies. Once installed, the terminal will prompt to authenticate with Google Cloud. Do this by following the link and signing in with your broadinstitute.org account. Copy and paste the auth code in the terminal and press enter to complete setup.

Local Setup

Alternatively, you may install DUOS locally.

  1. Install Node LTS, but verify the version of Node declared in the Dockerfile and install that when setting up. You can install it with Volta or NVM.
volta install node@24.11.1
  1. Next, install the project dependencies.
pnpm install
  1. Ensure you are connected to the Broad VPN. Copy the configuration files and certificates locally by running the render-configs.sh script. By default, the DUOS UI points to the dev environment.
./scripts/render-configs.sh --write_env true --write_config true

Notes on render-configs:

  • Ensure that HOST is not set in your shell environment, as it will override the value in .env.local. You can check like so: env | grep HOST=.
  • Development against other envs: If you want to point to other envs, you can populate public/config.json with the values from any environment by looking at the deployed configs in https://duos-k8s.dsde-{%ENV%}.broadinstitute.org/config.json where {%ENV%} is any of dev, staging, alpha, or prod. Remember to set the env value appropriately, for example, dev. Certain features are available only in specific environments. Setting the env value to the desired environment will simulate it for local development.
  • Refresh certs on rotation: render-config.sh populates local certificate files. The certificates are rotated every 3 months and can be repopulated by re-running the script. Again, you'll need to be on the broad VPN.
./scripts/render-configs.sh
  1. Ensure that your /etc/hosts file has an entry for local.dsde-dev.broadinstitute.org
127.0.0.1	local.dsde-dev.broadinstitute.org

  1. Create a site.conf file in the project root directory using https://github.com/broadinstitute/terra-helmfile/blob/master/charts/duos/templates/_site.conf.tpl as a model.

  2. Start the development server. There are two modes:

    Frontend only (default — fastest HMR):

    pnpm start

    Runs Vite's standalone dev server on port 3000 with native hot-module reloading. Use this for day-to-day UI work. The Fastify server is not involved, so sessions, cookies, auth callbacks, and the API proxy are not exercised.

    Full stack (Fastify + Vite middleware):

    pnpm run start:server

    Boots the Fastify server (port 3000) with Vite's HMR middleware embedded, so server code (sessions, cookies, auth callbacks, API proxy) runs alongside the frontend. Reloads via tsx watch, which is slower than native Vite HMR — use this when you need the server behavior.

    Both modes serve HTTPS from server.key/server.crt and open the browser automatically.

Running using Docker Compose

Update your local docker-compose.yaml file to mount the preferred config.json file in app volumes. Remember to set the env value appropriately, for example, dev. Certain features are available only in specific environments. Setting the env value to the desired environment will simulate it for local development.

    volumes:
      - ./public/config.json:/usr/src/app/build/config.json

Build and run:

docker build . -t duos --platform linux/amd64
docker compose up -d

Visit https://local.dsde-dev.broadinstitute.org/ to see the instance running under docker.

Environment variables

The server reads sensitive configuration from .env.local in the project root (gitignored). Create this file before running docker compose up. The required variables are:

# Fastify session
DUOS_SESSION_SECRET=          # random base64 string, e.g.: openssl rand -base64 32
DUOS_SESSION_MAX_AGE_MS=      # cookie max-age in milliseconds (default: 28800000 = 8 hours)

# PostgreSQL connection
DUOS_DB_HOST=                 # hostname of the Postgres server (e.g. db or a Cloud SQL proxy)
DUOS_DB_NAME=                 # database name
DUOS_DB_PORT=5432             # defaults to 5432 if omitted
DUOS_DB_USER=                 # database user
DUOS_DB_PASSWORD=             # database password

NODE_ENV, PORT, and FASTIFY_LOG_LEVEL can be overridden at the shell level when running docker compose up but have sensible defaults and do not need to be in .env.local.

Testing

See TESTING.md for full testing instructions.

E2E Tests (Playwright)

Build the app and run e2e tests against the preview server:

CI=false pnpm run build
pnpm run test:e2e

Unit & Component Tests (Vitest)

pnpm test