Improved edge docker install instructions. Fixed incorrect JSON format error

application/src/main/data/json/edge/install_instructions/docker/instructions.md

@@ -1,10 +1,6 @@
 ## Install edge and connect to cloud instructions
 
-### Localhost warning
-
-Localhost cannot be used for docker install - please update baseUrl to the IP address of your machine!
-
-Here is the list of commands, that can be used to quickly install and connect edge to the cloud using docker-compose.
+Here is the list of commands, that can be used to quickly install and connect edge to the cloud using docker compose.
 
 ### Prerequisites
 
@@ -12,7 +8,8 @@ Install <a href="https://docs.docker.com/engine/install/" target="_blank"> Docke
 
 ### Create data and logs folders
 
-Run following commands to create a directory for storing data and logs and then change its owner to docker container user, to be able to change user, chown command is used, which requires sudo permissions (command will request password for a sudo access):
+Run following commands to create directories for storing data and logs. These commands will change directories owner to *thingsboard* docker container user. 
+**chown** command requires sudo permissions to be able to change owner (command will request password for a sudo access):
 
 ```bash
 mkdir -p ~/.mytb-edge-data && sudo chown -R 799:799 ~/.mytb-edge-data
@@ -29,50 +26,66 @@ nano docker-compose.yml
 {:copy-code}
 ```
 
+${LOCALHOST_WARNING}
+
 Add the following lines to the yml file:
 
-```
-version: '2.2'
+```bash
+
+# Uncomment the following line if you are using docker-compose and not docker compose V2
+# version: '2.2'
+
 services:
-mytbedge:
-restart: always
-image: "thingsboard/tb-edge:3.4.1EDGE"
-ports:
-- "8080:8080"
-- "1883:1883"
-- "5683-5688:5683-5688/udp"
-environment:
-SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb-edge
-CLOUD_ROUTING_KEY: ${CLOUD_ROUTING_KEY}
-CLOUD_ROUTING_SECRET: ${CLOUD_ROUTING_SECRET}
-CLOUD_RPC_HOST: ${BASE_URL}
-volumes:
-- ~/.mytb-edge-data:/data
-- ~/.mytb-edge-logs:/var/log/tb-edge
-postgres:
-restart: always
-image: "postgres:12"
-ports:
-- "5432"
-environment:
-POSTGRES_DB: tb-edge
-POSTGRES_PASSWORD: postgres
-volumes:
-- ~/.mytb-edge-data/db:/var/lib/postgresql/data
+  mytbedge:
+    restart: always
+    image: "thingsboard/tb-edge:${EDGE_VERSION}"
+    ports:
+      - "8080:8080"
+      - "1883:1883"
+      - "5683-5688:5683-5688/udp"
+    environment:
+      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb_edge
+      CLOUD_ROUTING_KEY: ${CLOUD_ROUTING_KEY}
+      CLOUD_ROUTING_SECRET: ${CLOUD_ROUTING_SECRET}
+      CLOUD_RPC_HOST: ${BASE_URL}
+    volumes:
+      - ~/.mytb-edge-data:/data
+      - ~/.mytb-edge-logs:/var/log/tb-edge
+  postgres:
+    restart: always
+    image: "postgres:12"
+    ports:
+      - "5432"
+    environment:
+      POSTGRES_DB: tb_edge
+      POSTGRES_PASSWORD: postgres
+    volumes:
+      - ~/.mytb-edge-data/db:/var/lib/postgresql/data
 {:copy-code}
 ```
 
-### Ports warning [Optional]
-If ThingsBoard Edge is going to be running on the same machine where ThingsBoard server is running you’ll need to update docker compose port mapping.
+#### [Optional] Update bind ports 
+If ThingsBoard Edge is going to be running on the same machine where ThingsBoard server (cloud) is running you'll need to update docker compose port mapping.
 Please update next lines of docker compose:
+
+```bash
 ports:
-- “18080:8080”
-- “11883:1883”
-- “15683-15688:5683-5688/udp”
-  Please make sure ports above are not used by any other application.
+  - "18080:8080"
+  - "11883:1883"
+  - "15683-15688:5683-5688/udp"
+```
+Please make sure ports above are not used by any other application.
 
+#### Start ThingsBoard Edge
+Execute the following commands to pull and up using docker compose V2:
+
+```bash
+docker compose pull
+docker compose up
+{:copy-code}
+```
 
-Execute the following commands to up this docker compose directly:
+*NOTE*: If you are using outdated docker-compose (we recommend to use docker compose V2), execute the following commands:
 
 ```bash
 docker-compose pull
