Installing iDempiere

Overview

• What you’ll learn:
  • System requirements and how to prepare your environment for iDempiere installation
  • Step-by-step installation on Linux from source, including database setup, server configuration, and initial seeding
  • How to use the Docker-based installation as a faster alternative, and how to verify your installation works correctly
• Prerequisites: Lesson 2 — iDempiere Architecture Overview
• Estimated reading time: 20 minutes

Introduction

There is no substitute for hands-on experience when learning an ERP system. Reading about architecture and features provides a necessary foundation, but true understanding comes from working with a live installation. In this lesson, you will set up your own iDempiere instance — a personal sandbox where you can safely explore, experiment, and learn without any risk to production data.

We will cover two installation approaches: a traditional installation on Linux (which gives you full control and deeper understanding of the system’s components) and a Docker-based installation (which gets you up and running in minutes with minimal configuration). By the end of this lesson, you will have a working iDempiere system running on your machine and will have logged in for the first time.

System Requirements

Before you begin, ensure your system meets the following minimum requirements:

Hardware Requirements

These are requirements for a development or learning environment. Production deployments should be sized based on the number of concurrent users, transaction volume, and data growth expectations — typically requiring significantly more resources.

Software Requirements

• Operating System: Linux (Ubuntu 22.04+ or CentOS/RHEL 8+ recommended), macOS, or Windows (Linux is recommended for production and for following this guide)
• Java Development Kit (JDK): OpenJDK 17 or later (iDempiere 12 requires Java 17 as the minimum)
• PostgreSQL: Version 14 or later (we will use PostgreSQL in this guide as it is the community standard)
• Web Browser: Any modern browser — Chrome, Firefox, Edge, or Safari

For the Docker approach, you will additionally need:

• Docker Engine: Version 20.10 or later
• Docker Compose: Version 2.0 or later (usually included with Docker Desktop)

Method 1: Traditional Installation on Linux

This method walks you through every step of a manual installation. It takes more time but gives you a thorough understanding of how iDempiere is assembled and configured.

Step 1: Install Java 17

First, install the OpenJDK 17 development kit. On Ubuntu or Debian-based systems:

sudo apt update
sudo apt install openjdk-17-jdk -y

On CentOS, RHEL, or Fedora:

sudo dnf install java-17-openjdk-devel -y

Verify the installation:

java -version

You should see output indicating OpenJDK version 17 or later. If you have multiple Java versions installed, you can set the default using:

sudo update-alternatives --config java

Also set the JAVA_HOME environment variable by adding the following line to your ~/.bashrc or /etc/environment:

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64

Adjust the path based on your actual JDK installation location. Source the file to apply changes:

source ~/.bashrc

Step 2: Install and Configure PostgreSQL

Install PostgreSQL:

sudo apt install postgresql postgresql-contrib -y

Start and enable the PostgreSQL service:

sudo systemctl start postgresql
sudo systemctl enable postgresql

Create a database user for iDempiere. The default expected username is adempiere:

sudo -u postgres psql -c "CREATE ROLE adempiere WITH LOGIN SUPERUSER PASSWORD 'adempiere';"

Security note: In a production environment, you should never use adempiere as the password or grant SUPERUSER privileges. For a learning environment, this simplified setup is acceptable. The SUPERUSER role is needed during initial database seeding to install functions and extensions.

Verify that PostgreSQL is accepting connections:

psql -U adempiere -h localhost -c "SELECT version();"

If prompted for a password, enter adempiere. You may need to edit pg_hba.conf to allow password-based authentication for local connections. The file is typically located at /etc/postgresql/14/main/pg_hba.conf (adjust the version number). Change the local connection method from peer to md5:

# IPv4 local connections:
host    all    all    127.0.0.1/32    md5

After editing, restart PostgreSQL:

sudo systemctl restart postgresql

Step 3: Download iDempiere

Download the latest iDempiere release from GitHub. Navigate to github.com/idempiere/idempiere/releases and download the server package for your operating system.

Alternatively, download directly from the command line (replace the version number with the latest release):

cd /opt
sudo wget https://github.com/idempiere/idempiere/releases/download/v12.0.0/idempiereServer12.zip
sudo unzip idempiereServer12.zip

This creates a directory called idempiere.server (or similar, depending on the release). The directory contains:

• setup.sh / setup-console.sh — Configuration scripts
• idempiere-server.sh — The startup script
• plugins/ — Directory for OSGi plugin bundles
• data/seed/ — Database seed files for initial setup
• lib/ — Java libraries and dependencies

Step 4: Run the Setup Console

The setup process configures iDempiere to work with your specific environment (Java location, database connection, ports, etc.). Run the console-based setup:

cd /opt/idempiere.server
sudo sh setup-console.sh

The setup wizard will prompt you for several configuration values. For a standard learning environment, use these settings:

The setup process will:

