Development

This guide covers the steps required to set up a local development environment for Lodex using the provided Makefile abstractions.

🛠 Prerequisites

Before starting, ensure you have the following installed on your host machine:

• Docker & Docker Compose

• Make (build automation tool)

• Node.js (matching the version specified in .nvmrc or package.json)

---

🚀 Quick Start

Follow these steps to initialize and launch the development stack:

1. Install Dependencies

Initialize the project by installing necessary Node.js dependencies:

Bash

make install

2. Launch the Stack

Start the development containers. Note that the first execution may take several minutes as Docker images are built and layers are cached.

Bash

make run-dev

3. Active Services

Once the stack is up, the following containers will be active:

Container Name	Service Description	Access URL
lodex_server_1	API Server (Node.js process)	http://localhost:3000
lodex_devserver_1	Frontend (Webpack Dev Server)	http://localhost:8080
lodex_mongo_1	MongoDB Instance	localhost:27017

Authentication: Default credentials are defined in the ./config/ directory.

Cleaning the Project

To clean up the project and remove all generated files, dependencies, and Docker resources, you can use the following commands:

Remove Node.js Dependencies

npm run clear-npm

This command removes all node_modules directories in the project.

Remove Docker Resources

npm run clear-docker

This command stops and removes all containers, volumes, and images defined in the project's docker-compose files. It ensures a clean slate for rebuilding or redeploying the project.

---

📦 Dependency Management

To maintain consistency between environments and prevent package-lock.json corruption, do not run npm install directly on your host machine.

Always use the containerized npm environment:

Bash

# Correct way to add a new package
make npm 'install <package-name>'

---

🗄 Database Management

Direct Access

To enter the interactive MongoDB shell:

Bash

make mongo-shell

Resetting the Environment

If you need to clear the state of your application during development, use the following commands:

• make clear-publication: Removes all published data while preserving your uploaded datasets and data models.

• make clear-database: Full reset. Wipes the entire MongoDB database.

---

🧪 Testing & Quality Assurance

Ensure your development environment is fully initialized before running tests.

Clone and install

git clone https://github.com/Inist-CNRS/lodex.git
cd lodex
make install

Run dev server

make run-dev

Go to http://localhost:3000/instances and log in using the credentials root/secret. From there, you can create a new instance (tenant) on the instances page in order to publish new datasets and models.

Note: Upon instance creation, the default user/password combination is set to admin/secret.

Run test suite

Different tests can be run to verify that changes made to the source code at various levels do not cause any issues in the application.

• The test-unit suite focuses on testing individual functions and systems without considering the entire application.
• The test-api-e2e suite aims to test the API without taking the frontend into consideration.
• The test-e2e suite's goal is to test various scenarios with both the frontend and backend in mind.

make test-unit
make test-api-e2e
make test-e2e # Those tests may take up to 30 minutes to complete.

make test # Run all of the above tests

Note: You can disable end-to-end tests in the make test command by setting the DISABLE_E2E_TESTS environment variable to true.

---

🚀 Releasing a New Version

Lodex follows Semantic Versioning (SemVer). When you are ready to build a new version, use the npm version command to automate tag creation and version bumping.

Bash

# For bug fixes (16.10.4 -> 16.10.5)
npm version patch

# For new features (16.10.4 -> 16.11.0)
npm version minor

# For breaking changes (16.10.4 -> 17.0.0)
npm version major