Add a docker compose file and update README (#287)
* Add a docker compose file and update README
*Motivation*
- Add a docker compose file to show how to deploy a Pulsar Manager with a Pulsar cluster.
- Update README on how to install Pulsar Manager
* Fix github checkout action
diff --git a/.github/workflows/gradle.yml b/.github/workflows/gradle.yml
index b8d0e2d..0f94866 100644
--- a/.github/workflows/gradle.yml
+++ b/.github/workflows/gradle.yml
@@ -14,7 +14,7 @@
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v1
+ - uses: actions/checkout@v2
- name: Set up JDK 1.8
uses: actions/setup-java@v1
with:
diff --git a/.gitignore b/.gitignore
index df371de..77895da 100644
--- a/.gitignore
+++ b/.gitignore
@@ -48,4 +48,8 @@
dbdata
src/main/resources/local.properties
-*.key
\ No newline at end of file
+*.key
+
+# Docker
+docker/data
+data
\ No newline at end of file
diff --git a/README.md b/README.md
index f9dc381..44931b6 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,193 @@
Apache Pulsar manager is a web-based GUI management tool for managing and monitoring Pulsar.
-## Feature
+A Pulsar Manager is capable of managing multiple Pulsar clusters. A Pulsar instance or a group
+of Pulsar clusters is defined as an `Environment` in Pulsar Manager. You can create as many environments
+as you can. The following diagram illustrates the overall architecture of a Pulsar Manager.
+
+
+
+A running Pulsar Manager instance is comprised of two components: one is the `frontend` which provides
+the GUI to manage and monitor Pulsar clusters, the other one is the `backend` which interacts with Pulsar
+clusters for collecting metrics, forwarding admin requests to the requested Pulsar cluster or brokers.
+
+Since Pulsar Manager directly interacts with Pulsar brokers and bookies for management, it is required
+to deploy the Pulsar Manager into the same network as your Pulsar clusters. So the Pulsar Manager backend
+is able to talk to the brokers and bookies in your Pulsar cluster.
+
+## Install
+
+### Use Docker
+
+1. Start Pulsar standalone.
+
+ ```
+ docker pull apachepulsar/pulsar:latest
+ docker run -d -it \
+ -p 6650:6650 \
+ -p 8080:8080 \
+ -v $PWD/data:/pulsar/data \
+ --name pulsar-standalone \
+ apachepulsar/pulsar:latest \
+ bin/pulsar standalone
+ ```
+
+2. Start Pulsar Manager in a separate container.
+
+> NOTE: the command links the pulsar-manager container with the pulsar standalone container so they are in the same network.
+
+ ```
+ docker pull apachepulsar/pulsar-manager:v0.1.0
+ docker run -it \
+ -p 9527:9527 \
+ -e REDIRECT_HOST=127.0.0.1 \
+ -e REDIRECT_PORT=9527 \
+ -e DRIVER_CLASS_NAME=org.postgresql.Driver \
+ -e URL='jdbc:postgresql://127.0.0.1:5432/pulsar_manager' \
+ -e USERNAME=pulsar \
+ -e PASSWORD=pulsar \
+ -e LOG_LEVEL=DEBUG \
+ -v $PWD:/data \
+ --link pulsar-standalone \
+ apachepulsar/pulsar-manager:v0.1.0
+ ```
+
+ * `REDIRECT_HOST`: the IP address of the front-end server.
+
+ * `REDIRECT_PORT`: the port of the front-end server.
+
+ * `DRIVER_CLASS_NAME`: the driver class name of PostgreSQL.
+
+ * `URL`: the jdbc url of your PostgreSQL database, example: jdbc:postgresql://127.0.0.1:5432/pulsar_manager. The docker image automatically start a local instance of PostgresSQL database.
+
+ * `USERNAME`: the username of PostgreSQL.
+
+ * `PASSWORD`: the password of PostgreSQL.
+
+ * `LOG_LEVEL`: level of log.
+
+
+### Use Docker Compose
+
+Alternatively, you can start a standalone and Pulsar Manager using the docker compose file provided in this repository.
+
+1. Clone this git repoistory.
+
+ ```bash
+ https://github.com/apache/pulsar-manager
+ ```
+
+2. Go to the docker directory.
+
+ ```bash
+ cd docker
+ ```
+
+3. Start the docker composed cluster.
+
+ ```bash
+ docker-compose up
+ ```
+
+### Deploy Pulsar Manager to Kubernetes
+
+The Pulsar Manager can be deployed as part of [Pulsar Helm Chart](https://github.com/streamnative/charts).
+
+1. Install the Pulsar cluster with Pulsar Manager
+
+ ```bash
+ helm repo add streamnative https://charts.streamnative.io
+ helm repo update
+ helm install <release-name> streamnative/pulsar
+ ```
+
+2. Access the Pulsar Manager.
+
+ The default values will create a `ClusterIP` for the Pulsar Manager you can use to interact with cluster.
+ To find the IP address of the Pulsar Manager, use the following command:
+ ```bash
+ kubectl get service -n <k8s-namespace>
+ ```
+ After find the ip address of the Pulsar Manager, you can access the Pulsar Manager at `http://${pulsar-manager-cluster-ip}/#/environments`.
+
+### Build from source code
+
+#### Prerequisites
+
+* Java JDK 1.8
+* Node 10.15.3 or later
+* Npm 6.4.1 or later
+* Pulsar 2.4.0 or later
+
+#### Build instructions
+
+1. Clone the source code.
+
+ ``` bash
+ git clone https://github.com/apache/pulsar-manager
+ ```
+
+2. Build and start the backend.
+
+ ```
+ cd pulsar-manager
+ ./gradlew build -x test
+ cd build/distributions
+ unzip pulsar-manager.zip or tar -zxvf pulsar-manager.tar
+ ./pulsar-manager/bin/pulsar-manager
+ ```
+
+3. Open a new terminal, build and start the front end.
+
+ ```
+ cd pulsar-manager/front-end
+ npm install --save
+ npm run dev
+ ```
+
+After running these steps, the Pulsar Manager is running locally at http://127.0.0.1/#/environments.
+
+## Access Pusar Manager
+
+1. Access Pulsar manager UI at `http://${frontend-end-ip}/#/environments`.
+
+If you started Pulsar Manager using docker or docker-compose, the Pulsar Manager is running at port 9527. You can access the Pulsar Manager UI at http://127.0.0.1/#/environments.
+
+If you are deploying Pulsar Manager 0.1.0 using the released container, you can log in the Pulsar Manager UI using the following credentials.
+
+ * Account: `pulsar`
+ * Password: `pulsar`
+
+If you are deploying Pulsar Manager using the latest code, you can create a super-user using the following command. Then you can use the super user credentials to log in the Pulsar Manager UI.
+
+ ```$xslt
+ curl
+ -H "Content-Type: application/json" \
+ -X PUT http://backend-service:7750/pulsar-manager/users/superuser \
+ -d '{"name": "admin", "password": "apachepulsar", "description": "test", "email": "username@test.org"}'
+ ```
+ `backend-service`: The IP address or domain name of the backend service.
+
+2. Create an environment.
+
+ An environment represents a Pulsar instance or a group of clusters you want to manage. A Pulsar Manager is capable of managing multiple environments.
+
+ - Click "New Environment" button to add an environment.
+ - Input the "Environment Name". The environment name is used for identifying an environment.
+ - Input the "Service URL". The Service URL is the admin service url of your Pulsar cluster.
+ - You need to make sure the service url that Pulsar Manager is able to access. In this example, both pulsar container and pulsar-manager container are linked. So you can use pulsar container name as the domain name of the pulsar standalone cluster. Thus you can type `http://pulsar-standalone:8080`.
+
+## Configure Pulsar Manager
+
+### Back end
+
+For more information about the back end, see [pulsar-manager-backend](https://github.com/apache/pulsar-manager/blob/master/src/README.md).
+
+### Front end
+
+For more information about the front end, see [pulsar-manager-frontend](https://github.com/apache/pulsar-manager/blob/master/front-end/README.md).
+
+## Features
* Tenants Management
* Namespaces Management
@@ -13,8 +199,6 @@
* Dynamic environments with multiple changes
* Support JWT Auth
-## Feature preview
-
### Log in
Use the default account (`pulsar`) and the default password (`pulsar`) to log in.
@@ -63,97 +247,7 @@
-
-## Prerequisites
-* Java JDK 1.8
-* Node 10.15.3 or later
-* Npm 6.4.1 or later
-* Pulsar 2.4.0 or later
-* Docker
-
-## Preparation
-
-1. Start Pulsar standalone.
-
- ```
- docker pull apachepulsar/pulsar:2.4.0
- docker run -d -it -p 6650:6650 -p 8080:8080 -v $PWD/data:/pulsar/data --name pulsar-manager-standalone apachepulsar/pulsar:2.4.0 bin/pulsar standalone
- ```
-
-2. Build an environment.
-
- You can **build an environment with Docker** or **build a local environment**.
-
- * Build an environment with Docker
-
- * `REDIRECT_HOST`: the IP address of the front-end server.
-
- * `REDIRECT_PORT`: the port of the front-end server.
-
- * `DRIVER_CLASS_NAME`: the driver class name of PostgreSQL.
-
- * `URL`: the url of PostgreSQL jdbc, example: jdbc:postgresql://127.0.0.1:5432/pulsar_manager.
-
- * `USERNAME`: the username of PostgreSQL.
-
- * `PASSWORD`: the password of PostgreSQL.
-
- * `LOG_LEVEL`: level of log.
-
- ```
- docker pull apachepulsar/pulsar-manager
- docker run -it -p 9527:9527 -e REDIRECT_HOST=front-end-ip -e REDIRECT_PORT=front-end-port -e DRIVER_CLASS_NAME=org.postgresql.Driver -e URL='jdbc-url' -e USERNAME=root -e PASSWORD=pulsar -e LOG_LEVEL=DEBUG apachepulsar/pulsar-manager /bin/sh
- ```
-
- This is an example:
-
- ```
- docker pull apachepulsar/pulsar-manager:v0.1.0
- docker run -it -p 9527:9527 -e REDIRECT_HOST=http://192.168.0.104 -e REDIRECT_PORT=9527 -e DRIVER_CLASS_NAME=org.postgresql.Driver -e URL='jdbc:postgresql://127.0.0.1:5432/pulsar_manager' -e USERNAME=pulsar -e PASSWORD=pulsar -e LOG_LEVEL=DEBUG -v $PWD:/data apachepulsar/pulsar-manager:v0.1.0 /bin/sh
- ```
-
- * Build a local environment
-
- (1) Download the source code.
-
- ```
- git clone https://github.com/apache/pulsar-manager
- ```
-
- (2) Build and start the backend.
-
- ```
- cd pulsar-manager
- ./gradlew build -x test
- cd build/distributions
- unzip pulsar-manager.zip or tar -zxvf pulsar-manager.tar
- ./pulsar-manager/bin/pulsar-manager
- ```
-
- (3) Build and start the front end.
-
- ```
- cd pulsar-manager/front-end
- npm install --save
- npm run dev
- ```
-
-3. Access Pulsar manager website.
-
-If you are deploying Pulsar Manager 0.1.0 using the released container, you can log in the Pulsar Manager UI using the following credentials.
-
- * Account: `pulsar`
- * Password: `pulsar`
-
-If you are deploying Pulsar Manager using the latest code, you can create a super-user using the following command.
-
- ```$xslt
- curl -H "Content-Type: application/json" -X PUT http://backend-service:7750/pulsar-manager/users/superuser -d '{"name": "admin", "password": "apachepulsar", "description": "test", "email": "username@test.org"}'
- ```
- `backend-service`: The IP address or domain name of the backend service.
-
- * Pulsar manager website: http://localhost:9527/
-
+## Development
### Default Test database HerdDB
@@ -175,12 +269,3 @@
In order to start and setup an HerdDB database follow the instructions on the [HerdDB documentation](https://github.com/diennea/herddb/wiki).
-## Back end
-
-For more information about the back end, see [pulsar-manager-backend](https://github.com/apache/pulsar-manager/blob/master/src/README.md).
-
-
-## Front end
-
-For more information about the front end, see [pulsar-manager-frontend](https://github.com/apache/pulsar-manager/blob/master/front-end/README.md).
-
diff --git a/docker/data/.keep b/docker/data/.keep
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/docker/data/.keep
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
new file mode 100644
index 0000000..4fbbd56
--- /dev/null
+++ b/docker/docker-compose.yml
@@ -0,0 +1,30 @@
+version: "3.7"
+services:
+ pulsar:
+ image: apachepulsar/pulsar:2.5.0
+ command: bin/pulsar standalone
+ hostname: pulsar
+ ports:
+ - "8080:8080"
+ - "6650:6650"
+ restart: unless-stopped
+ volumes:
+ - "./data/:/pulsar/data"
+ dashboard:
+ image: apachepulsar/pulsar-manager:v0.1.0
+ ports:
+ - "9527:9527"
+ depends_on:
+ - pulsar
+ links:
+ - pulsar
+ volumes:
+ - "./data/:/data"
+ environment:
+ REDIRECT_HOST: "http://127.0.0.1"
+ REDIRECT_PORT: "9527"
+ DRIVER_CLASS_NAME: "org.postgresql.Driver"
+ URL: "jdbc:postgresql://127.0.0.1:5432/pulsar_manager"
+ USERNAME: "pulsar"
+ PASSWORD: "pulsar"
+ LOG_LEVEL: "DEBUG"
\ No newline at end of file
diff --git a/docs/img/pulsar-manager-arch.png b/docs/img/pulsar-manager-arch.png
new file mode 100644
index 0000000..e78b96a
--- /dev/null
+++ b/docs/img/pulsar-manager-arch.png
Binary files differ
