From cb3aa4b0ffbc814e577cb9adaa2d779fee4922ca Mon Sep 17 00:00:00 2001 From: Avgustin Marinov Date: Mon, 17 Nov 2025 12:45:02 +0200 Subject: [PATCH] Update the project readme's getting started (#2810) Signed-off-by: Avgustin Marinov --- README.md | 57 ++++++++++++++----- .../eclipse/hawkbit/sdk/HawkbitClient.java | 11 +++- hawkbit-sdk/hawkbit-sdk-demo/pom.xml | 3 + .../hawkbit/sdk/demo/device/DeviceApp.java | 7 ++- .../src/main/resources/application.properties | 1 + hawkbit-ui/pom.xml | 2 +- .../src/main/resources/application.properties | 2 +- 7 files changed, 60 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index d4ad71c5b..2e2b805f8 100644 --- a/README.md +++ b/README.md @@ -82,13 +82,13 @@ There are clients outside of the Eclipse IoT eco system as well, e.g.: ## SQL database -| Database | H2 | MySQL/MariaDB | PostgreSQL | -|-----------------------------------|:----------------------------------------------:|:---------------------------------------------------------------------:|:--------------------------------------------------------:| -| DDLs maintained by project | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| Test dependencies defined | :white_check_mark: | :white_check_mark: | :white_check_mark: | -| Docker image with driver provided | :white_check_mark: | :white_check_mark: (Tag: "-mysql") | :white_check_mark: | -| JDBC driver | [H2](https://github.com/h2database/h2database) | [MariaDB Connector/J](https://github.com/MariaDB/mariadb-connector-j) |[PostgreSQL JDBC Driver](https://github.com/pgjdbc/pgjdbc)| -| Status | Test, Dev | Production grade | Test, Dev | +| Database | H2 | MySQL/MariaDB | PostgreSQL | +|-----------------------------------|:----------------------------------------------:|:---------------------------------------------------------------------:|:----------------------------------------------------------:| +| DDLs maintained by project | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| Test dependencies defined | :white_check_mark: | :white_check_mark: | :white_check_mark: | +| Docker image with driver provided | :white_check_mark: | :white_check_mark | :white_check_mark: | +| JDBC driver | [H2](https://github.com/h2database/h2database) | [MariaDB Connector/J](https://github.com/MariaDB/mariadb-connector-j) | [PostgreSQL JDBC Driver](https://github.com/pgjdbc/pgjdbc) | +| Status | Test, Dev | Production grade | Test, Dev | ## (Optional) RabbitMQ: 3.6,3.7,3.8 @@ -103,9 +103,9 @@ Run with docker: docker run -d -p 8080:8080 hawkbit/hawkbit-update-server ``` -Open the update server in your browser: +The monolith update server will start on port 8080 with default configuration and H2 database. The default user `admin:admin` is configured. -[localhost:8080](http://localhost:8080) +The Swagger UI is available at: [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html) See below for how to build and run the update server on your own. In addition we have a [guide](https://www.eclipse.org/hawkbit/guides/runhawkbit/) for setting up a complete landscape. @@ -122,27 +122,54 @@ own [Spring Boot](https://projects.spring.io/spring-boot/) based application. # Clone, build and run hawkBit -## Build and start hawkBit [Update Server](hawkbit-monolith/hawkbit-update-server) +## Clone and build ```bash git clone https://github.com/eclipse-hawkbit/hawkbit.git cd hawkbit mvn clean install +``` + +## Start hawkBit [Update Server](hawkbit-monolith/hawkbit-update-server) + +```bash java -jar ./hawkbit-monolith/hawkbit-update-server/target/hawkbit-update-server-0-SNAPSHOT.jar ``` -## Start hawkBit [Device Simulator](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-device-simulator) (optional) +The monolith update server will start on port 8080 with default configuration and H2 database. The default user `admin:admin` is configured. + +The Swagger UI is available at: [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html) + +## Start hawkBit [UI](hawkbit-ui) ```bash -git clone https://github.com/eclipse-hawkbit/hawkbit-examples.git -cd hawkbit-examples -mvn clean install +java -jar ./hawkbit-ui/target/hawkbit-ui.jar ``` +Log in to [hawkbit UI](http://localhost:8088) with default `admin:admin` user. + +## Start hawkBit [Device Simulator](hawkbit-sdk/hawkbit-sdk-demo) + +* Enable gateway token authentication - on update server set tenant configuration properties (via [Swagger UI](http://localhost:8080/swagger-ui/index.html) or [hawkBit + UI](http://localhost:8088)): + * `authentication.gatewaytoken.enabled=true` and + * `authentication.gatewaytoken.key=`) +* Start demo Device Simulator - in the script below edit the environment properties accordingly. + * DDI url `http://localhost:8080` is default URL when running monolith update server. + * Set `hawkbit_tenant_gatewaytoken` to the configured gateway token (`authentication.gatewaytoken.key`)) + * Then run: + ```bash -java -jar ./hawkbit-device-simulator/target/hawkbit-device-simulator-#version#.jar +export hawkbit_server_ddiurl=http://localhost:8080 +export demo_controller_id=demo +export hawkbit_tenant_gatewaytoken=gw_token + +java -jar ./hawkbit-sdk/hawkbit-sdk-demo/target/hawkbit-sdk-demo-0-SNAPSHOT.jar ``` +* Execute `start` command in the simulator console to start the device simulation. +* Your device will be registered automatically on the update server and will start polling for updates. + ## Generate getting started data with the [Management API example](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-mgmt-simulator) (optional) ```bash diff --git a/hawkbit-sdk/hawkbit-sdk-commons/src/main/java/org/eclipse/hawkbit/sdk/HawkbitClient.java b/hawkbit-sdk/hawkbit-sdk-commons/src/main/java/org/eclipse/hawkbit/sdk/HawkbitClient.java index 6a7c3a201..c67fb7309 100644 --- a/hawkbit-sdk/hawkbit-sdk-commons/src/main/java/org/eclipse/hawkbit/sdk/HawkbitClient.java +++ b/hawkbit-sdk/hawkbit-sdk-commons/src/main/java/org/eclipse/hawkbit/sdk/HawkbitClient.java @@ -120,6 +120,7 @@ public class HawkbitClient { new DefaultHttpRequestRetryStrategy( Integer.getInteger("hawkbit.sdk.http.maxRetry", 3), TimeValue.ofSeconds(Integer.getInteger("hawkbit.sdk.http.defaultRetryIntervalSec", 10))); + private static final int BUFFER_SIZE = 8096; private final HawkbitServer hawkBitServer; @@ -131,10 +132,8 @@ public class HawkbitClient { private final BiFunction requestInterceptorFn; private final HttpRequestRetryStrategy httpRequestRetryStrategy; - private final int BUFFER_SIZE = 8096; - public HawkbitClient( - final HawkbitServer hawkBitServer, final Encoder encoder, final Decoder decoder, final Contract contract) { + public HawkbitClient(final HawkbitServer hawkBitServer, final Encoder encoder, final Decoder decoder, final Contract contract) { this(hawkBitServer, encoder, decoder, contract, null, null); } @@ -226,6 +225,7 @@ public class HawkbitClient { } private static final Cleaner CLEANER = Cleaner.create(); + private T service0(final Class serviceType, final Tenant tenant, final Controller controller) { final String url = controller == null ? hawkBitServer.getMgmtUrl() : hawkBitServer.getDdiUrl(); final HttpClientKey key = new HttpClientKey( @@ -364,6 +364,7 @@ public class HawkbitClient { } private static final String CRLF = "\r\n"; + private void writeMultipartFile( final MultipartFile multipartFile, final OutputStream out, final String boundary, final Annotation[] parametersAnnotations) throws IOException { @@ -382,6 +383,7 @@ public class HawkbitClient { out.write(CRLF.getBytes(StandardCharsets.UTF_8)); } } + private void writeSimpleFormData( final Object arg, final OutputStream out, final String boundary, final Annotation[] parameterAnnotations) throws IOException { if (arg != null) { @@ -406,13 +408,16 @@ public class HawkbitClient { } private static final String KEYSTORE_PASSWORD; + static { final Random random = new SecureRandom(); final byte[] bytes = new byte[16]; random.nextBytes(bytes); KEYSTORE_PASSWORD = Base64.getEncoder().encodeToString(bytes); } + private static final Map HTTP_CLIENTS = new HashMap<>(); + private static HttpClient httpClient(final HttpClientKey key) { synchronized (HTTP_CLIENTS) { final HttpClientWrapper httpClientWrapper = HTTP_CLIENTS.get(key); diff --git a/hawkbit-sdk/hawkbit-sdk-demo/pom.xml b/hawkbit-sdk/hawkbit-sdk-demo/pom.xml index c65ed37ed..7a4de8296 100644 --- a/hawkbit-sdk/hawkbit-sdk-demo/pom.xml +++ b/hawkbit-sdk/hawkbit-sdk-demo/pom.xml @@ -70,6 +70,9 @@ + + org.eclipse.hawkbit.sdk.demo.device.DeviceApp + diff --git a/hawkbit-sdk/hawkbit-sdk-demo/src/main/java/org/eclipse/hawkbit/sdk/demo/device/DeviceApp.java b/hawkbit-sdk/hawkbit-sdk-demo/src/main/java/org/eclipse/hawkbit/sdk/demo/device/DeviceApp.java index 564eefeae..00bea37f8 100644 --- a/hawkbit-sdk/hawkbit-sdk-demo/src/main/java/org/eclipse/hawkbit/sdk/demo/device/DeviceApp.java +++ b/hawkbit-sdk/hawkbit-sdk-demo/src/main/java/org/eclipse/hawkbit/sdk/demo/device/DeviceApp.java @@ -24,6 +24,7 @@ import org.eclipse.hawkbit.sdk.device.DdiController; import org.eclipse.hawkbit.sdk.device.DdiTenant; import org.eclipse.hawkbit.sdk.device.UpdateHandler; import org.eclipse.hawkbit.sdk.mgmt.AuthenticationSetupHelper; +import org.springframework.beans.factory.annotation.Value; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.annotation.Bean; @@ -66,11 +67,11 @@ public class DeviceApp { private final AuthenticationSetupHelper mgmtApi; @SuppressWarnings("java:S3358") - Shell(final DdiTenant ddiTenant, final AuthenticationSetupHelper mgmtApi, final Optional updateHandler) { + Shell(final DdiTenant ddiTenant, final AuthenticationSetupHelper mgmtApi, final Optional updateHandler, + @Value("${demo.controller.id:demo}") final String controllerId, + @Value("${demo.controller.securityToken:#{null}") final String securityToken) { this.ddiTenant = ddiTenant; this.mgmtApi = mgmtApi; - final String controllerId = System.getProperty("demo.controller.id"); - final String securityToken = System.getProperty("demo.controller.securityToken"); this.device = this.ddiTenant.createController( Controller.builder() diff --git a/hawkbit-sdk/hawkbit-sdk-demo/src/main/resources/application.properties b/hawkbit-sdk/hawkbit-sdk-demo/src/main/resources/application.properties index ecd3ddf61..deb56b545 100644 --- a/hawkbit-sdk/hawkbit-sdk-demo/src/main/resources/application.properties +++ b/hawkbit-sdk/hawkbit-sdk-demo/src/main/resources/application.properties @@ -9,6 +9,7 @@ # spring.main.web-application-type=none +spring.shell.interactive.enabled=true logging.level.org.eclipse.hawkbit=DEBUG diff --git a/hawkbit-ui/pom.xml b/hawkbit-ui/pom.xml index 80aa4df34..eb9a84a41 100644 --- a/hawkbit-ui/pom.xml +++ b/hawkbit-ui/pom.xml @@ -101,7 +101,7 @@ spring-boot-maven-plugin false - hawkBit-UI + hawkbit-ui org.eclipse.hawkbit.ui.HawkbitUiApp diff --git a/hawkbit-ui/src/main/resources/application.properties b/hawkbit-ui/src/main/resources/application.properties index b24aa545b..8ef42b8c7 100644 --- a/hawkbit-ui/src/main/resources/application.properties +++ b/hawkbit-ui/src/main/resources/application.properties @@ -27,6 +27,6 @@ vaadin.launch-browser=true # To improve the performance during development. # For more information https://vaadin.com/docs/flow/spring/tutorial-spring-configuration.html#special-configuration-parameters vaadin.allowed-packages=com.vaadin,org.vaadin,dev.hilla,org.eclipse.hawkbit -spring.application.name=hawkBit-UI +spring.application.name=hawkbit-ui server.servlet.session.persistent=false ### Vaadin end ### \ No newline at end of file