Skip to main content

Deployment Issues

How to reinstall​

  1. Stop services that may already be running, and execute the following command in the root directory of the manager: (Under normal circumstances, the output of stopped is successful);

    bash ./service.sh stopall
    rm -f ./installer.stage

  2. Backup service files (the specific backup target location can be customized, generally not required during first deployment, you can directly rm -rf /data/hap/);

    mv /data/hap/ /home/hapbak/

  3. Confirm again whether it has been cleaned up, and execute the following commands respectively to ensure that the output results are all empty (if not, the corresponding process will be killed);

    docker ps | grep hap
    netstat -ntpl | grep 38881
    ps -ef | grep 'hap\|service.sh' | grep -v grep

  4. Execute the following command to restart the manager. After successful startup, visit http://{Server IP}:38881 to install again.

    bash ./service.sh start

Initialization failed​

When the first deployment page prompts that initialization failed, please execute the following command on the server to observe the output. Usually exception information will be output in the terminal, and you can further determine the problem based on the output content.

bash ./service.sh restartall

If there is a iptables failed keyword error, usually the iptables rules will be cleared when firewalld is closed, so you need to restart Docker to regenerate the default iptables rules, and then [reinstall](#How to reinstall)

After the initialization is completed, it prompts "The account has been logged out, please log in again"​

Basic cause of the problem: The server hard disk IOPS performance is low, and the hard disk IO is full during the service startup process, causing the storage component service to start slowly.

Solution:

Add environment variables in the /data/hap/script/docker-compose.yaml configuration file to delay the microservice startup time.

After adding the environment variables, execute bash service.sh restartall in the installation manager directory to restart the service. After the restart is completed, refill the initial information.

services:
  app:
    environment:
      ENV_ROLE_MODE_WAITMS: "90000"

  • The unit of the ENV_ROLE_MODE_WAITMS environment variable value is milliseconds, and the default value is 30 seconds.

  • In this example, increase the default value of the environment variable to 90 seconds, delay the startup of the microservice for 90 seconds, and first ensure that the storage component process completes startup before the microservice starts.

  • If the problem still cannot be solved, you can continue to increase the waiting time, such as 180 seconds, and then restart the service for testing.

  • Adjusting the value of this environment variable will cause the overall startup speed of the service to slow down. It is more recommended to deploy the service on a high-performance hard disk, otherwise you may encounter performance problems during use. For hard disk performance indicators, please refer to Basic Server Performance Requirements.

Service response code error encountered after service startup was completed (Service response code error)​

​Problem phenomenon​​: A "Service response code error" error appears after the service is started, but it may still be accessible normally.

​Cause of the problem​​: In an environment with low disk I/O performance (such as using a mechanical hard disk as a data disk), the service will start slowly. A health check will be performed 5 minutes after the service starts. When the health check times out and no response is received, the system will throw this error.

Check method:

  1. Try to access the service page. If you can access and use it normally, it means that the core service has been started.

  2. Execute docker logs $(docker ps | grep -E 'hap-community|hap:' | awk '{print $1}') to check the microservice container log:

    • Normally, there should be mainly INFO level logs, which means normal.

    • If ERROR or WARN level logs appear, you need to pay special attention. ​

​Follow-up recommendations​: In order to ensure the stable operation of the service, ensure performance and data storage security, it is strongly recommended to deploy the service on high-performance disks. The standard disks of current mainstream cloud service providers can meet the minimum basic performance requirements. For physical machine deployment, it is recommended to use SSD disks.

How to configure auto-start at boot​

Taking the path where the installation manager is located as /usr/local/MDPrivateDeployment/ as an example, here are several common operating system configuration methods for reference:

Implementation method: Based on the systemd service that comes with the operating system, write the service startup command into the customized manager.service service unit file to realize automatic startup of the service at boot.

  1. Edit the /etc/systemd/system/manager.service file and add a service startup command.

The manager.service file can be created directly through the following command:

cat > /etc/systemd/system/manager.service <<'EOF'
[Unit]
Description=Manager
After=docker.service
Wants=docker.service
[Service]
Type=oneshot
WorkingDirectory=/usr/local/MDPrivateDeployment
ExecStart=/bin/bash service.sh restartall
RemainAfterExit=yes
StandardOutput=append:/usr/local/MDPrivateDeployment/manager.log
StandardError=append:/usr/local/MDPrivateDeployment/manager.log
[Install]
WantedBy=multi-user.target
EOF

  1. Enable auto-start at boot:

    systemctl daemon-reload
    systemctl enable manager

After the server is restarted, the service cannot start normally.​

Execute the following commands in the root directory of the manager and wait for the startall command to complete. If startup is not included, please refer to [Configuring startup](#How to configure automatic startup at startup)

bash ./service.sh stopall
rm -f service.pid
bash ./service.sh startall

The key is lost and the server ID is not displayed.​

  1. Stop the service and execute bash ./service.sh stopall in the root directory of the manager;
  2. Execute command ps -ef | grep 'hap\|service.sh' | grep -v grep (if there is output, kill all corresponding pids);
  3. Execute bash ./service.sh startall and wait for the command execution to complete.

Possible reasons:

  • Server resources are saturated, causing the manager process to be forcibly terminated
  • The server time is inaccurate, resulting in incorrect judgment of the key validity period
  • The server restarts, but the manager is not set to start automatically at boot.
  • The operation of service start and stop commands is not standardized, resulting in the failure to identify the key's periodic valid status.

Kafka startup failed​

In standalone mode, the Kafka service runs in the container as a built-in component. When the Kafka service is unavailable, phenomena including but not limited to the following may occur:

  • Workflow cannot run properly;
  • Slow submission of worksheet row record data;
  • The statistical function is abnormal or the data is out of sync.

During the running process of Kafka, message data and location information will be stored in the local data directory. When the system is shut down abnormally (such as a power outage or insufficient memory causing the process to be forcibly terminated), the following problems may occur in the metadata files of Kafka and Zookeeper:

  • The log data file is damaged: the message log or location file is not completely written, causing the verification to fail;
  • Zookeeper status is inconsistent: the transaction log is not submitted correctly, causing Kafka to be unable to load cluster metadata when starting;
  • Kafka startup stuck: Kafka detected inconsistent indexes or log files during the recovery phase and entered an abnormal recovery cycle.

Since Kafka does not have a cluster copy mechanism in standalone mode, such errors cannot be automatically recovered, and the Kafka service can only be reinitialized by clearing the abnormal data.

When checking the container logs, if you find that the Kafka service cannot be started, you can follow the steps below to fix it:

  1. Execute bash ./service.sh stopall in the root directory of the manager to stop the service;

  2. Execute the following command to rename the data directories of Kafka and Zookeeper to clear abnormal status data:

    mv /data/hap/script/volume/data/kafka{,_bak_$(date +%Y%m%d%H%M)}
    mv /data/hap/script/volume/data/zookeeper{,_bak_$(date +%Y%m%d%H%M)}

  3. Execute bash ./service.sh startall in the root directory of the manager to start the service;

Upload attachment interface timeout​

Uploading files larger than 4MB uses multipart upload mode by default. In some cases, due to network reasons, the upload of a certain segment may time out, causing the entire file to fail to upload. To solve this problem, you can add the following rules (nginx as an example)

location ~ /file {
  proxy_set_header Host $http_host;
  proxy_read_timeout 1800s;
  client_max_body_size 20480m;
  proxy_pass http://hap; #Adjust here according to the actual upstream name
}

How to enable sub-path deployment​

Add the environment variable ENV_MINGDAO_SUBPATH in the app service of the configuration file, as follows:

services:
  app:
    environment:
      ENV_MINGDAO_SUBPATH: "/hap"

How to enable dual access addresses​

Add environment variables ENV_EXT_MINGDAO_PROTO, ENV_EXT_MINGDAO_HOST, ENV_EXT_MINGDAO_PORT (a set of configurations corresponding to ENV_MINGDAO_PROTO, ENV_MINGDAO_HOST, ENV_MINGDAO_PORT) in the app service of the configuration file, expose port 18880 (specifically corresponding to the host port customization, 18880 is still used here), and then resolve http://example1.domain.com to 18880 of the host port (If you directly access the host through the internal and external network IP, you can ignore the domain name resolution configuration), as follows:

services:
  app:
    environment:
      ENV_EXT_MINGDAO_PROTO: "http"
      ENV_EXT_MINGDAO_HOST: "example1.domain.com"
      ENV_EXT_MINGDAO_PORT: "18880"
    ports:
      - 8880:8880
      - 18880:18880

For more details, please refer to Multiple Address Configuration Instructions

How to modify the default storage path​

Run tail -n 3 service.sh in the directory where the installation manager is located to see the version number of the installation manager.

New installation​

Before starting the manager (that is, before executing ./service.sh start), modify the installDir parameter value in service.sh.

Migration​

If it has already been installed, modify the installDir parameter value in service.sh. When the service is stopped, move all the files in the /data/hap directory to installDir, and then restart the service.

How to access each storage component externally​

In standalone deployment mode, the dependent storage components will be started by default, including: mysql, mongodb, redis, kafka, file. The ports of these components are not exposed to the outside world by default. If external connections are required, the ports can be exposed by modifying the ports field of the corresponding container in the configuration file (default /data/hap/script/docker-compose.yaml), as follows:

Please read the document about Data Security carefully before operation ⚠️⚠️⚠️

services:
  sc:
    ports:
      - 3306:3306   # mysql
      - 27017:27017 # mongodb
      - 6379:6379   # redis
      - 9092:9092   # kafka
      - 9000:9000   # file
      - 9200:9200   # elasticsearch

How to partially enable external storage components​

In standalone deployment mode, add the environment variable ENV_STANDALONE_DISABLE_SERVICES in the configuration file (default /data/hap/script/docker-compose.yaml). It supports setting mysql, mongodb, redis, kafka, and file. Multiple ones are separated by English commas, as follows:

services:
  app:
    environment:
      ENV_STANDALONE_DISABLE_SERVICES: "redis,file"

To enable custom storage components, you need to configure the connection address of the corresponding service through environment variables. Please refer to Environment Variable Description

How to customize MongoDB’s maximum memory usage​

Add the environment variable ENV_MONGODB_CACHEGB in the configuration file. The default is (physical memory-18)/2 (unit: G), as follows:

services:
  app:
    environment:
      ENV_MONGODB_CACHEGB: "6"

How to customize the maximum memory usage of Redis​

Add the environment variable ENV_REDIS_MAXMEMORY in the configuration file. It is not restricted by default. After restriction, it will be eliminated based on the LRU algorithm, as follows:

services:
  app:
    environment:
      ENV_REDIS_MAXMEMORY: "5gb"

How to be referenced by other systems through IFrame​

By default, it supports embedding in IFrames under the same domain. If you want to be embedded in other domain name systems, you can add the environment variable ENV_FRAME_OPTIONS in the configuration file. It supports: ALLOWALL, SAMEORIGIN, DENY, and ALLOW-FROM uri, as follows:

services:
  app:
    environment:
      ENV_FRAME_OPTIONS: "ALLOWALL"

Set IP whitelist access policy​

To allow restrictions on access source IP, configuration needs to be based on the first-layer proxy for client access. For specific configuration examples, refer to:

#Example 1
http {
  server {
    ......
    #Allow 192.168.0.1 IP access
    allow 192.168.0.1;
    #Allow IP access in the 192.168.0.1/32 network segment
    allow 192.168.0.1/32;
    #Deny access to all other IP addresses
    deny all;

    location / {
      ......
    }
  }
}

#Example 2
http {
  server {
    ......

    location / {
      #Allow 192.168.0.1 IP access
      allow 192.168.0.1;
      #Allow IP access in the 192.168.0.1/32 network segment
      allow 192.168.0.1/32;
      #Deny access to all other IP addresses
      deny all;
    }
  }
}

How to customize the upload file format black and white list​

Add environment variables to the configuration file
ENV_FILEEXT_BLOCKLIST (blacklist, default value: .exe,.vbs,.bat,.cmd,.com,.sh)
ENV_FILEEXT_ALLOWLIST (whitelist) to control uploaded file types
When ENV_FILEEXT_ALLOWLIST is set, ENV_FILEEXT_BLOCKLIST will automatically become invalid, as follows:

If it is a standalone deployment mode:

services:
  app:
    environment:
      ENV_FILEEXT_BLOCKLIST: ".exe,.sh,.html"
      ENV_FILEEXT_ALLOWLIST: ".docx,.txt,.png"

If it is cluster deployment mode, add the corresponding environment variables in file.yaml

How to add hosts resolution to the container​

Add extra_hosts configuration in hdp service, such as:

services:
  hdp:
    extra_hosts:
      - "a.domain.com:192.168.1.10"
      - "b.domain.com:172.17.13.42"