Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(docs): update docs docker image #1482

Merged
merged 2 commits into from
Nov 7, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 12 additions & 8 deletions deploy/docker/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,25 +37,29 @@ The `lfedge/ekuiper` images come in many flavors, each designed for a specific u

## `lfedge/ekuiper:<tag>`

This is the development Docker image, which is based on Debian and it also includes a Golang build environment. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code, compile plugins for eKuiper, and start the container to run your app), as well as the base to build other images. Please be aware of that this image is the biggest size, and it's usually used for development purpose.
This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is an alias of tag `lfedge/ekuiper:<tag>-alpine`(see below) since 1.7.1. Previously, it is equivalent to the `lfedge/ekuiper:<tag>-dev` image

Notice: This image is the equivalent to development image of `x.x.x-dev` in 0.3.x versions.
ngjaying marked this conversation as resolved.
Show resolved Hide resolved
## `lfedge/ekuiper:<tag>-alpine`

This image is based on the popular [Alpine Linux project](http://alpinelinux.org), available in [the `alpine` official image](https://hub.docker.com/_/alpine). Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general.

This variant is highly recommended when final image size being as small as possible is desired. The main caveat to note is that it does use [musl libc](http://www.musl-libc.org) instead of [glibc and friends](http://www.etalabs.net/compare_libcs.html), so certain software might run into issues depending on the depth of their libc requirements. However, most software doesn't have an issue with this, so this variant is usually a very safe choice. See [this Hacker News comment thread](https://news.ycombinator.com/item?id=10782897) for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images.

To minimize image size, it's uncommon for additional related tools (such as `git` or `bash`) to be included in Alpine-based images. Using this image as a base, add the things you need in your own Dockerfile (see the [`alpine` image description](https://hub.docker.com/_/alpine/) for examples of how to install packages if you are unfamiliar).

## `lfedge/ekuiper:<tag>-slim`

This image is also based on Debian, and only contains the minimal packages needed to run eKuiper. The difference between this and previous image (`lfedge/ekuiper:<tag>`) is that this image does not include Golang development environment. The typical usage of this image would be deploy the plugins compiled in previous Docker image instances. This is the official recommended image if you want to deploy & run customized plugins into eKuiper.
This image is based on Debian, and only contains the minimal packages needed to run eKuiper. The difference between this and dev image (`lfedge/ekuiper:<tag>-dev`) is that this image does not include Golang development environment. The typical usage of this image would be deploy the plugins compiled in previous Docker image instances. This is the official recommended image if you want to deploy & run customized plugins into eKuiper.

## `lfedge/ekuiper:<tag>-slim-python`

This image is the same as slim except that it also contains python environment. It is recommended if using eKuiper python portable plugins.

## `lfedge/ekuiper:<tag>-alpine`
ngjaying marked this conversation as resolved.
Show resolved Hide resolved

This image is based on the popular [Alpine Linux project](http://alpinelinux.org), available in [the `alpine` official image](https://hub.docker.com/_/alpine). Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general.
## `lfedge/ekuiper:<tag>-dev`

This variant is highly recommended when final image size being as small as possible is desired. The main caveat to note is that it does use [musl libc](http://www.musl-libc.org) instead of [glibc and friends](http://www.etalabs.net/compare_libcs.html), so certain software might run into issues depending on the depth of their libc requirements. However, most software doesn't have an issue with this, so this variant is usually a very safe choice. See [this Hacker News comment thread](https://news.ycombinator.com/item?id=10782897) for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images.
This is the development Docker image, which is based on Debian and it also includes a Golang build environment. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code, compile plugins for eKuiper, and start the container to run your app), as well as the base to build other images. Please be aware of that this image is the biggest size, and it's usually used for development purpose.

To minimize image size, it's uncommon for additional related tools (such as `git` or `bash`) to be included in Alpine-based images. Using this image as a base, add the things you need in your own Dockerfile (see the [`alpine` image description](https://hub.docker.com/_/alpine/) for examples of how to install packages if you are unfamiliar).
Notice: This image is the equivalent to development image of `x.x.x-dev` in 0.3.x versions.

# What is eKuiper

Expand Down
2 changes: 1 addition & 1 deletion docs/en_US/extension/native/develop/plugins_tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,7 @@ However, if developers create plugin project outside eKuiper, he needs following

#### Docker compile

eKuiper provides different docker images for different purpose. The development docker image should be used for compiling plugins. From 0.4.0, the eKuiper image with tag x.x.x (e.g. `lfedge/ekuiper:0.4.0`) is the development docker image. Compared with the running version, the development version provides the development environment of Go, which lets users compile the plugin that can be completely compatible with the officially published version of eKuiper. The compiling steps in docker are as follows:
eKuiper provides different docker images for different purpose. The development docker image should be used for compiling plugins. Since 1.7.1, the development docker image tag format is `x.x.x-dev`(From 0.4.0 to 1.7.0, the tag format is x.x.x) . Compared with the running version, the development version provides the development environment of Go, which lets users compile the plugin that can be completely compatible with the officially published version of eKuiper. The compiling steps in docker are as follows:
1. Run docker of the development version of eKuiper. Users need to mount the local plugin directory to the directory in docker, and then they can access and compile the plugin project in docker. The author's plugin project is located in the local `/var/git` directory. We map the local directory `/var/git` to the `/home` directory in docker by using the following commands.
```go
docker run -d --name kuiper-dev --mount type=bind,source=/var/git,target=/home lfedge/ekuiper:1.3.0
Expand Down
12 changes: 6 additions & 6 deletions docs/en_US/operation/manager-ui/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,16 @@ From eKuiper version 0.9.1, whenever a new version of eKuiper is released, the c

### Install eKuiper

- Pull eKuiper's Docker image from [Docker Image Library](https://hub.docker.com/r/lfedge/ekuiper/tags). Since it is required to install the plugin in this article, you must use the `ekuiper:1.5-slim` image (`ekuiper:1.5-alpine` image is relatively small and easy to install, but due to the lack of some necessary library files, the plug-in cannot run normally. The `ekuiper:1.5` image is the development version, which is suitable for use in the development phase).
- Pull eKuiper's Docker image from [Docker Image Library](https://hub.docker.com/r/lfedge/ekuiper/tags). Since it is required to install the plugin in this article, you must use the `ekuiper:1.7-slim` image (`ekuiper:1.7-alpine` image is relatively small and easy to install, but due to the lack of some necessary library files, the plug-in cannot run normally. The `ekuiper:1.7-dev` image is the development version, which is suitable for use in the development phase).

```shell
docker pull lfedge/ekuiper:1.5-slim
docker pull lfedge/ekuiper:1.7-slim
```

- Run the eKuiper container (for convenience, we will use the public MQTT server provided by [EMQ](https://www.emqx.io), and the address can be set by the `-e` option when running the container). If you want to access the eKuiper instance through the host, you can expose port 9081 by adding the `-p 9081:9081` parameter when starting the container.

```shell
# docker run -d --name kuiper -e MQTT_SOURCE__DEFAULT__SERVER="tcp://broker.emqx.io:1883" lfedge/ekuiper:1.5-slim
# docker run -d --name kuiper -e MQTT_SOURCE__DEFAULT__SERVER="tcp://broker.emqx.io:1883" lfedge/ekuiper:1.7-slim
```

When the container is running, the MQTT server address can be set through the `-e` option, and the data is written to the MQTT source configuration file, which can be viewed by the following command:
Expand All @@ -56,16 +56,16 @@ From eKuiper version 0.9.1, whenever a new version of eKuiper is released, the c

### Install management console

- Pull the Docker image of kuiper-manager from [Docker Image Library](https://hub.docker.com/r/emqx/ekuiper-manager/tags), and `1.5-ief` is a dedicated image for Huawei IEF users, This example uses the `1.5` image.
- Pull the Docker image of kuiper-manager from [Docker Image Library](https://hub.docker.com/r/emqx/ekuiper-manager/tags), and `1.7-ief` is a dedicated image for Huawei IEF users, This example uses the `1.7` image.

```shell
docker pull emqx/ekuiper-manager:1.5
docker pull emqx/ekuiper-manager:1.7
```

- Run the Kuiper-manager container and expose port 9082.

```shell
docker run --name kuiperManager -d -p 9082:9082 emqx/ekuiper-manager:1.5
docker run --name kuiperManager -d -p 9082:9082 emqx/ekuiper-manager:1.7
```

## Getting started
Expand Down
6 changes: 3 additions & 3 deletions docs/en_US/operation/manager-ui/plugins_in_manager.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ In `etc/kuiper.yaml`, there is a `pluginHosts` configuration item, and users can
https://$host/$folder/$version/$os/$type/$plugin.zip
```

Example: https://127.0.0.1:9090/kuiper-plugins/1.3.1/debian/sinks/file.zip
Example: https://127.0.0.1:9090/kuiper-plugins/1.7.1/debian/sinks/file.zip

Among them:

Expand All @@ -129,8 +129,8 @@ Among them:

Due to the limitation of `Go` language plugin mechanism, the compilation environment of the plugin must be the same as the `eKuiper` environment. Therefore, it is recommended that the plugin be compiled in a `Docker` container of the same version as `eKuiper`. At the same time, because some libraries in the `alpine` environment are missing, it is not recommended to run plugins on it. Therefore, if you need to install and run the plugin, it is recommended to use the following container:

- eKuiper: Use slim image, such as `1.3.1-slim`
- Plugin: compile with the default image of the corresponding version, such as `1.3.1`
- eKuiper: Use slim image, such as `1.7.1-slim`
- Plugin: compile with the default image of the corresponding version, such as `1.7.1-dev`

### Summary

Expand Down
2 changes: 1 addition & 1 deletion docs/zh_CN/extension/native/develop/plugins_tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,7 @@ require (

#### Docker编译

eKuiper 提供了开发版本 docker 镜像。其中, 0.4.0及之后版本的开发镜像为x.x.x,例如`lfedge/ekuiper:0.4.0`;与运行版本相比,开发版提供了 go 开发环境,使得用户可以在编译出在 eKuiper 正式发布版本中完全兼容的插件。Docker 中编译步骤如下:
eKuiper 提供了开发版本 docker 镜像。从 1.7.1 开始,开发镜像为 x.x.x-dev (0.4.0 到 1.7.0 之间版本的开发镜像为x.x.x,例如`lfedge/ekuiper:0.4.0`。);与运行版本相比,开发版提供了 go 开发环境,使得用户可以在编译出在 eKuiper 正式发布版本中完全兼容的插件。Docker 中编译步骤如下:
1. 运行 eKuiper 开发版本 docker。需要把本地插件目录 mount 到 docker 里的目录中,这样才能在 docker 中访问插件项目并编译。笔者的插件项目位于本地 `/var/git` 目录。下面的命令中,我们把本地的 `/var/git`目录映射到 docker 内的 `/home` 目录中。
```go
docker run -d --name kuiper-dev --mount type=bind,source=/var/git,target=/home lfedge/ekuiper:1.3.0
Expand Down
12 changes: 6 additions & 6 deletions docs/zh_CN/operation/manager-ui/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,16 @@

### 安装 eKuiper

- 从 [Docker 镜像库](https://hub.docker.com/r/lfedge/ekuiper/tags)拉取 eKuiper 的 Docker 镜像。由于本文中要安装插件,必须使用`ekuiper:1.5-slim`镜像(`ekuiper:1.5-alpine` 镜像比较小,安装比较方便,但是由于缺少一些必要的库文件,插件无法正常运行;而 `ekuiper:1.5` 镜像是开发版本的镜像,适合于开发阶段使用)。
- 从 [Docker 镜像库](https://hub.docker.com/r/lfedge/ekuiper/tags)拉取 eKuiper 的 Docker 镜像。由于本文中要安装插件,必须使用`ekuiper:1.7-slim`镜像(`ekuiper:1.7-alpine` 镜像比较小,安装比较方便,但是由于缺少一些必要的库文件,插件无法正常运行;而 `ekuiper:1.7-dev` 镜像是开发版本的镜像,适合于开发阶段使用)。

```shell
docker pull lfedge/ekuiper:1.5-slim
docker pull lfedge/ekuiper:1.7-slim
```

- 运行 eKuiper 容器(为了方便,我们将使用由 [EMQ](https://www.emqx.cn) 提供的公有 MQTT 服务器,在运行容器时可通过 `-e` 选项设置地址)。如果您想通过主机访问 eKuiper 实例,可以通过在启动容器的时候加入 `-p 9081:9081` 参数来暴露 9081 端口。

```shell
# docker run -d --name kuiper -e MQTT_SOURCE__DEFAULT__SERVER="tcp://broker.emqx.io:1883" lfedge/ekuiper:1.5-slim
# docker run -d --name kuiper -e MQTT_SOURCE__DEFAULT__SERVER="tcp://broker.emqx.io:1883" lfedge/ekuiper:1.7-slim
```

在运行容器时通过 `-e` 选项设置了 MQTT 服务器地址,数据写到了 MQTT 源配置文件中,通过以下命令可以查看:
Expand All @@ -56,16 +56,16 @@

### 安装管理控制台

- 从 [Docker 镜像库](https://hub.docker.com/r/emqx/ekuiper-manager/tags) 拉取 kuiper-manager 的 Docker 镜像 ,`1.5-ief` 为华为 IEF 用户专用镜像,本例使用`1.5` 镜像。
- 从 [Docker 镜像库](https://hub.docker.com/r/emqx/ekuiper-manager/tags) 拉取 kuiper-manager 的 Docker 镜像 ,`1.7-ief` 为华为 IEF 用户专用镜像,本例使用`1.7` 镜像。

```shell
docker pull emqx/ekuiper-manager:1.5
docker pull emqx/ekuiper-manager:1.7
```

- 运行 Kuiper-manager 容器并暴露 9082 端口。

```shell
docker run --name kuiperManager -d -p 9082:9082 emqx/ekuiper-manager:1.5
docker run --name kuiperManager -d -p 9082:9082 emqx/ekuiper-manager:1.7
```

## 开始使用
Expand Down
6 changes: 3 additions & 3 deletions docs/zh_CN/operation/manager-ui/plugins_in_manager.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ Function 元数据详细配置请参考 [sink 元数据配置](../../extension/n
https://$host/$folder/$version/$os/$type/$plugin.zip
```

例如: https://127.0.0.1:9090/kuiper-plugins/1.3.1/debian/sinks/file.zip
例如: https://127.0.0.1:9090/kuiper-plugins/1.7.1/debian/sinks/file.zip

其中:

Expand All @@ -129,8 +129,8 @@ https://$host/$folder/$version/$os/$type/$plugin.zip

由于`Go`语言插件机制的限制,插件的编译环境必须与`eKuiper`环境相同。因此,建议插件在`eKuiper`相同版本的`Docker` 容器中进行编译。同时,由于`alpine` 环境部分库缺失,不建议在上面运行插件。因此,若需要插件安装运行,建议使用如下容器:

- eKuiper: 使用 slim 镜像,例如 `1.3.1-slim`
- 插件:使用对应版本默认镜像进行编译,例如 `1.3.1`
- eKuiper: 使用 slim 镜像,例如 `1.7.1-slim`
- 插件:使用对应版本默认镜像进行编译,例如 `1.7.1-dev`

## 总结

Expand Down