Skip to content

Commit

Permalink
docs(#994): Change setup guide to recommend using python to start the…
Browse files Browse the repository at this point in the history 
… server (#1040)

* docs: improve setup guide

* docs: update quick start

* docs: few fixes

* docs: fix quotation

* Update docs/getting_started/advanced_setup_guides.rst

Co-authored-by: Francisco Aranda <frascuchon@gmail.com>

* Update docs/index.rst

Co-authored-by: Francisco Aranda <frascuchon@gmail.com>

* docs: improve es with docker section

* docs: fix code formating in code blocks

* docs: update readme

* docs: small fixes, improvements

* docs: update readme

Co-authored-by: Francisco Aranda <frascuchon@gmail.com>
  • Loading branch information
@frascuchon
David Fidalgo and frascuchon authored Jan 27, 2022
1 parent 8c5f1bc commit c3ffe14
Show file tree
Hide file tree
Showing 4 changed files with 158 additions and 163 deletions.
80 changes: 17 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -88,82 +88,38 @@ Why Rubrix?

## Get started

To get started you need to follow three steps:

1. Install the Python client
2. Launch the web app
3. Start logging data

🆕 **Rubrix Cloud Beta**: Use Rubrix on a scalable cloud infrastructure without installing the server. [Join the waiting list](https://www.rubrix.ml/rubrix-cloud/)

### 1. Install the Python client

You can install the Python client with `pip` or `conda`.

**with pip**
Getting started with Rubrix is as easy as:

```bash
pip install rubrix
```

**with conda**

```sh
conda install -c conda-forge rubrix
pip install rubrix[server]
```

### 2. Launch the web app

There are two ways to launch the web app:

- a) Using [docker-compose](https://docs.docker.com/compose/) (**recommended**).
- b) Executing the server code manually

#### a) Using docker-compose (recommended)
If you don't have [Elasticsearch (ES)](https://www.elastic.co/elasticsearch) running, make sure you have `Docker` installed and run:

Create a folder:
> :information_source: **Check [our documentation](https://rubrix.readthedocs.io/en/stable/getting_started/setup%26installation.html) for further options and configurations regarding Elasticsearch.**
```bash
mkdir rubrix && cd rubrix
```

and launch the docker-contained web app with the following command:

```bash
wget -O docker-compose.yml https://git.io/rb-docker && docker-compose up
```

This is the recommended way because it automatically includes an
[Elasticsearch](https://www.elastic.co/elasticsearch/) instance, Rubrix's main persistence layer.
docker run -d \
--name elasticsearch-for-rubrix \
-p 9200:9200 -p 9300:9300 \
-e "ES_JAVA_OPTS=-Xms512m -Xmx512m" \
-e "discovery.type=single-node" \
docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2

#### b) Executing the server code manually

When executing the server code manually you need to provide an [Elasticsearch](https://www.elastic.co/elasticsearch/) instance yourself.

1. First you need to install
[Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.10/install-elasticsearch.html)
(we recommend version 7.10) and launch an Elasticsearch instance.
For MacOS and Windows there are
[Homebrew formulae](https://www.elastic.co/guide/en/elasticsearch/reference/7.13/brew.html) and a
[msi package](https://www.elastic.co/guide/en/elasticsearch/reference/current/windows.html), respectively.
2. Install the Python client together with its server dependencies:

```bash
pip install rubrix[server]
```

3. Launch a local instance of the web app
Then simply run:

```bash
python -m rubrix.server
python -m rubrix
```

By default, the Rubrix server will look for your Elasticsearch endpoint at `http://localhost:9200`.
But you can customize this by setting the `ELASTICSEARCH` environment variable.
Afterward, you should be able to access the web app at http://localhost:6900/.
**The default username and password are** `rubrix` **and** `1234`.

### 3. Start logging data
> 🆕 **Rubrix Cloud Beta**: Use Rubrix on a scalable cloud infrastructure without installing the server. [Join the waiting list](https://www.rubrix.ml/rubrix-cloud/)
The following code will log one record into a data set called `example-dataset`:
The following code will log one record into a dataset called `example-dataset`:

```python
import rubrix as rb
Expand All @@ -175,10 +131,8 @@ rb.log(
```

If you go to your Rubrix web app at http://localhost:6900/, you should see your first dataset.
**The default username and password are `rubrix` and `1234`**.
You can also check the REST API docs at http://localhost:6900/api/docs.

Congratulations! You are ready to start working with Rubrix. You can continue reading a working example below.
**Congratulations! You are ready to start working with Rubrix.** You can continue reading for a working example below.

To better understand what's possible take a look at Rubrix's [Cookbook](https://rubrix.rtfd.io/en/stable/guides/cookbook.html)

Expand Down
109 changes: 101 additions & 8 deletions docs/getting_started/advanced_setup_guides.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,82 @@
Advanced setup guides
=====================

Here we provide some advanced setup guides, in case you want to use docker, configure your own Elasticsearch instance or install the cutting-edge master version.
Here we provide some advanced setup guides:

.. _using-docker:
.. contents::
:local:
:depth: 1

Using docker
------------
.. _setting-up-elasticsearch-via-docker:

You can use vanilla docker to run our image of the server.
Setting up Elasticsearch via docker
-----------------------------------

Setting up Elasticsearch (ES) via docker is straight forward.
Simply run following command:

.. code-block:: bash
docker run -d \
--name elasticsearch-for-rubrix \
-p 9200:9200 -p 9300:9300 \
-e "ES_JAVA_OPTS=-Xms512m -Xmx512m" \
-e "discovery.type=single-node" \
docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2
This will create an ES docker container named *"elasticsearch-for-rubrix"* that will run in the background.
To see the logs of the container, you can run:

.. code-block:: bash
docker logs elasticsearch-for-rubrix
Or you can stop/start the container via:

.. code-block:: bash
docker stop elasticsearch-for-rubrix
docker start elasticsearch-for-rubrix
.. warning::
Keep in mind, if you remove your container with ``docker rm elasticsearch-for-rubrix``, you will loose all your datasets in Rubrix!

For more details about the ES installation with docker, see their `official documentation <https://www.elastic.co/guide/en/elasticsearch/reference/7.10/docker.html>`__.
For MacOS and Windows, Elasticsearch also provides `homebrew formulae <https://www.elastic.co/guide/en/elasticsearch/reference/7.10/brew.html>`__ and a `msi package <https://www.elastic.co/guide/en/elasticsearch/reference/7.10/windows.html>`__, respectively.
We recommend ES version 7.10 to work with Rubrix.


.. _server-configurations:

Server configurations
---------------------

By default, the :ref:`Rubrix server <...>` will look for your ES endpoint at ``http://localhost:9200``.
But you can customize this by setting the ``ELASTICSEARCH`` environment variable.

Since the Rubrix server is built on fastapi, you can launch it using **uvicorn** directly:

.. code-block:: bash
uvicorn rubrix:app
*(for Rubrix versions below 0.9 you can launch the server via)*

.. code-block:: bash
uvicorn rubrix.server.server:app
For more details about fastapi and uvicorn, see `here <https://fastapi.tiangolo.com/deployment/manually/#run-a-server-manually-uvicorn>`_

Fastapi also provides beautiful REST API docs that you can check at `http://localhost:6900/api/docs <http://localhost:6900/api/docs>`__.


.. _launching-the-web-app-via-docker:

Launching the web app via docker
--------------------------------

You can use vanilla docker to run our image of the web app.
First, pull the image from the `Docker Hub <https://hub.docker.com/>`_:

.. code-block:: shell
Expand Down Expand Up @@ -43,9 +111,35 @@ To stop the Rubrix server, just stop the container:
If you want to deploy your own Elasticsearch cluster via docker, we refer you to the excellent guide on the `Elasticsearch homepage <https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html>`_

.. _launching-the-web-app-via-docker-compose:

Launching the web app via docker-compose
----------------------------------------

For this method you first need to install `Docker Compose <https://docs.docker.com/compose/install/>`__.

Then, create a folder:

.. code-block:: bash
mkdir rubrix && cd rubrix
and launch the docker-contained web app with the following command:

.. code-block:: bash
wget -O docker-compose.yml https://raw.githubusercontent.com/recognai/rubrix/master/docker-compose.yaml && docker-compose up -d
This is a convenient way because it automatically includes an
`Elasticsearch <https://www.elastic.co/elasticsearch/>`__ instance, Rubrix's main persistent layer.

.. warning::
Keep in mind, if you execute ``docker-compose down``, you will loose all your datasets in Rubrix!


.. _configure-elasticsearch-role-users:

Configure elasticsearch role/users
Configure Elasticsearch role/users
----------------------------------

If you have an Elasticsearch instance and want to share resources with other applications, you can easily configure it for Rubrix.
Expand Down Expand Up @@ -81,6 +175,7 @@ Note that provided analyzers names should be defined as built-in ones. If you wa
customized analyzer, you should create it inside an index_template matching Rubrix index names (`.rubrix*.records-v0),
and then provide the analyzer name using the specific environment variable.

.. _deploy-to-aws-instance-using-docker-machine:

Deploy to aws instance using docker-machine
-------------------------------------------
Expand Down Expand Up @@ -178,8 +273,6 @@ Accessing Rubrix
In our case http://52.213.178.33




.. _install-from-master:

Install from master
Expand Down
Loading

0 comments on commit c3ffe14

Please sign in to comment.