Ambiente de desenvolvimento

Antes de começar

Você vai precisar de:

• 8 GB de RAM no mínimo (16 GB é o confortável: Eclipse, servidor e PostgreSQL rodam juntos)
• 10 GB livres em disco (código, dependências do Maven e build)
• Linux, macOS ou Windows com WSL2. Os comandos deste módulo são para Ubuntu 24.04. No macOS, as diferenças aparecem em notas.
• Conhecimento básico de terminal, Git e Java

Nada disso exige experiência com iDempiere.

O que você vai construir

Ao final, você terá o iDempiere 14 rodando na sua máquina, compilado a partir do código-fonte, com o GardenWorld carregado. O GardenWorld é a empresa fictícia de demonstração que vem com o iDempiere: tem produtos, clientes, pedidos e estoque prontos para testar. Todo o guia usa ele como base.

Rodar a partir do código, e não do instalador, é o que permite debugar, ler o core e desenvolver plugins. É o ambiente de trabalho de quem desenvolve no iDempiere.

Passo a passo

1. Instale os pré-requisitos

No Ubuntu:

sudo apt-get install git openjdk-17-jdk

PostgreSQL 17, pelo repositório oficial do PostgreSQL:

sudo apt install curl ca-certificates
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc \
  --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc
. /etc/os-release
sudo sh -c "echo 'deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] \
  https://apt.postgresql.org/pub/repos/apt $VERSION_CODENAME-pgdg main' > \
  /etc/apt/sources.list.d/pgdg.list"
sudo apt update
sudo apt-get install postgresql-17

O iDempiere se conecta ao banco com usuário e senha. Por padrão, o PostgreSQL no Ubuntu aceita apenas a autenticação peer (pelo usuário do sistema operacional). Edite /etc/postgresql/17/main/pg_hba.conf, troque peer por scram-sha-256 nas linhas local e recarregue:

sudo systemctl reload postgresql

Defina uma senha para o superusuário do banco. Anote essa senha: ela é usada mais adiante.

sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'sua_senha_aqui'"

Confira:

java -version    # deve mostrar 17
psql --version   # 14 ou superior

2. Baixe o código

mkdir -p ~/sources && cd ~/sources
git clone https://github.com/idempiere/idempiere.git
cd idempiere
git switch master

A branch master é a do iDempiere 14. Evite pastas com espaço no nome: alguns scripts quebram.

3. Compile com o Maven

./mvnw verify

Esse comando baixa as dependências, compila todos os projetos e gera os binários. A primeira execução demora (de 15 a 40 minutos, dependendo da conexão) e ocupa cerca de 5 GB. Não precisa instalar o Maven: o ./mvnw baixa a versão certa.

Só siga em frente depois de ver BUILD SUCCESS no final.

4. Prepare o Eclipse

1. Abra o Eclipse e escolha a própria pasta do repositório (~/sources/idempiere) como workspace.
2. Desligue Project > Build Automatically. Com ele ligado, o Eclipse tenta compilar antes de a configuração estar completa e gera centenas de erros falsos.
3. Em Window > Preferences > General > Workspace: Text file encoding = UTF-8 e New text file line delimiter = Unix.
4. Em Java > Installed JREs, confirme que existe um JDK 17. Se não houver, adicione.
5. Em Java > Compiler, ajuste Compiler compliance level para 17.

5. Importe os projetos

1. File > Import > Maven > Existing Maven Projects
2. Em Root Directory, selecione a pasta do repositório.
3. Todos os projetos aparecem marcados. Clique em Finish.

6. Ative a target platform

Este é o passo que mais gera dúvida. O iDempiere é uma aplicação OSGi: as bibliotecas de que ele depende são definidas por uma target platform, e não pelo classpath comum do Java. Sem ela ativa, nada compila.

1. No projeto org.idempiere.p2.targetplatform, abra o arquivo org.idempiere.p2.targetplatform.mirror.target.
2. Espere o Eclipse resolver as dependências (a barra de progresso fica no canto inferior direito).
3. Clique em Set as Active Target Platform, no canto superior direito do editor.
4. Religue Project > Build Automatically e espere o build terminar.

A aba Problems não deve mostrar erros (avisos são normais). Se aparecerem erros, veja a seção Erros comuns.

7. Configure a conexão com o banco

No Eclipse, vá em Run > Run Configurations > Eclipse Application, selecione install.app e clique em Run. Uma janela de configuração vai abrir:

Clique em Test, depois em Save. Isso grava dois arquivos na pasta do repositório: idempiere.properties (a conexão) e idempiereEnv.properties (as configurações, incluindo a senha do postgres). O script do próximo passo lê os dois.

8. Importe o banco com o GardenWorld

cd ~/sources/idempiere
bash RUN_ImportIdempiereDev.sh

O script lê a conexão do idempiere.properties, cria o banco idempiere, importa o seed (que já inclui o GardenWorld) e aplica todos os scripts de migração pendentes. Leva alguns minutos.

Dois detalhes: o script pausa e pede Enter antes de importar, e usa o comando jar para extrair o seed. O jar vem com o JDK; se o terminal não encontrar, confira se o bin do JDK 17 está no PATH.

9. Suba o servidor

Run > Run Configurations > Eclipse Application > server.product > Run.

Quando o console parar de rolar, abra no navegador:

http://localhost:8080/webui/

(ou https://localhost:8443/webui/, aceitando o certificado autoassinado)

Prefira rodar em modo Debug (Run > Debug Configurations) desde já. Você vai precisar dele a partir do módulo 04, e o hábito economiza tempo.

10. Entre no sistema

Entre como GardenAdmin, digite Business Partner na busca do menu, abra a janela e navegue pelos clientes. Se os registros aparecem, o ambiente está pronto.

Checkpoint

Erros comuns

Desafio

Pare o servidor, rode git pull para trazer as últimas mudanças do master e aplique os novos scripts de migração no seu banco:

bash RUN_SyncDBDev.sh

Suba o servidor de novo e confira que tudo continua funcionando. Você vai repetir esse ciclo toda vez que atualizar o código, então vale fazer uma vez com calma.

Referência

• Caminho rápido no Linux: o projeto idempiere-dev-setup automatiza os passos 2 a 9 com scripts. Vale conhecer depois de fazer o processo manual pelo menos uma vez.
• Docker: para só usar o iDempiere, sem desenvolver, há uma imagem oficial. Não serve para este guia, porque você precisa do código no Eclipse.
• Documentação oficial da instalação para desenvolvimento (em inglês): Installing for Development.

Próximo módulo

01 · Seu primeiro CRUD sem código: você vai criar tabelas, janelas e menu sem escrever uma linha de Java.