-
Node >=24.0.0 -
corepackenabled for Yarn version management -
Supply chain security environment variable (recommended)
Add this to your shell profile (.bashrc, .zshrc, etc.):
# Supply chain security: require packages to be 7+ days old (Yarn 4+ feature)
export YARN_NPM_MINIMAL_AGE_GATE=10080Why this is needed:
-
YARN_NPM_MINIMAL_AGE_GATE=10080: Protects against supply chain attacks by requiring NPM packages to be at least 7 days old before installation. This is a Yarn 4+ feature that helps prevent installing packages immediately after publication (when they’re most vulnerable to compromise).
|
ℹ️
|
Developers have two options for setting this variable Option A: Global shell configuration (simple) Add the variable to your shell profile ( Option B: Per-repository with direnv (recommended) Use direnv to automatically set this variable only when working in this repository:
The environment variable will now be set automatically whenever you enter this repository directory. |
Volta is recommended for Node version management. It will automatically use Node 24 when working in this repository.
To set up Volta with Corepack:
# Install volta if you haven't already
curl https://get.volta.sh | bash
# Install corepack globally and enable it with volta integration
npm install -g corepack
corepack enable --install-directory ~/.volta/binThis configuration allows Volta to manage Node versions while Corepack manages Yarn versions based on the packageManager field in package.json.
If you’re not using Volta, simply enable corepack:
corepack enableNote: If you have a global yarn installation, you may need to uninstall it first to avoid conflicts with corepack.
IMPORTANT: This project requires Yarn. Using npm install will fail with dependency resolution errors because this monorepo uses Yarn-specific features (workspace protocol, etc.) that npm doesn’t support.
The repository includes automatic checks that run before yarn install to verify:
-
Corepack is properly configured with the correct Yarn version (4.12.0)
If you see errors about wrong Yarn version, refer to the setup instructions above.
WARNING: This section is ONLY for legacy deployment servers that cannot upgrade to Node.js 24. Development machines should follow the standard Prerequisites above.
This repository supports both modern (corepack-managed Yarn 4) and legacy (bundled Yarn 3) environments:
-
Development machines: Use Yarn 4.12.0 via corepack (as specified in
package.json) -
Legacy deployment servers: Use bundled Yarn 3.3.1 at
.yarn/releases/yarn-3.3.1.cjs
If you’re deploying to an environment that cannot run Node.js 24 (such as end-of-life CentOS 7), set these environment variables:
On palm and other legacy servers, add these exports to $BASE_GUS/etc/setenv for persistence, then paste them into your current shell to activate immediately. (Don’t re-source setenv - it will duplicate PATH entries.)
# Bypass version checks for web-monorepo
export SKIP_YARN_VERSION_CHECK=true
export npm_config_engine_strict=false
# Allow lockfile modifications (Yarn 3/4 lockfile format incompatibility)
export YARN_ENABLE_IMMUTABLE_INSTALLS=falseOn legacy deployment servers, you must uncomment the yarnPath line in .yarnrc.yml:
# Edit .yarnrc.yml and change:
# # yarnPath: .yarn/releases/yarn-3.3.1.cjs
# to:
# yarnPath: .yarn/releases/yarn-3.3.1.cjsThis will make yarn commands use the bundled Yarn 3.3.1, even when called from Ant or other build tools. No need to call Yarn with a fully-qualified path.
CRITICAL:
- The uncommented yarnPath line in .yarnrc.yml must NEVER be committed to git. The pre-commit hook will prevent this. Before running git pull or git checkout, restore the file with git restore .yarnrc.yml.
- The yarn.lock file uses Yarn 4 format. When Yarn 3 runs yarn install, it will modify checksums in the lockfile. These changes are format-only (no package version changes) but must NEVER be committed to git, as they will break Yarn 4 on development machines. A hook should prevent this anyway. Before changing code with git pull or git checkout, restore the file with git restore yarn.lock.
Security implications:
-
Legacy deployments do NOT benefit from the 7-day package age gate (Yarn 4+ feature)
-
Only use this for deployment servers where you will NOT be running
yarn addor installing new packages -
The security measures are designed to protect developer machines from supply chain attacks during package installation
The YARN_ENABLE_IMMUTABLE_INSTALLS=false environment variable does not override yarn --frozen-lockfile commands in Ant build scripts. To work around this:
First-time setup after checkout:
cd web-monorepo
yarn # This modifies yarn.lock to Yarn 3 format
# Verify: git status should show yarn.lock as modifiedAfter this initial yarn run, subsequent Ant build commands (rebuilder, wb site, etc.) will succeed because the lockfile is already in the expected format.
IMPORTANT: Before running git pull or git checkout, restore the lockfile:
git restore yarn.lockAfter any git operation that changes the repository, run yarn again to re-modify the lockfile.
From anywhere in the repo:
yarnNote: This repository uses immutable installs for security. The yarn.lock file must be committed to git and cannot be modified by yarn install. Commands like yarn add <package> and yarn remove <package> work normally and will update the lockfile as expected. This prevents accidental mass upgrades (e.g., deleting and regenerating yarn.lock would upgrade many packages to newer versions). All dependency upgrades should be intentional and reviewed.
This repository is a "monorepo", using the nx build system and yarn@4 dependency manager. The source code is divided into one of three types of packages: "config", "lib", and "site".
-
"config" packages (
./packages/configs) include various build and development configurations and tools. -
"lib" packages (
./packages/libs) include standalone library and webapp source code. -
"site" packages (
./packages/sites) include complete website source code.
Many "lib" and "site" packages include development tools, such as development servers, test scripts, etc.
Many commands require a reference to the package name. All package names are currently prefixed with @veupathdb/. For example, the eda package name is @veupathdb/eda.
The repository is currently configured as a "package based repository". This is subject to change, in the future (see https://nx.dev/concepts/integrated-vs-package-based to read about the differences between package based and integrated repos).
The following tasks are common performed by developers. This serves as a reference guide, and is not exhaustive in any way. If you feel something is missing, create an issue, or open a pull request.
All commands are expected to be run in the repository’s root directory, unless otherwise specified.
"Site" projects are stored in the packages/sites directory. Each one corresponds to a "cohort". For example, packages/sites/genomics-site
contains the code used to build the client code for a genomics website.
Each cohort contains a .env.sample file. Copy this to a sibling .env file. You may need to modify some values, such as usernames,
passwords, etc. You can also specify a website to use for various services. Typically a deployed QA site will suffice, but you can also run a "local backend" via various methods. (TODO: link to relevants docs/repos).
Once you have created a .env file, you can run the local dev site with the command:
yarn nx start <package name>For example, if you want to run a local clinepi site, you would run the command:
yarn nx start @veupathdb/clinepi-siteOnce the website has been compiled, the dev server will output some build statistics and automatically open a browser tab. You can kill the local dev server with CTRL-C in the terminal where you started it.
When a local dev site is running, it will detect when build dependencies are updated and reload the active webpage.
Note: the following refers to code tracked by the monorepo, and not third-party dependencies from npm.
There are two types of souce code that can be updated:
-
Source code within the package being served.
-
Source code within a dependent package.
Changes to code within the package being served will be detected automatically. The local dev service should reompile the affected module and reload the website without intervention.
Changes to code within a dependent workspace package will require a build command for the local dev server to detect the change.
For example, if you change code in packages/libs/eda, you will need to run this command in a new terminal window, from the repository root:
yarn workspace @veupathdb/eda build-npm-modulesOnce this command completed, the running dev server will see the updated build artifacts, recompile the website, and reload the webpage. There are some cases where this might not work as expected, such as if the recompile step fails. In those cases, you may need to restart the local dev server. You can monitor the progress of the recompilation step in the terminal where you started the dev server.
From the root package.json:
yarn nx run <workspaceName>:<scriptName>For example, you can start the MultiBLAST dev server by running
yarn nx run @veupathdb/multi-blast:startWhen running a development server (such as yarn nx start @veupathdb/eda or yarn nx start @veupathdb/clinepi-site),
use the following command to rebuild changes made to dependencies, and to have the dev site reload with the changes:
cd packages/libs/<package>
yarn build-npm-modulesNote: You may need to manually reload your website to see the changes the first time.
Using the equivalent nx command (yarn nx build-npm-modules @veupathdb/<package>) has proven inadequate in this scenario.
Directory: packages/libs/eda
You will need to configure the server with a packages/libs/eda/.env.local file that sets various environment variables.
For more documentation see the package README and this sample file.
Directory: packages/sites/{site name}-site
Copy the packages/sites/{site name}-site/.env.sample file to packages/sites/{site name}-site/.env and configure the new file with passwords and the desired backend for the site.
Run yarn to update dependencies if necessary.
Run the command yarn nx start @veupathdb/{site name}-site. For example, to run the ortho site use yarn nx start @veupathdb/ortho-site.
Warning. There be dragons! This section has not been maintained for a long time.
The Client Bundle Server is a Docker image based on NGINX that is used to serve VEuPathDB client code over HTTP.
As the client code comes in 2 flavors (bundles), legacy and modern, this NGINX server has an internal path rewrite based on the requesting browser’s user agent string to the appropriate client bundle component on request.
This means using a modern browser, requesting the file
genomics/site-client.bundle.js will cause the server to actually return
modern/genomics/site-client.bundle.js whereas requesting that same file from
an older or unsupported browser (such as CURL or Postman) the server will return
legacy/genomics/site-client.bundle.js.
Whether a browser is considered modern or legacy is dependent on the version of the browser compared to a RegEx constructed by the browserslist-useragent-regexp library using the input query constructed in the browserslist-config package of this repo. (See index.js for the raw queries)
The docker image is based on NGINX-Perl and includes NodeJS for executing a script based on browserslist-useragent-regexp that determines which path a specified file should be served from.
The image build is multi-staged with the first stage compiling primary contents of this repository, and the second stage setting up NGINX and the secondary JS script included in the docker directory (makeSupportedBrowsersScript.js).
Content is served from the following paths from the root path used to reach a running instance of the built Docker image:
{URL}/clinepi/{target-file}
{URL}/genomics/{target-file}
{URL}/mbio/{target-file}
{URL}/ortho/{target-file}These paths correspond to the following container internal paths:
/var/www/legacy/clinepi/{target-file}
/var/www/modern/clinepi/{target-file}
/var/www/legacy/genomics/{target-file}
/var/www/modern/genomics/{target-file}
/var/www/legacy/mbio/{target-file}
/var/www/modern/mbio/{target-file}
/var/www/legacy/ortho/{target-file}
/var/www/modern/ortho/{target-file}The Docker image may be tested locally by performing the following steps from the docker/ subdirectory:
-
Build and Start the image:
make docker-build make docker-run
-
Using your favorite HTTP request making tool such as Postman, CURL, or a web browser, make a request to http://localhost/genomics/site-client.bundle.js.LICENSE.txt . If the service is working you should receive a LICENSE text file’s contents as the response with a 200 status code. If it is not working you will receive a 403 or 404 error.