1. Validate your Java installation
2. Test the database connection
3. Generate the idempiereEnv.properties configuration file
4. Create an SSL certificate keystore

Step 5: Import the Seed Database

The seed database contains the initial Application Dictionary, default chart of accounts, and the demo “Garden World” client data. Import it using the provided script:

cd /opt/idempiere.server/utils
sudo sh RUN_ImportIdempiere.sh

This script creates the idempiere database and loads the seed data. The process typically takes 5–15 minutes depending on your hardware. You will see progress messages as tables and data are loaded.

After the import completes, run the database migration scripts to apply any post-release updates:

cd /opt/idempiere.server/utils
sudo sh RUN_SyncDB.sh

This step ensures your database schema is fully synchronized with the application code.

Step 6: Start the iDempiere Server

You are now ready to start the iDempiere application server:

cd /opt/idempiere.server
sudo sh idempiere-server.sh &

The & runs the server in the background. Watch the console output for startup messages. The server typically takes 30–90 seconds to fully start. Look for a message like:

=== Server started ===
Web UI: http://localhost:8080/webui/

To view the log output at any time:

tail -f /opt/idempiere.server/log/idempiere_*.log

To stop the server gracefully:

cd /opt/idempiere.server
sudo sh idempiere-server.sh stop

The iDempiere Properties File

The setup process generates a configuration file called idempiereEnv.properties in the iDempiere home directory. This file stores all the connection parameters, file paths, and server settings. Key properties include:

# Application Server
ADEMPIERE_HOME=/opt/idempiere.server
ADEMPIERE_APPS_TYPE=jetty
ADEMPIERE_APPS_SERVER=localhost
ADEMPIERE_WEB_PORT=8080
ADEMPIERE_SSL_PORT=8443

# Database
ADEMPIERE_DB_TYPE=PostgreSQL
ADEMPIERE_DB_SERVER=localhost
ADEMPIERE_DB_PORT=5432
ADEMPIERE_DB_NAME=idempiere
ADEMPIERE_DB_USER=adempiere
ADEMPIERE_DB_PASSWORD=adempiere

# Java
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64

If you need to change any configuration after initial setup (for example, changing the database password or port), you can either re-run the setup console or carefully edit this file directly.

Method 2: Docker Installation (Recommended for Quick Start)

If you want to get iDempiere running quickly without manually installing Java, PostgreSQL, and configuring everything from scratch, Docker is the ideal approach. The iDempiere community maintains official Docker images.

Step 1: Install Docker

If Docker is not already installed, follow the official Docker installation guide for your platform at docs.docker.com/engine/install. On Ubuntu, the quick install is:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

Log out and back in for the group change to take effect, then verify Docker is working:

docker --version
docker compose version

Step 2: Create the Docker Compose File

Create a project directory and a docker-compose.yml file:

mkdir ~/idempiere-docker && cd ~/idempiere-docker

Create the file docker-compose.yml with the following content:

version: '3.8'

services:
  idempiere:
    image: idempiereofficial/idempiere:12
    container_name: idempiere
    ports:
      - "8080:8080"
      - "8443:8443"
      - "12612:12612"
    environment:
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_NAME=idempiere
      - DB_USER=adempiere
      - DB_PASS=adempiere
      - DB_ADMIN_PASS=postgres
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - idempiere_config:/opt/idempiere/configuration
      - idempiere_plugins:/opt/idempiere/plugins

  postgres:
    image: idempiereofficial/idempiere-postgres:12
    container_name: idempiere-postgres
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_USER=adempiere
      - POSTGRES_PASSWORD=adempiere
      - POSTGRES_DB=idempiere
    volumes:
      - idempiere_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U adempiere -d idempiere"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  idempiere_data:
  idempiere_config:
  idempiere_plugins:

This configuration defines two services: the PostgreSQL database (pre-seeded with iDempiere data) and the iDempiere application server. The depends_on with condition: service_healthy ensures iDempiere does not start until PostgreSQL is ready to accept connections.

Step 3: Start the Containers

docker compose up -d

Docker will download the images (this may take several minutes the first time) and start both containers. Monitor the startup progress with:

docker compose logs -f idempiere

Wait until you see the server started message, then press Ctrl+C to exit the log viewer.

Managing the Docker Environment

Useful Docker Compose commands for managing your iDempiere installation:

# Stop all containers
docker compose stop

# Start containers again
docker compose start

# Stop and remove containers (preserves data volumes)
docker compose down

# Stop and remove containers AND data volumes (complete reset)
docker compose down -v

# View running containers
docker compose ps

# View logs
docker compose logs -f idempiere
docker compose logs -f postgres

Verifying Your Installation

Regardless of which installation method you used, the verification process is the same.

Access the Web Client

Open your web browser and navigate to:

http://localhost:8080/webui/

