Skip to content

Install Etendo Main UI

Overview

IMPORTANT: THIS IS A BETA VERSION

  • It is under active development and may contain unstable or incomplete features. Use it at your own risk, especially in production environments.
  • It should be used with caution, and you should always validate backups before executing any critical operation.

This guide provides instructions to install and run the Etendo Main UI, a modern React/TypeScript-based user interface that provides a new frontend experience for Etendo. The Main UI runs as a containerized service alongside your Etendo instance.

Requirements

  1. Etendo project properly set up.

  2. This project depends on the following tools:

    Info

    The Docker Management module, included as a dependency, allows for the distribution of the infrastructure within Etendo modules, which include Docker containers for each service.

  3. Client Access Token

    Application > General Setup > Client > Client

    A one-time encryption token must be configured for authentication. This token is required for Etendo Main UI to start a session.

    1. Access Etendo Classic as a System Administrator.
    2. Navigate to Client > Secure Web Service Configuration tab.
    3. Click the Generate Key button to create a token. The expiration time is measured in minutes, if set to 0 the token does not expire.

    alt text

    Info

    This token doesn’t require any action; it just needs to be generated for the authentication process to work properly.

Installation

Etendo Main UI is distributed within the Platform Extensions bundle, which includes the Main UI Infrastructure and all required backend modules for the new interface.

Info

To be able to include this functionality, the Platform Extensions Bundle must be installed.
To do that, follow the instructions from the marketplace: Platform Extensions Bundle.
For more information about the available versions, core compatibility and new features, visit Platform Extensions - Release notes.

Running Etendo Main UI

The simplest configuration example uses Main UI running in Docker and Tomcat running locally.
Other configurations are detailed in the section Advanced Configurations.

  1. You can configure Main UI interactively by running:

    ./gradlew setup -Pinteractive=true --console=plain

    This will guide you through the configuration process for all required variables. For more information visit Interactive Instalation guide.

  2. Start the Docker services:

    Terminal
        ./gradlew resources.up

    This will start the Main UI container along with any other configured Docker services.

Manual Configuration

  1. Add the following lines to the gradle.properties file:

    gradle.properties
        docker_com.etendoerp.mainui=true
    etendo.classic.url=http://host.docker.internal:8080/etendo
    etendo.classic.host=http://localhost:8080/etendo
    authentication.class=com.etendoerp.etendorx.auth.SWSAuthenticationManager
    ws.maxInactiveInterval=3600
    next.public.app.url=http://localhost:3000
    Variable Purpose (Simple Explanation) Notes Recommended Value (Local) Recommended Value (Production)
    docker_com.etendoerp.mainui Enables the Main UI Docker service. Default value may vary depending on the environment. true true
    etendo.classic.url Backend URL used by the Main UI server to connect to Etendo Classic. If Main UI runs in Docker and Tomcat runs locally, host.docker.internal must be used. http://host.docker.internal:8080/etendo https://your.backend.etendo.cloud/etendo
    etendo.classic.host Client-side URL that the browser uses to make direct requests to Etendo Classic. URL that the browser uses for direct requests. In Docker hybrid mode, use localhost http://localhost:8080/etendo https://your-domain.com/etendo
    authentication.class Java class that manages authentication between the Main UI and Etendo Classic. Required for Secure Web Services authentication. com.etendoerp.etendorx.auth.SWSAuthenticationManager com.etendoerp.etendorx.auth.SWSAuthenticationManager
    ws.maxInactiveInterval Session duration (in seconds) for the Main UI WebSocket connection. Does not affect the session timeout of Etendo Classic. Recommended value is 3600 seconds (1 hour). 3600 3600
    next.public.app.url Public URL where users access the Main UI application. Must point to the reachable frontend URL; for local use, localhost is typical. http://localhost:3000 https://your.frontend.etendo.cloud

  2. Run the following commands to setup the module and update resources:

    Terminal
        ./gradlew setup

  3. Start the Docker services:

    Terminal
        ./gradlew resources.up

    This will start the Main UI container along with any other configured Docker services.

Accessing the Main UI

Once all services are running, the Main UI will be available at:

http://localhost:3000 (default port)

Info

The exact URL may vary depending on your Docker configuration.

Advanced Configuration

