# 00 · Ambiente de desenvolvimento

Fonte: https://muriloht.com/idempiere/00-ambiente (Guia iDempiere, Murilo H. Torquato). Versão alvo: iDempiere 14.

Objetivos:
- Compilar o iDempiere 14 a partir do código-fonte
- Rodar o servidor dentro do Eclipse
- Entrar no GardenWorld e no perfil System

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

| Ferramenta | Versão |
|---|---|
| JDK | OpenJDK **17** |
| PostgreSQL | **17** (qualquer versão a partir da 14 funciona) |
| Eclipse | **Eclipse IDE for Enterprise Java and Web Developers**, 2025-12 ou mais recente |
| Git | qualquer versão recente |

No Ubuntu:

```bash
sudo apt-get install git openjdk-17-jdk
```

PostgreSQL 17, pelo repositório oficial do PostgreSQL:

```bash
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:

```bash
sudo systemctl reload postgresql
```

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

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

> **macOS:** `brew install openjdk@17 postgresql@17 git coreutils`. O `coreutils` é obrigatório: o script de importação do banco usa o `greadlink`.

Confira:

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

### 2. Baixe o código

```bash
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

```bash
./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:

| Campo | Valor |
|---|---|
| iDempiere Home | a pasta do repositório |
| Database Name | `idempiere` |
| DB Admin Password | a senha do `postgres` que você definiu no passo 1 |
| Database User / Password | `adempiere` / uma senha à sua escolha |
| Web Port / SSL | `8080` / `8443` (troque se estiverem ocupadas) |
| DB Already Exists | **desmarcado** (o banco ainda não existe) |

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

```bash
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`.

> **Alternativa oficial:** a documentação do projeto descreve outro caminho, gerando a configuração com o `console-setup-alt.sh` do produto compilado. Os dois chegam no mesmo lugar. Veja [Importing DB Seed Manually](https://docs.idempiere.org/docs/basic-installation/installing-for-development/manual-install/importing-db-seed-manually).

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

| Usuário | Senha | Para quê |
|---|---|---|
| `GardenAdmin` | `GardenAdmin` | Usar o sistema como administrador da empresa GardenWorld |
| `GardenUser` | `GardenUser` | Usar o sistema como usuário comum |
| `System` | `System` | Mexer no Dicionário da Aplicação (a partir do módulo 01) |
| `SuperUser` | `System` | Acessar os dois mundos com o mesmo login |

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.

> Essas senhas são públicas e só servem para desenvolvimento. Nunca use o seed de demonstração em produção.

## Checkpoint

- [ ] java -version mostra a versão 17
- [ ] ./mvnw verify termina com BUILD SUCCESS
- [ ] O Eclipse abre o workspace sem erros de compilação (aba Problems vazia de erros)
- [ ] O banco idempiere existe e tem o GardenWorld importado
- [ ] O server.product sobe e a tela de login abre no navegador
- [ ] Consigo entrar como GardenAdmin no cliente GardenWorld
- [ ] Consigo entrar como System no perfil System

## Erros comuns

| Sintoma | Causa provável | Correção |
|---|---|---|
| Centenas de erros de compilação no Eclipse | Target platform não ativada | Refaça o passo 6 e depois **Project > Clean > Clean all projects** |
| `Unsupported class file major version` ou erro parecido | Eclipse ou Maven usando um Java diferente do 17 | Confira `JAVA_HOME` e **Installed JREs** |
| `password authentication failed for user "postgres"` | `pg_hba.conf` ainda em `peer` ou senha errada | Revise o passo 1 e recarregue o PostgreSQL |
| Servidor não sobe: `Address already in use` | Porta 8080 ou 8443 ocupada | Rode o `install.app` de novo com outras portas |
| `The 'greadlink' command is not installed` (macOS) | Falta o coreutils | `brew install coreutils` |
| Eclipse lento ou travando | Pouca memória para a IDE | Aumente o `-Xmx` no `eclipse.ini` (por exemplo, `-Xmx4g`) |
| `RUN_ImportIdempiereDev.sh` diz que não há `idempiere.properties` | O `install.app` não foi salvo | Refaça o passo 7 e confirme que o arquivo existe na pasta do repositório |

## 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
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](https://github.com/hengsin/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](https://docs.idempiere.org/docs/basic-installation/docker). 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](https://docs.idempiere.org/docs/category/installing-for-development).

## Próximo módulo

[01 · Seu primeiro CRUD sem código](https://muriloht.com/idempiere/01-primeiro-crud): você vai criar tabelas, janelas e menu sem escrever uma linha de Java.