Installation Guide

Overview

The standard deployment method for Lodex is via Docker. While it is possible to install Lodex natively, manual configuration of its individual components is not officially documented or supported.
Lodex utilizes docker-compose to orchestrate its microservices. Several Compose files are available depending on the environment (Development, Testing, or Staging). For production environments, the standard docker-compose.yml is required.

Quick Start

The production stack consists of two primary containers:

1. MongoDB: The backend database.
2. Lodex: The core application engine.

To deploy the stack, execute the following commands:

Bash

# 1. Download the production docker-compose file (Version 16.10.4)  
wget https://raw.githubusercontent.com/Inist-CNRS/lodex/refs/tags/v16.10.4/docker-compose.yml

# 2. Deploy the stack in detached mode  
docker-compose up -d

Alternative ways

with git

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

with zip file

wget https://github.com/Inist-CNRS/lodex/archive/refs/tags/v14.0.18-alpha.zip
unzip v14.0.18-alpha.zip
cd lodex-14.0.18-alpha
make run-dist

Configuration

While Lodex runs with default settings out of the box, a production deployment requires specific environment variables to be tuned. These variables are defined within the docker-compose.yml file.

1. Networking & Proxy Settings

If the server is behind a corporate firewall, configure the standard outbound proxy variables:

• http_proxy: URL for the HTTP proxy.
• https_proxy: URL for the HTTPS proxy.
• no_proxy: List of hosts that should bypass the proxy.

2. Administrative Authentication

These credentials grant "Super Admin" privileges, allowing the user to manage (create/delete) all Lodex instances.

Security Warning: Change these defaults immediately and ensure they are not committed to public repositories.

Variable	Description
ROOT_LOGIN	The primary administrator username.
ROOT_PASSWORD	The primary administrator password.

3. Advanced Backend Settings

Variable	Description
PRECOMPUTED_URL	The callback URL used for asynchronous pre-calculation web services. (Optional: default usually suffices).
MONGO_DATABASE_PREFIX	Defines a prefix for MongoDB collections. Use this if you are hosting multiple Lodex environments on a single MongoDB cluster.

Data storage

In a production environment, Docker containers are ephemeral by design, meaning any data stored inside them is lost if the container is removed. To ensure your database survives updates and restarts, you must use Docker Volumes or Bind Mounts to persist the MongoDB data on the host machine’s physical storage. By mapping the container's internal data directory—located at /data/db—to a specific path on your server, you ensure that the database files remain intact regardless of the container's lifecycle.

To implement this, modify the mongo service in your docker-compose.yml file as follows:

services:
  mongo:
    image: mongo:latest
    user: "${UID}:${GID}"
    volumes:
      # Maps the host folder './lodex-data' to the MongoDB data directory
      - ./lodex-data:/data/db

Permissions: Ensure that the user running Docker has the necessary read/write permissions for the host directory (e.g., ./lodex-data). On Linux systems, you may need to use chown to adjust ownership if the container fails to write to the volume.

Log Management

In a production environment, container logs can grow indefinitely, eventually consuming all available disk space. To prevent this, we recommend mounting the application logs to a host directory and managing them with the system's native logrotate utility.

To externalize logs, add a volume mapping to your lodex service in the docker-compose.yml file. This ensures logs are written directly to your server's filesystem rather than inside the container's writable layer. YAML

services:
  lodex:
    # ... other settings
    volumes:
      - ./logs:/app/log # Maps internal application logs to the local 'logs' folder