Merge pull request #156 from chickenlj/update-readme
Add project introduction
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..36def7c
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,27 @@
+## Contributing to Dubbo
+Dubbo is released under the non-restrictive Apache 2.0 licenses and follows a very standard Github development process, using Github tracker for issues and merging pull requests into master. Contributions of all form to this repository is acceptable, as long as it follows the prescribed community guidelines enumerated below.
+
+### Sign the Contributor License Agreement
+Before we accept a non-trivial patch or pull request (PRs), we will need you to sign the Contributor License Agreement. Signing the contributors' agreement does not grant anyone commits rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. Active contributors may get invited to join the core team that will grant them privileges to merge existing PRs.
+
+### Contact
+
+#### Mailing list
+
+The mailing list is the recommended way of pursuing a discussion on almost anything related to Dubbo. Please refer to this [guide](https://github.com/apache/dubbo/wiki/Mailing-list-subscription-guide) for detailed documentation on how to subscribe.
+
+- [dev@dubbo.apache.org](mailto:dev-subscribe@dubbo.apache.org): the developer mailing list where you can ask questions about an issue you may have encountered while working with Dubbo.
+- [commits@dubbo.apache.org](mailto:commits-subscribe@dubbo.apache.org): the commit updates will get broadcasted on this mailing list. You can subscribe to it, should you be interested in following Dubbo's development.
+- [notifications@dubbo.apache.org](mailto:notifications-subscribe@dubbo.apache.org): all the Github [issue](https://github.com/apache/dubbo/issues) updates and [pull request](https://github.com/apache/dubbo/pulls) updates will be sent to this mailing list.
+
+### Reporting issue
+
+Please crete an issue here https://github.com/apache/dubbo-kubernetes
+
+
+### Contribution flow
+
+A rough outline of an ideal contributors' workflow is as follows:
+
+
+Thanks for contributing!
\ No newline at end of file
diff --git a/DEVELOPER.md b/DEVELOPER.md
new file mode 100644
index 0000000..1af28cf
--- /dev/null
+++ b/DEVELOPER.md
@@ -0,0 +1,5 @@
+# Developer documentation
+
+The source code guidance of this project.
+
+With this documentation, developers can learn which part of the project they need to change in order to fix a bug or introduce a new feature. How can they verify their codes work as expected before submit a pull request, by running the project locally or running the test suite.
\ No newline at end of file
diff --git a/README.md b/README.md
index 986b011..c969d1f 100644
--- a/README.md
+++ b/README.md
@@ -10,76 +10,124 @@
[](https://codecov.io/gh/apache/dubbo-kubernetes)
-This repository contains libraries and tools for creating and deploying Dubbo applications in any Kubernetes environment, i.e. on Kubernetes, Aliyun ACK, etc.
+**The universal Control Plane and Console for managing microservices on any environment - VM and Kubernetes.**
-## Prerequisites:
-* Ensure you have Go installed, version 1.20 or higher.
-* Make sure you install kubectl.
-* Ensure you have Dubboctl installed.
+
-## Quick Start
-### Create a Dubbo application
-Use `dubboctl create` to create a project template.
-
-```shell
-dubboctl create -l java
-```
-
-This should generate a simple project with a demo service properly configured and is ready to run.
-
-> For java developers, it's recommended to use [start.dubbo.apache.org]() or [IntelliJ IDEA plugin]() to generate more complicated templates.
-
-### Deploy application to Kubernetes
-Before deploying the application, let's install Nacos, Zookeeper, Prometheus and other components necessary for running a Dubbo application or microservice cluster.
-
-```shell
-dubboctl install --profile=demo # This will install Nacos, Prometheus, Grafana, Admin, etc.
-```
-
-Next, build your application as docker image and deploy it into kubernetes cluster with `dubboctl deploy`, it will do the following two steps:
-
-1. Build your application from source code into docker image and push the image to remote repository.
-2. Generate all the kubernetes configurations (e.g., deployments, services, load balancers) needed to run your application on vanilla Kubernetes.
-
-```shell
-dubboctl deploy --out=deployment.yml
-```
-
-Finally, apply manifests into kubernetes cluster.
-
-```shell
-kubectl apply -f deployment.yml
-```
-
-### Monitor and manage your application
-We already have the application up and running, now it's time to continuously monitor the status or manage the traffics of our applications.
-
-#### Admin
-Run the following command and open `http://localhost:38080/admin/` with your favourite browser.
-
-```shell
-dubboctl dashboard admin
-```
-
-![Admin Console]()
+## Quick Start (under development)
+> NOTICE: As the project has not been officially released yet, the following commands may not run properly. The best way for now is to refer to the [Developer's Guide](./DEVELOPER.md) to learn how to download the source code and build it locally!
-![Admin Grafana]()
+1. Download `dubbo-control-plane` binary package.
+ ```shell
+ curl -L https://raw.githubusercontent.com/apache/dubbo-kubernetes/master/release/downloadDubbo.sh | sh -
+
+ cd dubbo-$version
+ export PATH=$PWD/bin:$PATH
+ ```
-#### Tracing
-```shell
-dubboctl dashboard zipkin
-```
+2. Install `control-plane` on Kubernetes
+ ```shell
+ dubboctl install --profile=demo
+ ```
-#### Traffic Management
-Please refer to our official website to learn the traffic policies in Dubbo with some well-designed tasks.
-* Timeout
-* Accesslog
-* Region-aware traffic split
-* Weight-based traffic split
-* Circuit breaking
-* Canary release
+3. Check installation
+ ```shell
+ kubectl get services -n dubbo-system
+ ```
+
+4. Next, deploy Dubbo applications to Kubernetes as shown below:
+
+ ```yaml
+ apiVersion: v1
+ kind: Service
+ metadata:
+ name: demo-service
+ namespace: dubbo-demo
+ spec:
+ selector:
+ app: dubbo-demo
+ type: ClusterIP
+ ports:
+ - name: port1
+ protocol: TCP
+ appProtocol: http
+ port: 80
+ targetPort: 8080
+ ---
+ apiVersion: apps/v1
+ kind: Deployment
+ metadata:
+ name: example-app
+ namespace: dubbo-demo
+ spec:
+ ...
+ template:
+ metadata:
+ ...
+ labels:
+ dubbo.apache.org/sidecar-injection: enabled
+ spec:
+ containers:
+ ...
+ ```
+
+ > If you want to create your own Dubbo application from scratch and deploy it, please use `[dubboctl]()`we provided below.
+5. Open the following page to check deployment status on control plane UI:
+ ```shell
+ kubectl port-forward svc/dubbo-control-plane \
+ -n dubbo-system 5681:5681
+ ```
+
+ visit, 127.0.0.1:5681/admin
+ 
+## Architecture
+
+
+
+The microservcice architecture built with Dubbo Control Plane consists of two main components:
+
+- The **`Dubbo Control Plane`** configures the data plane - applications developed with Dubbo SDK, for handling service traffic. Users create [policies]() that the dubbo control plane processes to generate configurations for the data plane.
+- The data plane - the **`Dubbo SDK`**, connets directly to control plane and receives configurations that can work as the sources for service discovery, traffic routing, load balancing, etc.
+
+Dubbo Control Plane supports two depoyment modes: **`kubernetes`** and **`universal`**.
+
+- **`kubernetes`** is like the classic Service Mesh architecture, with all microservices concepts bond to kubernetes resources. Comparing to classic service mesh solutions like istio, Dubbo favors a proxyless mode - with no envoy sidecar.
+- **`universal`** is the traditional microservice architecture that all Dubbo users are already familar with. Unlike service mesh, it usually needs a dedicatd registry like Nacos or Zookeeper for service discovery, etc.
+
+### Kubernetes
+In kubernetes mode, the control plane will interact directly with the Kubernetes API-SERVER, watching the kubernetes resources and tranform them as xDS resources for service discovery and traffic management configurations.
+
+
+
+We all know the `service`definition of Kubernetes and Dubo are different, `Kubernetes Service` is more like an application concent run on a selected group of pods while `Dubbo Service` can mean a specific RPC service inside the application process. So how does dubbo control plane manages to bridge the `interface-application` gap, check here for more details.
+
+### Universal
+In Universal mode, Dubbo still uses Nacos or Zookeeper as registries for service discovery, control plane then interact with registry directly to work as the console UI, as the entry point for viewing and managing the cluster.
+
+
+
+### Multiple cluster
+Dubbo Control Plane supports running your services in multiple zones. It is even possible to run with a mix of Kubernetes and Universal zones. Your microservice environment can include multiple isolated services, and workloads running in different regions, on different clouds, or in different datacenters. A zone can be a Kubernetes cluster, a VPC, or any other deployment you need to include in the same distributed mesh environment. The only condition is that all the data planes running within the zone must be able to connect to the other data planes in this same zone.
+
+Dubbo Control Plane supports a **`global`** deployment mode that can connect different **`zone`** region clusters. The picture below shows how it works.
+
+
+
+## Roadmap
+
+- Security
+- Metrics
+- Cross-cluster communication
+- Console
+
+## Refereces
+
+- Dubboctl
+- Console UI Design
+- Dubbo java xDS implementation
+- Dubbo go xDS implementation
diff --git a/docs/dubboctl.md b/docs/dubboctl.md
new file mode 100644
index 0000000..67da43e
--- /dev/null
+++ b/docs/dubboctl.md
@@ -0,0 +1,41 @@
+
+This repository contains libraries and tools for creating and deploying Dubbo applications in any Kubernetes environment, i.e. on Kubernetes, Aliyun ACK, etc.
+
+## Prerequisites:
+* Ensure you have Go installed, version 1.20 or higher.
+* Make sure you install kubectl.
+* Ensure you have Dubboctl installed.
+
+## Quick Start
+### Create a Dubbo application
+Use `dubboctl create` to create a project template.
+
+```shell
+dubboctl create -l java
+```
+
+This should generate a simple project with a demo service properly configured and is ready to run.
+
+> For java developers, it's recommended to use [start.dubbo.apache.org]() or [IntelliJ IDEA plugin]() to generate more complicated templates.
+
+### Deploy application to Kubernetes
+Before deploying the application, let's install Nacos, Zookeeper, Prometheus and other components necessary for running a Dubbo application or microservice cluster.
+
+```shell
+dubboctl install --profile=demo # This will install Nacos, Prometheus, Grafana, Admin, etc.
+```
+
+Next, build your application as docker image and deploy it into kubernetes cluster with `dubboctl deploy`, it will do the following two steps:
+
+1. Build your application from source code into docker image and push the image to remote repository.
+2. Generate all the kubernetes configurations (e.g., deployments, services, load balancers) needed to run your application on vanilla Kubernetes.
+
+```shell
+dubboctl deploy --out=deployment.yml
+```
+
+Finally, apply manifests into kubernetes cluster.
+
+```shell
+kubectl apply -f deployment.yml
+```
diff --git a/docs/images/homepage/arch1.png b/docs/images/homepage/arch1.png
new file mode 100644
index 0000000..a544f10
--- /dev/null
+++ b/docs/images/homepage/arch1.png
Binary files differ
diff --git a/docs/images/homepage/arch2.png b/docs/images/homepage/arch2.png
new file mode 100644
index 0000000..d005966
--- /dev/null
+++ b/docs/images/homepage/arch2.png
Binary files differ
diff --git a/docs/images/homepage/kubernetes-mode.png b/docs/images/homepage/kubernetes-mode.png
new file mode 100644
index 0000000..e34c573
--- /dev/null
+++ b/docs/images/homepage/kubernetes-mode.png
Binary files differ
diff --git a/docs/images/homepage/multiple-cluster.png b/docs/images/homepage/multiple-cluster.png
new file mode 100644
index 0000000..f0c0c6a
--- /dev/null
+++ b/docs/images/homepage/multiple-cluster.png
Binary files differ
diff --git a/docs/images/homepage/ui-demo.png b/docs/images/homepage/ui-demo.png
new file mode 100644
index 0000000..0e810a8
--- /dev/null
+++ b/docs/images/homepage/ui-demo.png
Binary files differ
diff --git a/docs/images/homepage/universal-mode.png b/docs/images/homepage/universal-mode.png
new file mode 100644
index 0000000..652efc5
--- /dev/null
+++ b/docs/images/homepage/universal-mode.png
Binary files differ
