update

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing Guidelines
+# Contributing Guidelines in General
 
 [English](./CONTRIBUTING.md) | [中文](./CONTRIBUTING.zh.md)
 

CONTRIBUTING.zh.md

@@ -1,4 +1,4 @@
-# 贡献指南
+# 贡献指南（通用）
 
 [English](./CONTRIBUTING.md) | [中文](./CONTRIBUTING.zh.md)
 

SUPPORT.md

@@ -2,7 +2,6 @@
 
 [English](./SUPPORT.md) | [中文](./SUPPORT.zh.md)
 
----
 
 - If you'd like to contribute to this project, please read the [CONTRIBUTING.md](./CONTRIBUTING.md).
 - If you're looking for programming help, and for answers to questions, please consult the [issue list][] and the [discussion][].

SUPPORT.zh.md

@@ -2,7 +2,6 @@
 
 [English](./SUPPORT.md) | [中文](./SUPPORT.zh.md)
 
----
 
 - 如果你想为这个项目做出贡献，请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)。
 - 如果你在寻找编程帮助，以及问题的答案，请查阅 [issue list][] 和 [discussion][] 。

doc/cheatsheet/docker.md

@@ -0,0 +1,10 @@
+---
+parent: Cheatsheet
+---
+# Docker Cheatsheet
+
+## Docker commands
+
+![Docker Commands.png](https://raw.githubusercontent.com/rossbachp/docker-basics/master/images/docker-command-flow.png)
+
+- [The Ultimate Docker Cheat Sheet](https://collabnix.github.io/dockerlabs/docker/cheatsheet/)

doc/code-style/bash.md

@@ -14,7 +14,7 @@ And the following rules have higher priority.
 
 ## File naming
 
-- All filenames must match the regex `[-_a-z0-9]`, except `Dockerfile` and other particular files.
+- All filenames must match the regex `[-_a-z0-9]`, except other particular files (like `Dockerfile`).
 - All script filenames must end with `.bash`.
 
 ## File Header

doc/code-style/docker-image.md

@@ -0,0 +1,44 @@
+---
+parent: Code Styles
+---
+# Docker Image Style
+
+## Use only well maintained images FROM a trusted registry
+
+We trust "Docker" and "ourselves". As a consequence, you can pull images from `hub.docker.com`, `docker.io` or `quay.io`.
+
+## Image names and versions
+
+1. Image names should not contain version info "in themselves".
+
+    Example: There is no `mysql4:1.0` or `ubuntu14:0.4` but only `mysql:4.x.x` and `ubuntu:14.0.4`
+
+2. you **MUST** use `latest` only with the most recent **STABLE** version (not necessarily the latest being build).
+
+    Example: `php:latest`
+
+3. container:major - this is for a specific version/featureset.
+
+    Example: `php:4`, `php:5`
+
+4. container:major.minor - this is for a specific (compatible) version with a compatible featureset
+
+    Example: `mysql:5.6`, `mysql:5.7`
+
+5. container:major.minor.patch - this is/must be EXACTLY THE current container. If anybody needs THIS container he has to use this tag.
+
+    Example: `mysql:5.6.28`, `mysql:5.7.10`
+
+## Adding information to version
+
+Examples:
+
+- `php:5.6.17-cli` It is IDENTICAL to php:5.6.17 and so the default
+- `php:5.6.17-apache` It is an php container installation that provides the apache webserver WITH php
+- `php:5.6.17-fpm` It is an php container that can be used with nginx (FPM=FastCGI Process Manager)
+
+## Building Multi-Architecture Images
+
+You **SHOULD** build images for `amd64` and `arm64` architectures at least.
+
+Follows this [article](https://www.docker.com/blog/how-to-rapidly-build-multi-architecture-images-with-buildx/).

doc/code-style/dockerfile.md

@@ -0,0 +1,191 @@
+---
+parent: Code Styles
+---
+# Dockerfile Code Style
+<!-- editorconfig-checker-disable-file -->
+
+## Editor Settings
+
+- Your editor must be able to recognize the [`.editorconfig`](http://editorconfig.org/) file in project.
+
+## Follow the Best practices for writing Dockerfiles
+
+https://docs.docker.com/develop/develop-images/dockerfile_best-practices/
+
+## NO "upgrade" in NON-OS-Base-Images
+
+While you **MAY** "update" the file-lists of the package manager of the OS in the **Base Image** you have chosen, you **MUST NOT** alter the contents of a **Base Image** by "upgrading" it in a Dockerfile build.
+
+This is OK
+
+	FROM ubuntu: 14.04.1
+	RUN apt-get update \
+		&& apt-get install -y ...
+	# ...
+
+This is BAD
+
+	FROM ubuntu: 14.04.1
+	RUN apt-get update \
+		&& apt-get upgrade -y
+		&& apt-get install -y ...
+	# ...
+
+The `apt-get upgrade` (or the command that does the trick in "your" **Base Image**) might change installed software versions or even install or remove packages based on new dependencies. The resulting Docker Image does NOT match the **Base Image** anymore.
+
+If you NEED such statements because the `docker build` fails, **ASK** for a new **upgraded Base Image**
+
+
+## Not leave unnecessary files and tools in layer
+
+- **MUST NOT** leave configuration management tools (puppet, ansible, chef, ...) **INSIDE** a image layer.
+
+## Use only well maintained images FROM a trusted registry
+
+We trust "Docker" and "ourselves". As a consequence, you can pull images from `hub.docker.com`, `docker.io` or `quay.io`.
+
+## NO secrets in Dockerfile (or its repository)
+
+A VERY bad example of a Dockerfile would be
+
+	FROM ubuntu:14.04.1
+	MAINTAINER ...
+	ENV API_KEY=4711101 \
+		USR=admin \
+		PWD=the_admin_password \
+		CREDITCARD=5555 3333 2222
+	ADD the_same_secrets.txt /etc
+	# ...
+
+You **MUST** keep secrets out of the services Dockerfile **AND** its repository.
+
+Dockerfile repositories with all their accompanying files tend to be cloned,
+shared, etc. IF you forget about the secrets inside, anybody who gains access
+to the repository would immediately KNOW your precious secrets.
+
+You can solve this dilemma by
+- provide secrets as **environment variables** when you start the container with `docker run -e API_KEY=4711 ...`
+- create strictly **separate repositories for secret/configuration containers**
+	that are NEVER at risk being published outside
+- create configuration only **containers "on the fly"** during provisioning
+- let the **containers entrypoint or command retrieve secrets** at startup.
+
+
+## VERIFY downloaded artifacts
+
+When using the Dockerfile with the `docker build` command, files from the local filesystem (the build context) can be used or being retrieved from services in the intra- or internet.
+
+You **MUST** verify externally downloaded files.
+
+### VERIFY downloaded artifacts (I)
+
+You **SHOULD** use one of:
+
+- a signature for the external file itself
+- a signed file with the HASH for the external file and the signing key from a public keyserver. 
+
+> Using a keyserver with HTTP support (port 80) might help with problematic firewalls.
+
+     # ...
+    ENV HASHICORP_KEYIDS=51852D87348FFC4C
+     # ...
+	RUN curl -sL https://releases.hashicorp.com/vault/0.5.0/vault_0.5.0_linux_amd64.zip >  vault_0.5.0_linux_amd64.zip \
+        && curl -sL https://releases.hashicorp.com/vault/0.5.0/vault_0.5.0_SHA256SUMS > app.sha \
+        && curl -sL https://releases.hashicorp.com/vault/0.5.0/vault_0.5.0_SHA256SUMS.sig > app.sig \
+        && gpg --keyserver http://pool.sks-keyservers.net:80 --recv-keys ${HASHICORP_KEYIDS} \
+        && gpg --verify app.sig app.sha \
+        && grep linux_amd64 app.sha | sha256sum -sc \
+        && echo "We only get here if sha256sum succeeded ..."
+
+### VERIFY downloaded artifacts (II)
+
+If there is no better option, you **SHOULD** use a well known HASH from a trusted source (e.g. placed directly in the Dockerfile)
+
+     # ...
+	ENV VAULT_SHA256=f81accce15313881b8d53b039daf090398b2204b1154f821a863438ca2e5d570
+     # ...
+    RUN curl -sL https://releases.hashicorp.com/vault/0.5.0/vault_0.5.0_linux_amd64.zip > /tmp/my_file \
+        && echo "${VAULT_SHA256}  /tmp/my_file" | sha256sum -sc  \
+        && echo "We only get here if sha256sum succeeded ..."
+
+## No "root" processes in containers (please)
+
+A process inside a container **SHOULD NOT** run as root (with uid “0”) to reduce possible runtime risks - especially in respect to (root-owned ?) volumes from the host. Even a Docker Engine > 1.10 (with new security features enabled) is a misconfiguration risk to be avoided.
+
+If possible, set the effective runtime-user in the dockerfile.
+
+    host$ cat dockerfile
+    FROM ubuntu
+
+    # Installing as almighty "root"
+    RUN ...
+    COPY ...
+
+    # now switching to harmless "guest" runtime user
+    USER guest
+
+    ENTRYPOINT ["/my_entrypoint.sh"]
+    CMD ["/my_command.sh"]
+
+> Some programs - like Apache or Nginx - have to be **STARTED** as root,
+but provide configuration settings to switch to a different, much less
+risky runtime user.
+
+## Only EXPOSE necessary ports
+
+In a Dockerfile, you **MUST** only `EXPOSE` ports that are required
+from outside of the container. If a program provides its API via
+port 80 AND 443, but you don't really need port 80, this should be
+reflected in the Dockerfile:
+
+```dockerfile
+# Disabled
+# EXPOSE 80
+
+EXPOSE 443
+```
+
+## Write Log/Error to Stdout/Stderr
+
+The container **MUST** use this functionality **IF POSSIBLE** to support a standardized log management approach.
+
+Stdout **SHOULD** contain regular information about the process doings, while stderr **SHOULD** be restricted to messages about technical errors or warnings that an operator or admin has to take care of.
+
+Such messages **SHOULD** be machine readable (e.g. json formatted) to avoid extensive parsing steps in later processing.
+
+Of course, the application **MAY** uses other (additional) means of log forwarding but is immediately on its own for maintenance, configuration etc.
+
+## Use Exec form rather than Shell
+
+You **MUST** write [CMD](https://docs.docker.com/engine/reference/builder/#cmd) and [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) statements using the Exec-form.
+Using the shell form would effectively trigger a call to `/bin/sh -c` with the command and parameters you specified. 
+
+As a result, when you use `docker stop` or `docker kill` the POSIX signal will only be sent to the container process running as PID 1, and if that process is /bin/sh rather than the underlying process you started and /bin/sh doesn't forward signals to any child processes you won't be able to [gracefully stop the process](https://www.ctl.io/developers/blog/post/gracefully-stopping-docker-containers/).
+
+## Use tini as PID 1
+
+[tini](https://github.com/krallin/tini)
+
+## One Process/Service per Container
+
+A Dockerfile **MUST** only install packages for ONE **logical** service.
+
+A logical service **SHOULD** be only a **SINGLE** process like one
+web- or database server.
+
+	FROM ubuntu:14.04.1
+	CMD [ "/opt/myservice/myprogram" ]
+
+The technical reason is the STREAMS (Stdin/Stdout/Stderr) and SIGNAL handling between the Docker Engine and
+the process(es) running in a Docker Container. When not constructed/handled
+carefully, something similar to "unix process zombies" might raise their
+ugly heads ...
+
+This asks for installing and starting applications the "right way"
+
+> There are solutions for cleanly handling multiple processes inside a
+> container like [Using Supervisor with Docker](https://docs.docker.com/engine/admin/using_supervisord/),
+
+## Inspired & Thanks
+
+This documents are modified from [Haufe-Lexware/docker-style-guide](https://github.com/Haufe-Lexware/docker-style-guide/blob/master/Dockerfile.md) which under Apache-2.0 license. Thanks for their great .

doc/dco.md

@@ -2,7 +2,6 @@
 
 [English](./dco.md) | [中文](./dco.zh.md)
 
----
 
 The project uses a mechanism known as a Developer Certificate of Origin (DCO) to manage process.
 

doc/dco.zh.md

@@ -2,7 +2,6 @@
 
 [English](./dco.md) | [中文](./dco.zh.md)
 
----
 
 该项目使用一种被称为开发者原创声明 (DCO) 的机制来管理流程。
 

doc/git-style.md

@@ -5,7 +5,6 @@ parent: Code Styles
 
 [English](./git-style.md) | [中文](./git-style.zh.md)
 
----
 
 Generally follows the [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/).
 

doc/git-style.zh.md

@@ -5,7 +5,6 @@ parent: Code Styles
 
 [English](./git-style.md) | [中文](./git-style.zh.md)
 
----
 
 通常情况下，遵循风格 [Conventional Commits v1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)。