Developer Setup
This page explains the steps necessary to be set up on the developer machines to start development of xpanse.
Prerequisite tools
- Java 21 - OpenJDK or Eclipse Adoptium
- GIT client
- Maven for Java applications
- Docker
- Docker compose
- NodeJS for UI module
- NPM for UI module.
- Go SDK
Setup and run xpanse project
To run the main xpanse application, the following steps must be executed.
- Fork the xpanse project.
- Clone the fork.
- We can then either compile the project using maven and start the application from CLI or just execute the main class XpanseApplication.java from your preferred IDE.
For developers, the minimum required profiles to be activated are noauth and dev.
./mvnw clean install -DskipTests
java -Dspring.profiles.active=noauth,dev -jar runtime/target/xpanse-runtime-*-SNAPSHOT.jar
To confirm the server is started, you can try to access the swagger UI from your browser.
http://localhost:8080/swagger-ui/index.html
The runtime can be controlled by activating different spring profiles and configuration parameters. More information about this can be found here.
Dependent Components
For regular development activities, xpanse needs some predefined applications from its stack based on the use case. But in most cases, the dependencies are kept as minimal as possible.
| Component | Mandatory | Default |
|---|---|---|
| Database | No | H2 Database |
| terra-boot | No | terraform-local |
| tofu-maker | No | opentofu-local |
| policy-man | No | Necessary only for testing policies |
| zitadel | No | We can also use 'noauth' mode |
| UI | No | We can test APIs directly |
| Redis Cache | No | Caffeine Cache |
To set up the above-mentioned components, we can either use a master docker-compose configuration which will start all components with default configuration.
Or we can also make start individual components based on the use case.
Master Docker Compose
By executing the below commands, we can start all components in one click.
# Download docker compose configuration file.
wget https://raw.githubusercontent.com/eclipse-xpanse/xpanse-relops/refs/heads/main/local/docker-compose.yml
# Run the database and application containers.
docker compose up --d
Then ensure to enable the spring profile local-docker-stack in xpanse application to ensure communication between docker containers
and the xpanse running on host.
If you think that any of the containers in the docker compose file isn't necessary for your use case, you can simply comment them out.
Individual Component Configuration
Database
By default, the development environment uses h2 database. Other than this, xpanse supports MySql as well at the moment.
If you wish to test with MySql, the MySql container can be started using the below command.
docker run --name mysql-db -p 3306:3306 -e MYSQL_PASSWORD=Xpanse@2023 -e MYSQL_ROOT_PASSWORD=xpanse -e MYSQL_DATABASE=xpanse -e MYSQL_USER=xpanse -d mysql:latest
Deployer Tools Installation
Depending on the type of deployers you intend to use, the below steps can be used to install the necessary deployers for local development.
These steps are necessary for development activities in the main xpanse application as well as deployer applications such as terra-boot or tofu-maker.
Auto Installation
During the deployment job, the deployer automatically downloads the necessary deployer binaries. If you have an active and stable connection, then there is nothing to be done in this case.
Using Docker Images
If you wish to use remote deployers such as terra-boot or tofu-maker then you can pull the latest docker containers and configure the xpanse runtime to use it.
In this case, the images already contain the default supported Terraform and OpenTofu versions respectively and additionally can install new versions on demand.
docker run -p 9090:9090 -d --name terra-boot --add-host=host.docker.internal:host-gateway ghcr.io/eclipse-xpanse/terra-boot:latest
docker run -p 9092:9092 -d --name tofu-maker --add-host=host.docker.internal:host-gateway ghcr.io/eclipse-xpanse/tofu-maker:latest
Then ensure to enable the spring profile local-docker-stack in xpanse application to ensure communication between docker containers
and the xpanse running on host.
Manual Installation
If you wish you manually install the deployers for whatever reason, then the below steps are necessary.
This method is necessary for local and remote deployment if the auto installation isn't possible.
Terraform CLI Installation
Terraform CLI can be installed using the steps from the official guide.
OpenTofu CLI Installation
Terraform CLI can be installed using the steps from the official guide.
Auth Layer Installation
No Auth Mode
If feature under development doesn't need any authentication or authorization features,
then it can be turned off completely by simply activating the noauth spring profile.
OAuth Mode
This is the default mode, and by default we use Zitadel as the identity provider. We build a fully configured development Zitadel application and DB images which contains all necessary configurations as well as test users.
Run the below command to start the OAuth stack.
# Download the docker compose configuration.
wget https://raw.githubusercontent.com/eclipse-xpanse/xpanse-iam/refs/heads/main/zitadel/local/run/docker-compose.yml
# Run the database and application containers.
docker compose up --d
Also, in case you wish to connect and check and change the configuration of the Zitadel instance, the admin user can be used
username—zitadel-admin@zitadel.localhost
password - Zitadel@123
The necessary end users with multiple combinations of roles and metadata can be found here . Here, we must use the provided email address as the username for OAuth application.
The zitadel-local spring profile already contains the configuration details necessary to connect to this local
Zitadel instance. The developer has no other extra task to be done.
More information about Zitadel can be found here.
policy-man
policy-man is a Golang-based application.
Manual start
We will need Golang SDK to be installed and the steps mentioned here can be used to start the application.
Docker Image
Easiest way to simply start the policy-man application using the released docker images.
docker run -p 8090:8090 -d --name policy-man ghcr.io/eclipse-xpanse/policy-man:latest --host=0.0.0.0
Irrespective of the above methods used to start policy-man, no changes are necessary on the xpanse side. The default configuration already points to correct local instances of the application.
UI Module
UI module requires node and NPM binaries installed on the developer machine.
Auth modes
Depending on the necessity, the UI can be started with or without auth mode.
# Start with noauth mode
npm run start
# start with auth mode
npm run start-with-zitadel-local
More documentation on UI can be found here.