You should see the iDempiere login screen. If you get a connection refused error, the server may still be starting — wait another minute and try again.

Log In with the Default Credentials

iDempiere ships with a demo company called “Garden World” that provides sample data for learning and testing. Log in using these default credentials:

After entering the username and password, you will see a role selection dialog with the following fields:

• Client: Select “Garden World” — this is the demo tenant
• Organization: Select “HQ” or “*” (asterisk means all organizations)
• Role: Select “GardenWorld Admin” — this gives you full administrative access
• Warehouse: Select “HQ Warehouse” — this sets the default warehouse context

Click OK to log in. You should now see the iDempiere main menu — a tree structure on the left side showing all available windows, reports, and processes organized by functional area.

Important: The default “System” client (used for global administration) has the credentials SuperUser/System. The GardenAdmin account is for the demo company and is what you should use for learning. Never use the System client for day-to-day business operations.

Quick Smoke Test

To confirm that the system is fully operational, perform these quick tests:

1. Open a window: In the menu tree, navigate to Material Management → Purchase Order. The window should open and display the Purchase Order entry form.
2. Query records: Click the magnifying glass (lookup) icon in the toolbar to switch to search mode, then click the green checkmark to execute the query. You should see existing demo purchase orders loaded in the grid.
3. Run a report: In the menu tree, navigate to Performance Analysis → Financial Report. Select “Balance Sheet” and click OK. A financial report should generate and display.

If all three tests work, your installation is fully functional and ready for learning.

Common Installation Issues and Solutions

Here are the most frequently encountered issues during iDempiere installation and how to resolve them:

Issue: Port 8080 Already in Use

Symptom: The server fails to start with a “port already in use” error.

Solution: Another application (such as Tomcat or another web server) is using port 8080. Either stop the other application or change iDempiere’s port. For the traditional installation, re-run the setup console and specify a different port (such as 8888). For Docker, change the port mapping in docker-compose.yml from "8080:8080" to "8888:8080".

Issue: Database Connection Refused

Symptom: Setup or startup fails with “Connection refused” when trying to reach PostgreSQL.

Solution: Verify that PostgreSQL is running (sudo systemctl status postgresql). Check that pg_hba.conf allows connections from the iDempiere host. Ensure the database port (default 5432) is not blocked by a firewall. For Docker, ensure the postgres container is running and healthy (docker compose ps).

Issue: Java Version Mismatch

Symptom: Setup completes but the server crashes on startup with UnsupportedClassVersionError.

Solution: iDempiere requires Java 17 or later. Run java -version to verify your version. If you have multiple Java versions installed, ensure JAVA_HOME points to Java 17+ and that this version appears first in your PATH.

Issue: Out of Memory Errors

Symptom: The server starts but becomes unresponsive or crashes with OutOfMemoryError.

Solution: Increase the Java heap size by editing the idempiere-server.sh script. Find the line containing -Xmx and increase the value:

# Change from default (e.g., -Xmx1024m) to a larger value
-Xmx2048m

For Docker, add a deploy section to the idempiere service in docker-compose.yml or set the IDEMPIERE_JAVA_OPTIONS environment variable.

Issue: Seed Database Import Fails

Symptom: The RUN_ImportIdempiere.sh script fails partway through.

Solution: The most common cause is the PostgreSQL user not having sufficient privileges. Ensure the adempiere user has SUPERUSER or at least CREATEDB privileges. Also verify that the idempiere database does not already exist from a failed previous attempt — drop it with dropdb -U adempiere idempiere before retrying.

Issue: Login Page Shows But Login Fails

Symptom: The web UI loads but you cannot log in with GardenAdmin/GardenAdmin.

Solution: The password may be case-sensitive — use exactly GardenAdmin (capital G and A). If the seed database was not properly imported, the user may not exist. Check the server log for authentication errors. You can also try the SuperUser/System credentials to access the System client.

Key Takeaways

• iDempiere requires Java 17+ (JDK, not just JRE), PostgreSQL 14+, and at least 4 GB of RAM for a development or learning environment.
• The traditional installation involves installing Java and PostgreSQL, downloading the iDempiere release, running the setup console, importing the seed database, and starting the server.
• The Docker installation provides a simpler and faster alternative using pre-built images that include a seeded database, requiring only Docker and a docker-compose.yml file.
• The default demo login credentials are GardenAdmin/GardenAdmin for the “Garden World” demo client.
• The idempiereEnv.properties file stores all configuration parameters and can be modified to change database connections, ports, and Java settings.
• Most common installation problems relate to port conflicts, database authentication, Java version mismatches, or insufficient memory allocation.

What’s Next

With your iDempiere instance up and running, the next lesson will guide you through the user interface. You will learn how to navigate the menu tree, understand the window and tab structure, use the toolbar buttons, work with different field types, and switch between grid and record views to become comfortable and productive in the iDempiere environment.