From 9e082a0da24f762c7c134d7c13ff991388be3603 Mon Sep 17 00:00:00 2001 From: GuangJie1 Date: Tue, 16 Jul 2024 19:47:26 +0800 Subject: [PATCH] readme: update the readme file format --- README.en.md | 123 +++++++++++++++++++++++++++------------------------ README.md | 44 +++++++++--------- 2 files changed, 87 insertions(+), 80 deletions(-) diff --git a/README.en.md b/README.en.md index 6dd67b05..026a8bd9 100644 --- a/README.en.md +++ b/README.en.md @@ -1,18 +1,15 @@ # openEuler official container images -#### Introduction +## Introduction Dockerfiles for openEuler official container images, include openEuler basic image and application images. -#### openEuler Basic Container Image +## Basic Container Image -openEuler basic image is published by openEuler community in [openEuler repo](https://repo.openeuler.org) +openEuler basic image is published by openEuler community in [openEuler repo](https://repo.openeuler.org), "openeuler:latest" is the current stable available image. - -"openeuler:latest" is the current stable available image. - -After the official images are published, we will push to every remote container images hub: +After the official images are published, we will push to the third-party Hubs, details are as follows: - name: `openeuler/openeuler` - Download: `docker pull [Remote repo URL]openeuler/openeuler[:tags]` @@ -36,79 +33,87 @@ After the official images are published, we will push to every remote container - [23.09](https://repo.openeuler.org/openEuler-23.09/docker_img/) - [24.03-lts, latest](https://repo.openeuler.org/openEuler-24.03-LTS/docker_img/) - Path rule：`openeuler/[openEuler version]/Dockerfile`, -such as: openEuler 21.09 Dockerfile is under `openeuler/21.09/Dockerfile` path. + such as: openEuler 21.09 Dockerfile is under `openeuler/21.09/Dockerfile` path. -#### openEuler Application Container Image +## Application Container Image Dockerfiles for various popular application implementations based on openEuler basic image. -- Path rule：`[Application name]/[Application version]/[openEuler version]/Dockerfile`, -such as, the nginx 1.20.1 based on openEuler 20.03 LTS SP1 is under `nginx/1.20.1/20.03-lts-sp1/Dockerfile`. -In particular, for application container images of complex software stacks, in order to accurately express their dependencies, the `[application version number]` in the Dockerfile storage path can be described as the complete software stack version, for example: `pytorch/2.1.0-cann7 .0.RC1.alpha002/22.03-lts-sp2/Dockerfile` stores the pytorch 2.1.0 application image Dockerfile based on cann7.0.RC1.alpha002 and openEuler 22.03-lts-sp2. -- The container images would be published after Dockerfile merged under `openeuler`, -such as: `openeuler/nginx:1.20.1-oe2003sp1`. +- Repository rule：`openeuler/[Application name]`, such as: `openeuler/nginx`. +- Path rule：`[Application name]/[Application version]/[openEuler version]/Dockerfile`, such as: the nginx 1.20.1 based on openEuler 20.03 LTS SP1 is under `nginx/1.20.1/20.03-lts-sp1/Dockerfile`. -All openEuler application images contain a README (such as nginx/README.md), included: + In particular, for application container images of complex software stacks, in order to accurately express their dependencies, the `[application version]` in the Dockerfile storage path can be described as the complete software stack version, for example: `pytorch/2.1.0-cann7 .0.RC1.alpha002/22.03-lts-sp2/Dockerfile` stores the pytorch 2.1.0 application image Dockerfile based on cann7.0.RC1.alpha002 and openEuler 22.03-lts-sp2. +- Tag rule: `[Application version]-[openEuler version]`, such as: `openeuler/nginx:1.20.1-oe2003sp1`. -- Description for container images build. -- openEuler, container service (like Docker, iSula) and application version info. +The contents of each application container image directory: -The container images would be published under `openeuler` after Dockerfile merged. We use `docker buildx` to build the container image for amd64 and arm64 platforms. -The build steps are as follows: -- go into directory of `[Application name]/[Application version]/[openEuler version]` -- execute the command `docker buildx build -t tag_name --platform linux/amd64,linux/arm64 .` +1. All openEuler application images contain a README (such as nginx/README.md), included: + - `Quick reference`：related links + - `[Application name] | openEuler`：application descriptions + - `Supported tags and respective Dockerfile links`：tags and Dockerfile links, this must be updated when a new tag is published + - `Usage`：describe how to use the application container image, and try to give a test case that can be easily run + - `Question and answering`：where to file bugs and issues -All openEuler application images contain a `doc/` directory, which stores the graphic and text information of the image: + The README will be synchronously published to the third-party Hubs, so please be serious while contributing. -- `doc/image-info.yml` +2. All openEuler application images contain a `meta.yml` file，which stores the image tag info，the file path is: `[app-name]/meta.yml`. The example is as follows： -The content is as follows: + - `meta.yml` - name - category (such as: bigdata, ai, storage, database, cloud, hpc) - description - environment - download - install - license - similar_packages - Dependency + # spark/meta.yml + 3.3.1-oe2203lts: + path: spark/3.3.1/22.03-lts/Dockerfile + 3.3.2-oe2203lts: + path: spark/3.3.2/22.03-lts/Dockerfile + + In the above example, each pair of `` contains image's publishing configuration, it's as follows: + - key: Tag of the image, `3.3.1-oe2203lts` and `3.3.2-oe2203lts` are different image tags of the openeuler/spark. + - value: It contains configuration items those are used to build image, thos are follows. + + Configuration description: + | Item | Optional | Description | Example | + |--|--|--|--| + | path | yes | Relative path of the image dockerfile | spark/3.3.1/22.03-lts/Dockerfile | + | arch | no | This configuration is required when only one architecture is supported. By default, it supports arm64 and amd64 architectures.| x86_64，only x86_64 or aarch64 can be configured. | + + It is required to add or update the meta.yml while Dockerfile is changed. -- `doc/picture/` +3. All openEuler application images contain a `doc/` directory, which stores the graphic and text information of the image: -Store application-related images + - `doc/image-info.yml` -All openEuler application images contain a `meta.yml` file，which stores the image tag info，the file path is: `[app-name]/meta.yml` + The content is as follows: - - `meta.yml` - - The example is as follows： + name + category (such as: bigdata, ai, storage, database, cloud, hpc, others) + description + environment + tags + download + usage + license + similar_packages + dependency - # spark/meta.yml - 3.3.1-oe2203lts: - path: spark/3.3.1/22.03-lts/Dockerfile - 3.3.2-oe2203lts: - path: spark/3.3.2/22.03-lts/Dockerfile - - Configuration item description: - | Configuration item | Required or not | Description | Example | - |--|--|--|--| - | path | yes | Relative path of the image dockerfile | spark/3.3.1/22.03-lts/Dockerfile | - | arch | no | This configuration is required when only one architecture is supported. By default, it supports arm64 and amd64 architectures.| x86_64，only x86_64 or aarch64 can be configured. | + - `doc/picture/` -#### Available Container Repo + Store application-related images, such as application logos or runtime screenshots of typical scenes. -- [hub.oepkgs.net](https://hub.oepkgs.net/) -- [hub.docker.com](https://hub.docker.com/) +## Available Container Registries -- [quay.io](https://quay.io/) +Available container registries included: +1. [hub.oepkgs.net](https://hub.oepkgs.net/) +2. [hub.docker.com](https://hub.docker.com/) +3. [quay.io](https://quay.io/) +## Contributions -#### Contributions +Welcome to contribute openEuler application container images, please submit PR according to the above rules. As the PR is passed and merged, the automatically publishing process will be triggered, and these images will be published to available container registries mentioned above! -1. After the pull request is merged, the CI process will automatically publish the image. -2. After the `dockerfile` is added or modified, the CI process will automatically publish the image. -3. After the `README.md` is added or modified, the CI process will automatically publish the image README information. -4. Welcome to submit image test cases to the project `eulerPublisher`; The automatic publishing process only checks whether the image can be successfully constructed if the image has no test cases. +Code check instruction: +1. [EulerPublisher](https://gitee.com/openeuler/eulerpublisher) is used to build, check and publish container images. +2. All test cases of application container images are stored in [/tests/container/app](https://gitee.com/openeuler/eulerpublisher/tree/master/tests/container/app). Developers who want to publish container images can also submit test cases to [EulerPublisher](https://gitee.com/openeuler/eulerpublisher). +3. When the PR in which you add or modify a Dockerfile is merged, a new image will be automatically published or the existing image will be updated. +4. When the PR in which you add or modify a README.md is merged, the README.md will be synchronously published to the third-party Hubs. diff --git a/README.md b/README.md index 1e9c4fc0..dc6357f5 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,7 @@ ## 基础镜像 -openEuler的基础镜像由社区官方发布，目前发布在[openEuler镜像站](https://repo.openeuler.org)。 - -其中"openeuler:latest"是最新可用的长期稳定镜像。 +openEuler的基础镜像由社区官方发布，目前发布在[openEuler镜像站](https://repo.openeuler.org), 其中"openeuler:latest"是最新可用的长期稳定镜像。 镜像发布后，会同步推送到各个远端容器镜像仓，信息如下： @@ -74,6 +72,7 @@ openEuler的基础镜像由社区官方发布，目前发布在[openEuler镜像 path: spark/3.3.2/22.03-lts/Dockerfile arch: aarch64 ``` + 上述文件中，每一对``描述一个镜像的构建发布规则，其中： - key：表示镜像的tag，如`3.3.1-oe2203lts`和`3.3.2-oe2203lts`均表示`openeuler/spark`镜像的不同tag - value: 用于描述如何构建镜像，说明如下 @@ -82,22 +81,25 @@ openEuler的基础镜像由社区官方发布，目前发布在[openEuler镜像 | path | 是 | 描述构建镜像的Dockerfile相对路径 | spark/3.3.1/22.03-lts/Dockerfile | | arch | 否 | 用于发布单架构镜像时，指定构建架构可选`x86_64`或`aarch64`；未填写该项时，默认发布`x86_64`和`aarch64`的双架构镜像 | x86_64 | -2. （可选）包含一个`doc/`目录，存放该镜像的图文信息： -- `doc/image-info.yml`，内容如下： - - 名称（name）：应用名 - 分类（category）：应用镜像功能分类，可选：大数据（bigdata）、AI（ai）、分布式存储（storage）、数据库（database）、云服务（cloud）、HPC（hpc）、其他（others） - 功能简介（description） - 运行环境（environment） - 镜像标签（tags） - 获取方式（download） - 使用方式（usage） - LICENSE（license） - 近似软件（similar_packages） - 依赖软件（dependency） -- `doc/picture/` - - 存放与应用特征相关的图片，如应用的logo或典型场景的运行时截图 + 备注： 镜像tag更新时，需要同步更新上述配置。 + +3. （可选）包含一个`doc/`目录，存放该镜像的图文信息： + + - `doc/image-info.yml`，内容如下： + + 名称（name）：应用名 + 分类（category）：应用镜像功能分类，可选：大数据（bigdata）、AI（ai）、分布式存储（storage）、数据库（database）、云服务（cloud）、HPC（hpc）、其他（others） + 功能简介（description） + 运行环境（environment） + 镜像标签（tags） + 获取方式（download） + 使用方式（usage） + LICENSE（license） + 近似软件（similar_packages） + 依赖软件（dependency） + - `doc/picture/` + + 存放与应用特征相关的图片，如应用的logo或典型场景的运行时截图 ## 镜像托管平台 @@ -118,6 +120,6 @@ openEuler的基础镜像由社区官方发布，目前发布在[openEuler镜像 关于PR合入后，自动发布镜像的规则说明： -1. 新增或修改镜像Dockerfile的PR合入后，会触发新增镜像自动发布或已有镜像更新。 +3. 新增或修改镜像Dockerfile的PR合入后，会触发新增镜像自动发布或已有镜像更新。 -2. 新增或修改镜像README.md的PR合入后，会触发所有镜像托管平台的Overview或Description信息刷新。 +4. 新增或修改镜像README.md的PR合入后，会触发所有镜像托管平台的Overview或Description信息刷新。 -- Gitee