01 - Development environment setup
Prerequisites
You will need the following programs already installed on your system:
- git
- maven
- docker
- Your favorite IDE, we will be using IntelliJ
Creating the connector project
Then, find or create a suitable empty directory to store your project files and follow the steps:
- Clone Evolveum Polygon repository (keeping in mind the version, we will be using the 1.4.3.47 release)
- Add the following XML in your's .m2/settings.xml file
.m2/settings.xml (If the file already exists)
... <repositories> <repository> <!-- id expected by maven-archetype-plugin to avoid fetching from everywhere --> <id>archetype</id> <url>https://nexus.evolveum.com/nexus/repository/releases</url> <releases> <enabled>true</enabled> <checksumPolicy>fail</checksumPolicy> </releases> <snapshots> <enabled>true</enabled> <checksumPolicy>warn</checksumPolicy> </snapshots> </repository> </repositories> ....m2/settings.xml (Brand new)<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> <profiles> <profile> <id>default</id> <activation> <activeByDefault>true</activeByDefault> </activation> <repositories> <repository> <!-- id expected by maven-archetype-plugin to avoid fetching from everywhere --> <id>archetype</id> <url>https://nexus.evolveum.com/nexus/repository/releases</url> <releases> <enabled>true</enabled> <checksumPolicy>fail</checksumPolicy> </releases> <snapshots> <enabled>true</enabled> <checksumPolicy>warn</checksumPolicy> </snapshots> </repository> </repositories> </profile> </profiles> </settings> - Step into the repository folder and run the
mvn clean installcommand - Create the connector project using the Evolveum basic-connector-archetype template
- Choose a connector name (must be a valid Java Class name) and version (we will be using the default one):
- If everything went smoothly, we can now build the connector as a jar file
- Good job, we now have a basic development environment ready for our custom connector
Start a local MidPoint server
To quickly test our connector we will spin up a MidPoint instance with docker compose.
Outside our connector project root folder create a new folder and then create the following docker-compose.yml file:
services:
midpoint_data:
image: postgres:16-alpine
environment:
- POSTGRES_PASSWORD=db.secret.pw.007
- POSTGRES_USER=midpoint
- POSTGRES_INITDB_ARGS=--lc-collate=en_US.utf8 --lc-ctype=en_US.utf8
networks:
- net
volumes:
- midpoint_data:/var/lib/postgresql/data
data_init:
image: evolveum/midpoint:${MP_VER:-latest}-alpine
command: >
bash -c "
cd /opt/midpoint ;
bin/midpoint.sh init-native ;
echo ' - - - - - - ' ;
bin/ninja.sh -B info >/dev/null 2>/tmp/ninja.log ;
grep -q \"ERROR\" /tmp/ninja.log && (
bin/ninja.sh run-sql --create --mode REPOSITORY ;
bin/ninja.sh run-sql --create --mode AUDIT
) ||
echo -e '\\n Repository init is not needed...' ;
"
depends_on:
- midpoint_data
environment:
- MP_SET_midpoint_repository_jdbcUsername=midpoint
- MP_SET_midpoint_repository_jdbcPassword=db.secret.pw.007
- MP_SET_midpoint_repository_jdbcUrl=jdbc:postgresql://midpoint_data:5432/midpoint
- MP_SET_midpoint_repository_database=postgresql
- MP_INIT_CFG=/opt/midpoint/var
networks:
- net
volumes:
- midpoint_home:/opt/midpoint/var
midpoint_server:
image: evolveum/midpoint:${MP_VER:-latest}-alpine
container_name: midpoint_server
hostname: midpoint-container
depends_on:
data_init:
condition: service_completed_successfully
midpoint_data:
condition: service_started
command: [ "/opt/midpoint/bin/midpoint.sh", "container" ]
ports:
- 8080:8080
environment:
- MP_SET_midpoint_repository_jdbcUsername=midpoint
- MP_SET_midpoint_repository_jdbcPassword=db.secret.pw.007
- MP_SET_midpoint_repository_jdbcUrl=jdbc:postgresql://midpoint_data:5432/midpoint
- MP_SET_midpoint_repository_database=postgresql
- MP_SET_midpoint_administrator_initialPassword=Test5ecr3t
- MP_UNSET_midpoint_repository_hibernateHbm2ddl=1
- MP_NO_ENV_COMPAT=1
networks:
- net
volumes:
- midpoint_home:/opt/midpoint/var
api-server:
image: dotronglong/faker:stable
volumes:
- ./mocks:/app/mocks
ports:
- "3030:3030"
expose:
- 3030
networks:
- net
networks:
net:
driver: bridge
volumes:
midpoint_data:
midpoint_home:
Before starting this docker compose start, create in the docker-compose.yml folder a new folder called "mocks" and inside it a file called "users.json":
{
"request": {
"method": "GET",
"path": "/v1/users"
},
"response": {
"body": [
{ "id": 1, "name": "John" },
{ "id": 2, "name": "Marry" }
]
}
}
Now we can start this compose stack with the following command (in the docker-compose.yml folder):
Installing the connector
To quickly install the connector inside the Midpoint container we will use the docker compose cp command.
From within the docker-compose.yml folder we should be able to run the following command:
If everything went well you should see a similar message:
✔ midpoint_server copy ..\connector-sample-rest\target\connector-sample-rest-1.0-SNAPSHOT.jar to midpoint_server:/opt/midpoint/var/connid-connectors/ Copied
Finding the connector jar
You should be able to find the connector jar in your machine inside the target directory of the connector project. If you called your project "connector-sample-rest" with version "1.0-SNAPSHOT" the connector is located at "connector-sample-rest/target/connector-sample-rest-1.0-SNAPSHOT.jar"
The final check
To check if everything is ready we can try to create a resource in MidPoint and see if our new custom connector shows up.
- Login in MidPoint (http://localhost:8080) using the credentials "administrator" and "Test5ecr3t"
- Go to "Resources > New resource"
- See if your connector shows up, it should have the name you choose during the project creation
Now let's check if the fake Rest API is working by typing in the browser's search bar "http://localhost:3030/v1/users"