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.

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 we are going to follow as an example is to mount Main UI Dockerized and Tomcat running as a local service. Other configurations are detailed in the section, Advanced Configurations.

1. Configure Services

Add the following lines to the gradle.properties file:

docker_com.etendoerp.mainui=true
ETENDO_CLASSIC_URL=http://your.etendo.instance/etendo
authentication.class=com.etendoerp.etendorx.auth.SWSAuthenticationManager

Replace your.etendo.instance with your actual Etendo URL.

For example: 

docker_com.etendoerp.mainui=true
ETENDO_CLASSIC_URL=http://localhost:8080/etendo
authentication.class=com.etendoerp.etendorx.auth.SWSAuthenticationManager

2. Set Up the Module

Run the following commands to set up the module and update resources:

./gradlew setup
./gradlew resources.up

3. Start Services

Start the Docker services:

./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)

The exact URL may vary depending on your Docker configuration.

Getting Help

If you encounter issues during installation:

  1. Check the Docker container logs.
  2. Verify all requirements are met.
  3. Ensure the Platform Extensions Bundle is properly installed.
  4. Review the configuration in gradle.properties.

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 may 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 monorepo 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 Development Repository

Clone the Main UI development repository:

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

2. Install Dependencies

Install all project dependencies using pnpm:

pnpm install

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

3. Environment Configuration

Create environment configuration files for development:

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

cd packages/MainUI
touch .env.local

Add your backend configuration:

NEXT_PUBLIC_BACKEND_URL=http://localhost:8080/etendo
NEXT_PUBLIC_API_BASE_URL=http://localhost:8080/etendo

Replace the URLs with your actual EtendoERP backend URLs.

4. Build Dependencies

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

5. Start Development Server

Launch the development server for the Main UI:

pnpm dev

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

Development Workflow

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

# 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:

# 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.