Update documentation (#2451)

Signed-off-by: Avgustin Marinov <Avgustin.Marinov@bosch.com>

hawkbit-sdk/hawkbit-sdk-demo/src/main/java/org/eclipse/hawkbit/sdk/demo/device/DeviceApp.java

@@ -43,14 +43,12 @@ public class DeviceApp {
     }
 
     @Bean
-    HawkbitClient hawkbitClient(
+    HawkbitClient hawkbitClient(final HawkbitServer hawkBitServer, final Encoder encoder, final Decoder decoder, final Contract contract) {
-            final HawkbitServer hawkBitServer, final Encoder encoder, final Decoder decoder, final Contract contract) {
         return new HawkbitClient(hawkBitServer, encoder, decoder, contract);
     }
 
     @Bean
-    DdiTenant ddiTenant(final Tenant defaultTenant,
+    DdiTenant ddiTenant(final Tenant defaultTenant, final HawkbitClient hawkbitClient) {
-            final HawkbitClient hawkbitClient) {
         return new DdiTenant(defaultTenant, hawkbitClient);
     }
 
@@ -71,14 +69,17 @@ public class DeviceApp {
         Shell(final DdiTenant ddiTenant, final AuthenticationSetupHelper mgmtApi, final Optional<UpdateHandler> updateHandler) {
             this.ddiTenant = ddiTenant;
             this.mgmtApi = mgmtApi;
-            String controllerId = System.getProperty("demo.controller.id");
+            final String controllerId = System.getProperty("demo.controller.id");
-            String securityToken = System.getProperty("demo.controller.securityToken");
+            final String securityToken = System.getProperty("demo.controller.securityToken");
 
-            this.device = this.ddiTenant.createController(Controller.builder()
+            this.device = this.ddiTenant.createController(
+                    Controller.builder()
                             .controllerId(controllerId)
-                            .securityToken(ObjectUtils.isEmpty(securityToken) ?
+                            .securityToken(ObjectUtils.isEmpty(securityToken)
-                                    (ObjectUtils.isEmpty(ddiTenant.getTenant().getGatewayToken()) ? AuthenticationSetupHelper.randomToken() : securityToken) :
+                                    ? (ObjectUtils.isEmpty(ddiTenant.getTenant().getGatewayToken())
-                                    securityToken)
+                                        ? AuthenticationSetupHelper.randomToken()
+                                        : securityToken)
+                                    : securityToken)
                             .build(),
                     updateHandler.orElse(null)).setOverridePollMillis(10_000);
         }

hawkbit-security-core/src/main/java/org/eclipse/hawkbit/im/authentication/SpPermission.java

@@ -83,12 +83,6 @@ public final class SpPermission {
      */
     public static final String DELETE_REPOSITORY = "DELETE_REPOSITORY";
 
-    /**
-     * Permission to administrate the system on a global, i.e. tenant
-     * independent scale. That includes the deletion of tenants.
-     */
-    public static final String SYSTEM_ADMIN = "SYSTEM_ADMIN";
-
     /**
      * Permission to download repository artifacts of a software module.
      */
@@ -142,6 +136,12 @@ public final class SpPermission {
      */
     public static final String APPROVE_ROLLOUT = "APPROVE_ROLLOUT";
 
+    /**
+     * Permission to administrate the system on a global, i.e. tenant
+     * independent scale. That includes the deletion of tenants.
+     */
+    public static final String SYSTEM_ADMIN = "SYSTEM_ADMIN";
+
     /**
      * Return all permission.
      *

pom.xml

@@ -542,24 +542,15 @@
 
     <profiles>
         <profile>
-            <id>nexus_staging</id>
+            <id>publish</id>
             <activation>
                 <property>
-                    <name>!skipNexusStaging</name>
+                    <name>!skipPublish</name>
                 </property>
             </activation>
             <build>
                 <plugins>
                     <plugin>
-                        <!-- Use the Nexus Staging plugin as a full replacement
-                           for the standard Maven Deploy plugin. See https://github.com/sonatype/nexus-maven-plugins/tree/master/staging/maven-plugin
-                           why this makes sense :-) We can control whether we want to deploy to the
-                           Eclipse repo or Maven Central by a combination of the version being a SNAPSHOT
-                           or RELEASE version and property skipNexusStaging=true/false. In any case
-                           we can take advantage of the plugin's "deferred deploy" feature which makes
-                           sure that all artifacts of a multi-module project are deployed as a whole
-                           at the end of the build process instead of deploying each module's artifacts
-                           individually as part of building the module. -->
                         <groupId>org.sonatype.central</groupId>
                         <artifactId>central-publishing-maven-plugin</artifactId>
                         <version>${central.publishing.maven.plugin.version}</version>

site/content/concepts/authentication.md

@@ -26,7 +26,7 @@ There is a 32 alphanumeric character security-token for each created target with
 to authenticate the target at hawkBit through the HTTP-Authorization header with the custom scheme _TargetToken_.
 
 ```
-GET /SPDEMO/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
+GET /DEFAULT/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
 Host: your.hawkBit.server
 Authorization: TargetToken bH7XXAprK1ChnLfKSdtlsp7NOlPnZAYY
 ```
@@ -35,14 +35,9 @@ The target security token is provided in [DMF API](../../apis/dmf_api/) as part
 DMF clients to leverage the feature or can it be manually retrieved per target
 by [Management API](../../apis/management_api/) or in the [Management UI](../../ui) in the target details.
 
-Note: needs to be enabled in your hawkBit installation **and** in the tenant configuration. That allows both the
+Note: needs to be enabled in your hawkBit installation (See [DdiSecurityProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java)
-operator as well as the individual customer (if run in a multi-tenant setup) to enable this access method.
+for system-wide enablement) **and** in the tenant configuration (set [TenantConfigurationProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-repository/hawkbit-repository-api/src/main/java/org/eclipse/hawkbit/tenancy/configuration/TenantConfigurationProperties.java)#TenantConfigurationKey.AUTHENTICATION_MODE_TARGET_SECURITY_TOKEN_ENABLED, _authentication.targettoken.enabled_ to true). That allows both the
-See [DdiSecurityProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java)
+operator and the individual customer (if run in a multi-tenant setup) to enable this access method.
-for system wide enablement.
-
-The additional activation for the individual tenant:
-
-![Enable Target Token](../../images/security/targetToken.png)
 
 #### Gateway Security Token Authentication
 
@@ -55,19 +50,14 @@ also handy during development or for testing purposes. However, we generally rec
 allows to act _in the name of_ any device.
 
 ```
-GET /SPDEMO/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
+GET /DEVICE/controller/v1/0e945f95-9117-4500-9b0a-9c6d72fa6c07 HTTP/1.1
 Host: your.hawkBit.server
 Authorization: GatewayToken 3nkswAZhX81oDtktq0FF9Pn0Tc0UGXPW
 ```
 
-Note: needs to be enabled in your hawkBit installation **and** in the tenant configuration. That allows both the
+Note: needs to be enabled in your hawkBit installation (See [DdiSecurityProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java)
-operator as well as the individual customer (if run in a multi-tenant setup) to enable this access method.
+for system-wide enablement) **and** in the tenant configuration (set [TenantConfigurationProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-repository/hawkbit-repository-api/src/main/java/org/eclipse/hawkbit/tenancy/configuration/TenantConfigurationProperties.java)#TenantConfigurationKey.AUTHENTICATION_MODE_GATEWAY_SECURITY_TOKEN_ENABLED, _authentication.gatewaytoken.enabled_ to true). That allows both the
-See [DdiSecurityProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-security-core/src/main/java/org/eclipse/hawkbit/security/DdiSecurityProperties.java)
+operator and the individual customer (if run in a multi-tenant setup) to enable this access method.
-for system wide enablement.
-
-The additional activation for the individual tenant:
-
-![Enable Gateway Token](../../images/security/gatewayToken.png)
 
 ### Certificate Authentication by Reverse Proxy
 
@@ -86,17 +76,16 @@ fingerprint of the client certificate issuer(s) (as a comma separated list).
 To authenticate the request to hawBit the following condition shall be met:
 
 - the common name of the client certificate shall match the controller/client id
-- the SSL Issuer(s) hash of the presented client certificate shall be set for the tenant. For that, in Hawkbit's UI
+- the TLS Issuer(s) hash of the presented client certificate shall be set for the tenant. 
-  section, under system configuration, you shall enable 'Allow targets to authenticate via a certificate by an reverse
-  proxy' and set the hash of the client certificate issuer(s) (as a comma separated list).
 
-![Example Reverse Proxy Settings](../../images/security/exampleReverseProxySettings.png)
+For that you shall:
+- enable header authentication in the tenant configuration - set [TenantConfigurationProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-repository/hawkbit-repository-api/src/main/java/org/eclipse/hawkbit/tenancy/configuration/TenantConfigurationProperties.java)#TenantConfigurationKey.AUTHENTICATION_MODE_HEADER_ENABLED, _authentication.header.enabled_ to true. 
+- set / configure the issuer, for the tenant, in the tenant configuration - set [TenantConfigurationProperties](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-repository/hawkbit-repository-api/src/main/java/org/eclipse/hawkbit/tenancy/configuration/TenantConfigurationProperties.java)#AUTHENTICATION_MODE_HEADER_AUTHORITY_NAME.AUTHENTICATION_MODE_HEADER_ENABLED, _aauthentication.header.authority_ to issuer hash.
 
-You can use the following command to get the issuer hash:
+  You can use the following command to get the issuer hash
-
+  ```shell
-```shell
+  openssl x509 -in client_certificate.crt -issuer_hash -noout`
-openssl x509 -in client_certificate.crt -issuer_hash -noout`
+  ```
-```
 
 Here is an example diagram that shows all the communication between the hawkBit, reverse proxy and client. For the sake
 of simplification we assume that there are not intermediate certificates and the certificate and key are as follows:

site/content/concepts/authorization.md

@@ -90,14 +90,14 @@ to hawkBit permissions.
     - Artifacts
     - DS tags
 
-- READ_TARGET_SECURITY_TOKEN
-    - Permission to read the target security token. The security token is security concerned and should be protected.
-
 - DOWNLOAD_REPOSITORY_ARTIFACT
     - Permission to download artifacts of a software module (Note: READ_REPOSITORY allows only to read the metadata).
 
-- TENANT_CONFIGURATION
+- READ_TARGET_SECURITY_TOKEN
-    - Permission to administrate the tenant settings.
+  - Permission to read the target security token. The security token is security concerned and should be protected.
+
+- READ_TENANT_CONFIGURATION/TENANT_CONFIGURATION
+    - Permission to read/administrate the tenant settings.
 
 - READ_/UPDATE_/CREATE_/DELETE_/HANDLE_/APPROVE_ROLLOUT for:
     - Managing rollouts and provision targets through a rollout.

site/content/gettingstarted.md

@@ -14,6 +14,8 @@ It supports two configurations:
 * monolith - hawkbit-update-server
 * micro-service - hawkbit-mgmt-server, hawkbit-ddi-server, hawkbit-dmf-server.
 
+For more hawkBit Docker related info see [Docker run info](https://github.com/eclipse-hawkbit/hawkbit/blob/master/docker/README.md) and [Docker build info](https://github.com/eclipse-hawkbit/hawkbit/blob/master/docker/build/README.md) 
+
 ### A: Run hawkBit Update Server (Monolith) as Docker Container
 
 Start the hawkBit Update Server as a single container
@@ -112,7 +114,7 @@ and (only if you want to use the DMF feature):
 $ java -jar ./hawkbit-dmf/hawkbit-dmf-server/target/hawkbit-dmf-server-0-SNAPSHOT.jar
 ```
 
-Note: you could starte the Simple UI by:
+Note: you could start the Simple UI by:
 ```sh
 $ java -jar ./hawkbit-simple-ui/target/hawkbit-simple-ui-0-SNAPSHOT.jar
 ```
@@ -132,4 +134,6 @@ hawkbit.security.user.hawkbit.roles=TENANT_ADMIN
 ```
 which should remove the default _admin/admin_ user and add a hawkbit user _hawkbit_ with password _isAwesome!_ and a role _TENANT_ADMIN_. 
 
-You could create multiple users with specified roles.
+You could create multiple users with specified roles.
+
+For details how to configure docker compose based setup see the [Docker run info](https://github.com/eclipse-hawkbit/hawkbit/blob/master/docker/README.md) -> Configuration

site/content/guides/feignclient.md

@@ -1,76 +0,0 @@
----
-title: Feign Client
-parent: Guides
-weight: 32
----
-
-In this guide we describe how to create a [Feign](https://github.com/Netflix/feign) Rest Client based on
-a  [Spring Boot](http://projects.spring.io/spring-boot/) Application.
-<!--more-->
-
-## Create Feign REST Client
-
-hawkBit provides REST interfaces
-for [Management API](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-ddi-api)
-and [DDI API](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-ddi-api). Using this interfaces you can
-create a feign client with the help of
-the [feign inheritance support](http://projects.spring.io/spring-cloud/spring-cloud.html#spring-cloud-feign-inheritance).
-Our [example](https://github.com/eclipse-hawkbit/hawkbit-examples) modules demonstrate how to
-create [Feign](https://github.com/Netflix/feign) client resources. Here you can find
-the [Management API client resources](hhttps://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-mgmt-feign-client)
-and
-the [DDI client resources](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-ddi-feign-client).
-A
-small [simulator application](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-mgmt-simulator)
-demonstrates how you can interact with the hawkBit via the [Management API
-](http://www.eclipse.org/hawkbit/documentation/interfaces/management-api.html).
-
-## Example Management API simulator
-
-In the follow code section, you can a see a feign client resource example. The interface extend the origin api interface
-to declare the `@FeignClient`. The `@FeignClient`declares that a REST client with that interface should be created.
-
-```Java
-@FeignClient(url = "${hawkbit.url:localhost:8080}/" + MgmtRestConstants.TARGET_V1_REQUEST_MAPPING)
-public interface MgmtTargetClientResource extends MgmtTargetRestApi {
-}
-```
-
-This interface can be autowired and use as a normal java interface:
-
-```Java
-public class CreateStartedRolloutExample {
-
-    @Autowired
-    private MgmtTargetClientResource targetResource;
-
-
-    public void run() {
-        // create ten targets
-        targetResource.createTargets(new TargetBuilder().controllerId("00-FF-AA-0").name("00-FF-AA-0")
-                .description("Targets used for rollout example").buildAsList(10));
-    }
-
-```
-
-At [hawkbit-example-core-feign-client](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-core-feign-client)
-is a spring configuration to auto configure some beans, which can be reused for a own feign client.
-
-```Java
-@Configuration
-@ConditionalOnClass(Feign.class)
-@Import(FeignClientsConfiguration.class)
-public class FeignClientConfiguration {
-
-    @Bean
-    public ApplicationJsonRequestHeaderInterceptor jsonHeaderInterceptor() {
-        return new ApplicationJsonRequestHeaderInterceptor();
-    }
-
-    @Bean
-    public Contract feignContract() {
-        return new IgnoreMultipleConsumersProducersSpringMvcContract();
-    }
-}
-
-```

site/content/guides/runhawkbit.md

@@ -16,19 +16,21 @@ and no artifact storage.
 
 ## System Architecture
 
-This guide describes a target architecture that is more like one that you will expect in a production system.
+This guide describes a target architecture that you will probably expect in a production system.
 
 - hawkBit [Update Server](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-monolith/hawkbit-update-server).
 - [MariaDB](https://mariadb.org) for the repository.
 - [RabbitMQ](https://www.rabbitmq.com) for DMF communication.
-- For testing and demonstration purposes we will also use:
+
-- [hawkBit Device Simulator](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-device-simulator).
+For testing, demonstration or integrations purposes you could also use hawkBit SDK:
-- [hawkBit Management API example client](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-mgmt-feign-client).
+- [hawkBit SDK Management API client](https://github.com/eclipse-hawkbit/hawkbit/blob/master/hawkbit-sdk/hawkbit-sdk-commons/src/main/java/org/eclipse/hawkbit/sdk/HawkbitClient.java).
+- [hawkBit SDK / Simulator Device](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-sdk/hawkbit-sdk-device).
+- [hawkBit SDK / Simulator for DMF integration](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-sdk/hawkbit-sdk-dmf)
+- [hawkBit SDK Demo Devices](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-sdk/hawkbit-sdk-demo)
 
 ## Prerequisites
 
 - You have a working [hawkBit core build](https://github.com/eclipse-hawkbit/hawkbit).
-- You have a working [hawkBit examples build](https://github.com/eclipse-hawkbit/hawkbit-examples).
 
 ## Adapt hawkBit Update Server and Device Simulator to your environment.
 
@@ -42,44 +44,34 @@ a [new profile](http://docs.spring.io/spring-boot/docs/current/reference/htmlsin
 
 ```properties
 spring.jpa.database=MYSQL
-spring.datasource.url=jdbc:mariadb://localhost:3306/YOUR_SCHEMA
-spring.datasource.username=YOUR_USER
-spring.datasource.password=YOUR_PWD
 spring.datasource.driverClassName=org.mariadb.jdbc.Driver
+spring.datasource.url=jdbc:mariadb://localhost:3306/<YOUR_SCHEMA>
+spring.datasource.username=<YOUR_USER>
+spring.datasource.password=<YOUR_PWD>
 ```
 
-Note: On Ubuntu 18.04 with MariaDB 10.1 installed from the default repository via apt install _COLLATE option_ of
-database have to be changed manually to "latin1".
-For recent versions of MariaDB running on Ubuntu this is not required (
-cf. [system variables](https://mariadb.com/kb/en/differences-in-mariadb-in-debian-and-ubuntu), [issue](https://github.com/eclipse-hawkbit/hawkbit/issues/963))
-
 ### Configure RabbitMQ connection settings for update server and device simulator (optional).
 
 We provide already defaults that should work with a standard Rabbit installation. Otherwise configure the following in
 the `application.properties` of the two services:
 
 ```properties
-spring.rabbitmq.username=guest
-spring.rabbitmq.password=guest
-spring.rabbitmq.virtualHost=/
 spring.rabbitmq.host=localhost
 spring.rabbitmq.port=5672
+spring.rabbitmq.virtualHost=/
+spring.rabbitmq.username=guest
+spring.rabbitmq.password=guest
 ```
 
-### Adapt hostname of example scenario [creation script](https://github.com/eclipse-hawkbit/hawkbit-examples/blob/master/hawkbit-example-mgmt-simulator/src/main/resources/application.properties)
+### Adapt hostnames of demo simulator
 
 Should only be necessary if your system does not run on localhost or uses a different port than the example app.
 
-Adapt `application.properties` in this case:
+Adapt `application.properties` or pass system / env variables for Spring properties:
 
 ```properties
-hawkbit.url=localhost:8080
+hawkbit.server.mgmtUrl=<MGMT server host:MGMT port>
-```
+hawkbit.server.ddiUrl=<DDI server host:DDI port>
-
-or provide the parameter on command line:
-
-```properties
-hawkbit-example-mgmt-simulator-##VERSION##.jar --hawkbit.url=YOUR_HOST:PORT
 ```
 
 ## Compile & Run
@@ -88,16 +80,12 @@ hawkbit-example-mgmt-simulator-##VERSION##.jar --hawkbit.url=YOUR_HOST:PORT
 
 see [update server](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-monolith/hawkbit-update-server)
 
-### Compile & Run example scenario [creation script](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-example-mgmt-simulator) (optional)
+Note: you have to log into update server (e.g. via UI) before starting device / device simulator. Then hawkBit creates the mandatory tenant metadata.
+
+### Compile & Run demo simulator (optional)
+
+see [demo simulator](https://github.com/eclipse-hawkbit/hawkbit/tree/master/hawkbit-sdk/hawkbit-sdk-demo)
 
-This has to be done before the device simulator is started. hawkBit creates the mandatory tenant metadata with first
 login into either Management API (which is done by this client).
 
-However, this is not done by _DMF_ which is in fact used by the device simulator, i.e. without calling _Management API_
+## Enjoy hawkBit with a real database, artifact storage and all [interfaces](../../apis/) available
-first hawkBit would drop all _DMF_ messages as the tenant is unknown.
-
-### Compile & Run device simulator (optional)
-
-see [device simulator](https://github.com/eclipse-hawkbit/hawkbit-examples/tree/master/hawkbit-device-simulator)
-
-# Enjoy hawkBit with a real database, artifact storage and all [interfaces](../../apis/) available