|
| 1 | +--- |
| 2 | +title: 'Download and Install' |
| 3 | +meta_title: 'Download and Install ReactiveSearch' |
| 4 | +meta_description: 'Run ReactiveSearch in Open Source mode with Docker with an Elasticsearch or OpenSearch cluster' |
| 5 | +keywords: |
| 6 | + - clusters |
| 7 | + - appbaseio |
| 8 | + - appbase |
| 9 | + - Elasticsearch |
| 10 | + - Opensearch |
| 11 | + - docker |
| 12 | + - open source |
| 13 | +sidebar: 'docs' |
| 14 | +--- |
| 15 | + |
| 16 | +ReactiveSearch is available in Open Source mode as a Docker-based deployment. Run it alongside any Elasticsearch-compatible cluster you manage — whether that's AWS OpenSearch, Elastic Cloud, or a self-hosted Elasticsearch/OpenSearch instance. |
| 17 | + |
| 18 | + |
| 19 | + |
| 20 | +This diagram highlights how ReactiveSearch works. It acts as an API gateway between your client applications and an underlying Elasticsearch or OpenSearch cluster. ReactiveSearch supercharges your search cluster with pipelines, search relevancy controls, AI search, actionable analytics, fine-grained access control, and a no-code UI builder. |
| 21 | + |
| 22 | +## Quickstart |
| 23 | + |
| 24 | +### Using Docker |
| 25 | + |
| 26 | +The quickest way to get started is to run ReactiveSearch alongside Elasticsearch using Docker Compose. This requires [Docker](https://docs.docker.com/install/) to be installed on your system. |
| 27 | + |
| 28 | +- **Step 1:** Clone the repository and start the services |
| 29 | + |
| 30 | + ```bash |
| 31 | + git clone https://github.com/appbaseio/reactivesearch-api-docker.git && cd reactivesearch-api-docker |
| 32 | + docker-compose -f docker-compose-with-elasticsearch.yaml up -d |
| 33 | + ``` |
| 34 | + |
| 35 | + This starts Elasticsearch, ReactiveSearch API, Nginx (with TLS), Zinc (for internal logging), and Fluent Bit — all with a single command. 😎 |
| 36 | + |
| 37 | +- **Step 2:** Verify the service is running |
| 38 | + |
| 39 | + Once the containers are up, verify that ReactiveSearch is accessible: |
| 40 | + |
| 41 | + ```bash |
| 42 | + curl http://localhost:8000 -u rs-admin-user:rs-password |
| 43 | + ``` |
| 44 | + |
| 45 | + You should see a response like: |
| 46 | + |
| 47 | + ```json |
| 48 | + { |
| 49 | + "name": "elasticsearch", |
| 50 | + "cluster_name": "docker-cluster", |
| 51 | + "version": { |
| 52 | + "number": "9.3.0", |
| 53 | + "build_flavor": "default", |
| 54 | + "build_type": "docker", |
| 55 | + "build_hash": "17b451d8979a29e31935fe1eb901310350b30e62", |
| 56 | + "build_date": "2026-01-29T10:05:46.708397977Z", |
| 57 | + "build_snapshot": false, |
| 58 | + "lucene_version": "10.3.2", |
| 59 | + "minimum_wire_compatibility_version": "8.19.0", |
| 60 | + "minimum_index_compatibility_version": "8.0.0" |
| 61 | + }, |
| 62 | + "tagline": "You Know, for Search" |
| 63 | + } |
| 64 | + ``` |
| 65 | + |
| 66 | + This confirms that ReactiveSearch is running and connected to the Elasticsearch cluster. |
| 67 | + |
| 68 | +- **Step 3:** Connect the ReactiveSearch Dashboard |
| 69 | + |
| 70 | + Open [dash.reactivesearch.io](https://dash.reactivesearch.io) in your browser. Enter your ReactiveSearch URL (`http://localhost:8000`), username (`rs-admin-user`) and password (`rs-password`). |
| 71 | + |
| 72 | +  |
| 73 | + |
| 74 | +- **Step 4:** Start building your search experience |
| 75 | + |
| 76 | + After signing in, you'll land on the Cluster Overview page — your central hub for managing indices, configuring search relevancy, setting up analytics, and more. |
| 77 | +
|
| 78 | +  |
| 79 | +
|
| 80 | +### Services overview |
| 81 | +
|
| 82 | +The dockerized setup is composed of the following services: |
| 83 | +
|
| 84 | +#### ReactiveSearch API |
| 85 | +
|
| 86 | +Allows you to access all ReactiveSearch features like search preview, actionable analytics and granular security with any Elasticsearch cluster hosted anywhere. |
| 87 | +
|
| 88 | +> **Note:** Make sure your ReactiveSearch container has complete access to Elasticsearch. You can use Elasticsearch URL with Basic Auth in configuring the dashboard or an IP-restricted Elasticsearch URL where the IP of your ReactiveSearch cluster is whitelisted. |
| 89 | +
|
| 90 | +#### Nginx |
| 91 | +
|
| 92 | +This service sets up a reverse proxy for the ReactiveSearch API. It also supports serving data with a TLS certificate, which is recommended for production. |
| 93 | +
|
| 94 | +For production deployments, replace the self-signed certificates in [nginx/certs](https://github.com/appbaseio/reactivesearch-api-docker/tree/master/nginx/certs) with your own TLS certificate and key (e.g. from [Let's Encrypt](https://letsencrypt.org/)). Update the file names in both the `docker-compose.yaml` and [nginx/default.conf](https://github.com/appbaseio/reactivesearch-api-docker/blob/master/nginx/default.conf) if needed. |
| 95 | + |
| 96 | +#### Elasticsearch |
| 97 | + |
| 98 | +An open-source single-node Elasticsearch cluster. This is optional — you can use the [docker compose file here](https://github.com/appbaseio/reactivesearch-api-docker/blob/master/docker-compose.yaml) to run ReactiveSearch without a bundled Elasticsearch and connect to your own cluster instead. |
| 99 | + |
| 100 | +#### Zinc |
| 101 | + |
| 102 | +A lightweight search engine used internally by ReactiveSearch for logging. |
| 103 | + |
| 104 | +#### Fluent Bit |
| 105 | + |
| 106 | +A log processor that forwards pipeline execution logs. |
| 107 | + |
| 108 | +## Deploy with OpenSearch |
| 109 | + |
| 110 | +To run ReactiveSearch alongside [OpenSearch](https://opensearch.org) instead of Elasticsearch, use the dedicated OpenSearch docker compose file: |
| 111 | + |
| 112 | +```bash |
| 113 | +git clone https://github.com/appbaseio/reactivesearch-api-docker.git && cd reactivesearch-api-docker |
| 114 | +docker-compose -f docker-compose-with-opensearch.yaml up -d |
| 115 | +``` |
| 116 | + |
| 117 | +This sets up: |
| 118 | + |
| 119 | +- **OpenSearch** (single-node, port `9200`) — an Apache 2.0 licensed search engine compatible with the Elasticsearch API |
| 120 | +- **ReactiveSearch API** — connected to OpenSearch via `ES_CLUSTER_URL=http://opensearch:9200` |
| 121 | +- **Nginx** — reverse proxy with TLS support |
| 122 | +- **Zinc** — lightweight search engine for internal logging |
| 123 | +- **Fluent Bit** — log forwarding for pipeline logs |
| 124 | + |
| 125 | +The default credentials configured in the compose file are: |
| 126 | +- ReactiveSearch username: `rs-admin-user` |
| 127 | +- ReactiveSearch password: `rs-password` |
| 128 | + |
| 129 | +You can change these by editing the environment variables in the compose file or via the configuration UI at http://localhost after startup. |
| 130 | + |
| 131 | +### Connecting to AWS OpenSearch |
| 132 | + |
| 133 | +To connect ReactiveSearch to an existing AWS OpenSearch cluster (instead of running a local one), modify the `ES_CLUSTER_URL` environment variable for the `reactivesearch-api` service in your docker compose file to point to your AWS OpenSearch endpoint: |
| 134 | + |
| 135 | +```yaml |
| 136 | +reactivesearch-api: |
| 137 | + environment: |
| 138 | + - ES_CLUSTER_URL=https://your-aws-opensearch-endpoint.region.es.amazonaws.com |
| 139 | +``` |
| 140 | + |
| 141 | +> **Note:** Ensure your AWS OpenSearch domain's access policy allows connections from the machine running the ReactiveSearch Docker container. You can use IP whitelisting or fine-grained access control with a master user to secure the connection. |
| 142 | +
|
| 143 | +## Deploy with Elastic Cloud |
| 144 | +
|
| 145 | +To connect ReactiveSearch to your [Elastic Cloud](https://cloud.elastic.co) cluster, modify the `ES_CLUSTER_URL` environment variable to use your Elastic Cloud endpoint with credentials: |
| 146 | +
|
| 147 | +```bash |
| 148 | +git clone https://github.com/appbaseio/reactivesearch-api-docker.git && cd reactivesearch-api-docker |
| 149 | +docker-compose up -d |
| 150 | +``` |
| 151 | +
|
| 152 | +Edit the `docker-compose.yaml` (or use the configuration UI after startup) and set: |
| 153 | +
|
| 154 | +```yaml |
| 155 | +reactivesearch-api: |
| 156 | + environment: |
| 157 | + - ES_CLUSTER_URL=https://username:password@your-elastic-cloud-endpoint.es.cloud.es.io:9243 |
| 158 | +``` |
| 159 | +
|
| 160 | +### Setting up Elastic Cloud credentials |
| 161 | +
|
| 162 | +1. Log in to [Elastic Cloud](https://cloud.elastic.co/home) and open your deployment |
| 163 | +2. Navigate to Kibana → Management → Security → Users |
| 164 | +3. Create a new user (e.g. `reactivesearch-connect`) with a **superuser** role |
| 165 | +4. Construct the URL as `https://<username>:<password>@<elasticsearch-endpoint>` |
| 166 | +5. Use this URL as the `ES_CLUSTER_URL` value |
| 167 | +
|
| 168 | +> **Why is a `superuser` role needed?** ReactiveSearch creates and manages system indices within your Elastic Cloud cluster for recording analytics, storing query rules, search relevance preferences, logs and more. Other roles don't allow access to these indices. |
| 169 | + |
| 170 | +> ReactiveSearch connects to your Elastic Cloud cluster from a private environment and these credentials aren't exposed anywhere. |
0 commit comments