@@ -80,9 +93,9 @@ docker-compose up
 {:copy-code}
 ```
 
-### Open ThingsBoard Edge UI
+#### Open ThingsBoard Edge UI
 
-Once started, you will be able to open ThingsBoard Edge UI using the following link http://localhost:8080.
+Once started, you will be able to open ThingsBoard Edge UI using the following link http://localhost:8080
 
-If during installation process you have changed edge HTTP_BIND_PORT please use that port instead for Edge UI URL:
-http://localhost:HTTP_BIND_PORT
+*NOTE*: If you updated bind ports (optional step) please use updated port instead for Edge UI URL
+http://localhost:YOUR_UPDATED_PORT

application/src/main/data/json/edge/install_instructions/docker/localhost_warning.md

@@ -0,0 +1,4 @@
+#### WARNING - 'localhost (127.0.0.1)' is not supported
+
+Please note that your ThingsBoard base URL is **'localhost (127.0.0.1)'** at the moment.  
+**'localhost (127.0.0.1)'** cannot be used for docker containers - please update **CLOUD_RPC_HOST** environment variable below to the IP address of your machine (*docker **host** machine*). IP address must be next format **192.168.1.XX** or similar. In other case - Edge service, that is running in docker container, will not be able to connect to the cloud.

application/src/main/java/org/thingsboard/server/controller/BaseController.java

@@ -131,8 +131,7 @@ import org.thingsboard.server.queue.discovery.PartitionService;
 import org.thingsboard.server.queue.provider.TbQueueProducerProvider;
 import org.thingsboard.server.queue.util.TbCoreComponent;
 import org.thingsboard.server.service.component.ComponentDiscoveryService;
-import org.thingsboard.server.service.edge.EdgeInstallService;
-import org.thingsboard.server.service.edge.EdgeNotificationService;
+import org.thingsboard.server.service.edge.instructions.EdgeInstallService;
 import org.thingsboard.server.service.edge.rpc.EdgeRpcService;
 import org.thingsboard.server.service.entitiy.TbNotificationEntityService;
 import org.thingsboard.server.service.ota.OtaPackageStateService;

application/src/main/java/org/thingsboard/server/controller/EdgeController.java

@@ -56,6 +56,7 @@ import org.thingsboard.server.dao.exception.IncorrectParameterException;
 import org.thingsboard.server.dao.model.ModelConstants;
 import org.thingsboard.server.queue.util.TbCoreComponent;
 import org.thingsboard.server.service.edge.EdgeBulkImportService;
+import org.thingsboard.server.service.edge.instructions.EdgeInstallInstructions;
 import org.thingsboard.server.service.entitiy.edge.TbEdgeService;
 import org.thingsboard.server.common.data.sync.ie.importing.csv.BulkImportRequest;
 import org.thingsboard.server.common.data.sync.ie.importing.csv.BulkImportResult;
@@ -603,7 +604,7 @@ public class EdgeController extends BaseController {
     @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
     @RequestMapping(value = "/edge/instructions/{edgeId}", method = RequestMethod.GET)
     @ResponseBody
-    public String getEdgeDockerInstallInstructions(
+    public EdgeInstallInstructions getEdgeDockerInstallInstructions(
             @ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
             @PathVariable("edgeId") String strEdgeId,
             HttpServletRequest request) throws ThingsboardException {

application/src/main/java/org/thingsboard/server/service/edge/DefaultEdgeInstallService.java → application/src/main/java/org/thingsboard/server/service/edge/instructions/DefaultEdgeInstallService.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.thingsboard.server.service.edge;
+package org.thingsboard.server.service.edge.instructions;
 
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -40,18 +40,28 @@ public class DefaultEdgeInstallService implements EdgeInstallService {
 
     private static final String EDGE_DIR = "edge";
 
+    private static final String EDGE_VERSION = "3.4.2EDGE";
+
     private static final String EDGE_INSTALL_INSTRUCTIONS_DIR = "install_instructions";
 
     private final InstallScripts installScripts;
 
     @Override
-    public String getDockerInstallInstructions(TenantId tenantId, Edge edge, HttpServletRequest request) {
+    public EdgeInstallInstructions getDockerInstallInstructions(TenantId tenantId, Edge edge, HttpServletRequest request) {
+        String dockerInstallInstructions = readFile(resolveFile("docker", "instructions.md"));
         String baseUrl = request.getServerName();
-        String template = readFile(resolveFile("docker", "instructions.md"));
-        template = template.replace("${BASE_URL}", baseUrl);
-        template = template.replace("${CLOUD_ROUTING_KEY}", edge.getRoutingKey());
-        template = template.replace("${CLOUD_ROUTING_SECRET}", edge.getSecret());
-        return template;
+        if (baseUrl.contains("localhost") || baseUrl.contains("127.0.0.1")) {
+            String localhostWarning = readFile(resolveFile("docker", "localhost_warning.md"));
+            dockerInstallInstructions = dockerInstallInstructions.replace("${LOCALHOST_WARNING}", localhostWarning);
+            dockerInstallInstructions = dockerInstallInstructions.replace("${BASE_URL}", "!!!PLEASE_REPLACE_ME!!!");
+        } else {
+            dockerInstallInstructions = dockerInstallInstructions.replace("${LOCALHOST_WARNING}", "");
+            dockerInstallInstructions = dockerInstallInstructions.replace("${BASE_URL}", baseUrl);
+        }
+        dockerInstallInstructions = dockerInstallInstructions.replace("${EDGE_VERSION}", EDGE_VERSION);
+        dockerInstallInstructions = dockerInstallInstructions.replace("${CLOUD_ROUTING_KEY}", edge.getRoutingKey());
+        dockerInstallInstructions = dockerInstallInstructions.replace("${CLOUD_ROUTING_SECRET}", edge.getSecret());
+        return new EdgeInstallInstructions(dockerInstallInstructions);
     }
 
     private String readFile(Path file) {

application/src/main/java/org/thingsboard/server/service/edge/instructions/EdgeInstallInstructions.java

@@ -0,0 +1,17 @@
+package org.thingsboard.server.service.edge.instructions;
+
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@ApiModel
+@Data
+@AllArgsConstructor
+@NoArgsConstructor
+public class EdgeInstallInstructions {
+
+    @ApiModelProperty(position = 1, value = "Markdown with docker install instructions")
+    private String dockerInstallInstructions;
+}

application/src/main/java/org/thingsboard/server/service/edge/EdgeInstallService.java → application/src/main/java/org/thingsboard/server/service/edge/instructions/EdgeInstallService.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.thingsboard.server.service.edge;
+package org.thingsboard.server.service.edge.instructions;
 
 import org.thingsboard.server.common.data.edge.Edge;
 import org.thingsboard.server.common.data.id.TenantId;
@@ -22,6 +22,6 @@ import javax.servlet.http.HttpServletRequest;
 
 public interface EdgeInstallService {
 
-    String getDockerInstallInstructions(TenantId tenantId, Edge edge, HttpServletRequest request);
+    EdgeInstallInstructions getDockerInstallInstructions(TenantId tenantId, Edge edge, HttpServletRequest request);
 
 }

ui-ngx/src/app/core/http/edge.service.ts

@@ -21,7 +21,7 @@ import { HttpClient } from '@angular/common/http';
 import { PageLink, TimePageLink } from '@shared/models/page/page-link';
 import { PageData } from '@shared/models/page/page-data';
 import { EntitySubtype } from '@app/shared/models/entity-type.models';
-import { Edge, EdgeEvent, EdgeInfo, EdgeSearchQuery } from '@shared/models/edge.models';
+import { Edge, EdgeEvent, EdgeInfo, EdgeInstallInstructions, EdgeSearchQuery } from '@shared/models/edge.models';
 import { EntityId } from '@shared/models/id/entity-id';
 import { BulkImportRequest, BulkImportResult } from '@home/components/import-export/import-export.models';
 
@@ -114,7 +114,7 @@ export class EdgeService {
     return this.http.post<BulkImportResult>('/api/edge/bulk_import', entitiesData, defaultHttpOptionsFromConfig(config));
   }
 
-  public getEdgeDockerInstallInstructions(edgeId: string, config?: RequestConfig): Observable<any> {
-    return this.http.get<any>(`/api/edge/instructions/${edgeId}`, defaultHttpOptionsFromConfig(config));
+  public getEdgeDockerInstallInstructions(edgeId: string, config?: RequestConfig): Observable<EdgeInstallInstructions> {
+    return this.http.get<EdgeInstallInstructions>(`/api/edge/instructions/${edgeId}`, defaultHttpOptionsFromConfig(config));
   }
 }

ui-ngx/src/app/modules/home/pages/edge/edges-table-config.resolver.ts

@@ -51,7 +51,7 @@ import {
   AddEntitiesToCustomerDialogData
 } from '../../dialogs/add-entities-to-customer-dialog.component';
 import { HomeDialogsService } from '@home/dialogs/home-dialogs.service';
-import { Edge, EdgeInfo } from '@shared/models/edge.models';
+import { Edge, EdgeInfo, EdgeInstallInstructions } from '@shared/models/edge.models';
 import { EdgeService } from '@core/http/edge.service';
 import { EdgeComponent } from '@home/pages/edge/edge.component';
 import { EdgeTableHeaderComponent } from '@home/pages/edge/edge-table-header.component';
@@ -535,12 +535,12 @@ export class EdgesTableConfigResolver implements Resolve<EntityTableConfig<EdgeI
       $event.stopPropagation();
     }
     this.edgeService.getEdgeDockerInstallInstructions(edge.id.id).subscribe(
-      (edgeInstructionsTemplate: string) => {
+      (edgeInstructionsTemplate: EdgeInstallInstructions) => {
         this.dialog.open<EdgeInstructionsDialogComponent, EdgeInstructionsData>(EdgeInstructionsDialogComponent, {
           disableClose: false,
           panelClass: ['tb-dialog', 'tb-fullscreen-dialog'],
           data: {
-            instructions: edgeInstructionsTemplate
+            instructions: edgeInstructionsTemplate.dockerInstallInstructions
           }
         });
       }

ui-ngx/src/app/shared/models/edge.models.ts

@@ -167,3 +167,7 @@ export interface EdgeEvent extends BaseData<EventId> {
   uid: string;
   body: string;
 }
+
+export interface EdgeInstallInstructions {
+  dockerInstallInstructions: string;
+}