This section is for developers who want to contribute to or customize the Main UI codebase directly.

Requirements for Development

  1. Node.js version ^18.0.0 or higher
  2. pnpm version ^9.15.2 (package manager)
  3. All requirements from the basic installation above.

Manual Module Installation (Development Only)

For development environments, you need to install the required modules manually:

  • com.etendoerp.openapi
  • com.etendoerp.etendorx
  • com.etendoerp.metadata
  • com.etendoerp.metadata.template

Quick Clone Commands

cd modules

# Clone required modules for development
git clone git@github.com:etendosoftware/com.etendoerp.etendorx.git
git clone git@github.com:etendosoftware/com.etendoerp.openapi.git 
git clone git@github.com:etendosoftware/com.etendoerp.metadata.git
git clone git@github.com:etendosoftware/com.etendoerp.metadata.template.git

Development Project Structure

The workspace is organized as a unique environment with multiple packages:

com.etendorx.workspace-ui/
├── packages/
│   ├── api-client/          # API client for backend communication
│   ├── ComponentLibrary/    # Reusable UI components
│   └── MainUI/             # Main application
├── package.json
├── pnpm-workspace.yaml
└── README.md

Development Installation Steps

  1. Clone the Main UI development repository:

    git clone https://github.com/etendosoftware/com.etendorx.workspace-ui.git
cd com.etendorx.workspace-ui

  2. Install all project dependencies using pnpm:

    pnpm install

    This command will install dependencies for all packages in the workspace.

  3. Create a .env.local file in the packages/MainUI directory:

    cd packages/MainUI
touch .env.local

  4. Add your backend configuration:

    ETENDO_CLASSIC_URL=http://localhost:8080/etendo

    Info

    Replace the URLs with your actual Etendo backend URLs.

  5. Build the required packages in the correct order:

    # Build API Client first (dependency for other packages)
pnpm --filter @workspaceui/api-client build

# Build Component Library
pnpm --filter @workspaceui/componentlibrary build

  6. Launch the development server for the Main UI:

    pnpm dev

    The application will be available at http://localhost:3000 by default.

Development Workflow

Root-Level Commands (Recommended)

The workspace provides convenient aliases at the root level for common tasks:

Aliases
# Start Main UI development server
pnpm dev

# Build all packages
pnpm build

# Run tests across all packages
pnpm test

# Lint all packages
pnpm lint

# Fix lint issues automatically
pnpm lint:fix

# Format code across all packages
pnpm format

# Auto-fix formatting issues
pnpm format:fix

# Clean all build artifacts
pnpm clean

# Install dependencies
pnpm install

Individual Package Commands

Each package can also be run independently using pnpm workspace commands:

Commands
# Run MainUI development server
pnpm --filter @workspaceui/mainui dev

# Build API Client
pnpm --filter @workspaceui/api-client build

# Build Component Library
pnpm --filter @workspaceui/componentlibrary build

# Run tests for API Client
pnpm --filter @workspaceui/api-client test

# Lint specific package
pnpm --filter @workspaceui/mainui lint

Linting and Formatting

The project uses Biome for linting and formatting across all packages:

# Lint all packages
pnpm lint

# Fix lint issues
pnpm lint:fix

# Format code
pnpm format

# Auto-fix formatting
pnpm format:fix

Package Details

API Client (@workspaceui/api-client)

Contains TypeScript definitions and API functions for communicating with the Etendo backend. Provides:

  • Authentication APIs
  • Metadata APIs
  • Datasource APIs
  • Copilot integration APIs

Component Library (@workspaceui/componentlibrary)

A collection of reusable React components built with Material-UI. Includes:

  • Form components (inputs, selectors, etc.)
  • Navigation components
  • Modal and dialog components
  • Data display components

Main UI (@workspaceui/mainui)

The main Next.js application that provides the complete user interface. Features:

  • Modern React/TypeScript architecture
  • Server-side rendering with Next.js
  • Material-UI theme integration
  • Responsive design

Run Tests

Execute the test suites to ensure everything works correctly

# Run all tests
pnpm test

# Build for production
pnpm build

The development environment is now ready for building and customizing the Etendo Main UI.

This work is licensed under CC BY-SA 2.5 ES by Futit Services S.L.