diff --git a/docs/quick-start.md b/docs/quick-start.md index 473946b0a..28ecf7b8c 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -1,40 +1,38 @@ --- layout: page -title: Quick Start --- -## Setup TwitterMap locally +## Setup TwitterMap Using Cloudberry and AsterixDB -This page includes instructions on how to setup a small instance of the +This page includes instructions on how to use Cloudberry and AsterixDB to setup a small instance of the [TwitterMap](http://cloudberry.ics.uci.edu/demos/twittermap/) on a local machine. -The relation between TwitterMap and Cloudberry is shown in the following figure: -![architecture][architecture] +The following diagram illustrates its architecture: ![architecture][architecture] System requirements: - Linux or Mac - At least 4GB memory -**Step 1**: Install `sbt` by following the instructions on this [`page`](http://www.scala-sbt.org/release/docs/Setup.html). +**Step 1**: Follow the instructions on this [`page`](http://www.scala-sbt.org/release/docs/Setup.html) to install `sbt`. -**Step 2**: Clone the codebase. +**Step 2**: Clone the Cloudberry codebase from github. ``` -shell> git clone https://github.com/ISG-ICS/cloudberry.git +~> git clone https://github.com/ISG-ICS/cloudberry.git ``` Suppose the repostory is cloned to the folder `~/cloudberry`. -**Step 3**: Use the following steps to install an AsterixDB cluster on the local machine in order to run the Cloudberry middleware. +**Step 3**: Use the following steps to start a Docker container that has a pre-built AsterixDB cluster. 1. Install [Docker](https://www.docker.com/products/docker) (version at least 1.10) on the local machine; - 2. Run the following commands to create an AsterixDB cluster locally: + 2. Run the following commands: ``` ~> cd cloudberry ~/cloudberry> ./script/dockerRunAsterixDB.sh ``` -This command will download and run a prebuilt AsterixDB docker image from [here](https://hub.docker.com/r/jianfeng/asterixdb/). This step may take 5-10 minutes or even longer, depending on your network speed. +The second command will download and run a prebuilt AsterixDB docker container from [here](https://hub.docker.com/r/jianfeng/asterixdb/). This step may take 5-10 minutes or even longer, depending on your network speed. After it finishes, you should see the messages as shown in the following screenshot: ![docker][docker] @@ -45,8 +43,7 @@ After it finishes, you should see the messages as shown in the following screens ~/cloudberry> ./script/ingestAllTwitterToLocalCluster.sh ``` -This step is downloading about 70MB of data, and it may take 5 minutes, again, depending on your network speed. This step is successful after you see a message "Data ingestion completed!" in the shell. -After it finishes, you should see the messages as shown in the following screenshot: +This step is downloading about 70MB of data, and it may take 5 minutes, again, depending on your network speed. You should see the messages as shown in the following screenshot: ![ingestion][ingestion] **Step 5**: Compile and run the Cloudberry server. @@ -56,42 +53,44 @@ After it finishes, you should see the messages as shown in the following screens ~/cloudberry> sbt "project neo" "run" ``` -Wait until the shell prints the messages as shown in the following screenshot: +Wait until the shell prints the messages shown in the following screenshot: ![neo][neo] -**Step 6**: Start the TwitterMap frontend by running the following command in another shell: +**Step 6**: Start the TwitterMap Web server (in port 9001) by running the following command in another shell: ``` ~/cloudberry> sbt "project twittermap" "run 9001" ``` -Wait until the shell prints the messages as shown in the following screenshot: +Wait until the shell prints the messages shown in the following screenshot: ![twittermap][twittermap] -**Step 7**: Open a browser to access [http://localhost:9001](http://localhost:9001) to see the TwitterMap frontend. Notice that the first time you open the page, it could take up to several minutes (depending on your machine) to show the following webpage: +**Step 7**: Open a browser to access [http://localhost:9001](http://localhost:9001) to see the TwitterMap frontend. The first time you open the page, it could take up to several minutes (depending on your machine's speed) to show the following Web page: ![web][web] -**Congratulations!** You have successfully set up TwitterMap using AsterixDB and Cloudberry! +**Congratulations!** You have successfully set up TwitterMap using Cloudberry and AsterixDB! + + +## Setup your own AsterixDB cluster +The instructions above assume that we use an AsterixDB instance in a Docker container. If you want to setup your AsterixDB cluster, please use the following steps. -### Connect to your own AsterixDB cluster -To connect with an existing AsterixDB cluster, you can modify the AsterixDB hostname in the -configuration file `neo/conf/application.conf` and change the `asterixdb.url` value to the AsterixDB hostname. +**Step 8**: Follow the instructions on the [AsterixDB Installation Guide](https://ci.apache.org/projects/asterixdb/index.html) to install an AsterixDB cluster. Select your preferred installation option. + +**Step 9**: Ingest twitter data. + +**Step 10**: Change the Cloudberry middleware configuration to connect to this new AsterixDB cluster. You can modify the AsterixDB hostname in the configuration file `neo/conf/application.conf` and change the `asterixdb.url` value to the AsterixDB hostname. ``` asterixdb.url = "http://YourAsterixDBHostName:19002/query/service" ``` -### Run your own front-end server - -TwitterMap is our homemade front-end that shows how to use Cloudberry server. You can implement own front-end service -and let it talk to Cloudberry to achieve the same interactive user experience. +## Build your own application -### Customize front-end requests -Read more on [documentation](/documentation) about how to write Cloudberry requests for your own front-end applications. +For more information about Cloudberry, please read its [documentation](/documentation). [architecture]: /img/quick-start-architecture.png {: width="800px"}