Adding Documentation for Search
Safwan Rahman
parent
463f9e23d2
commit
879b59cc4f
|
|
@ -1,108 +0,0 @@
|
||||||
==========================================
|
|
||||||
Enabling Elasticsearch on the local server
|
|
||||||
==========================================
|
|
||||||
|
|
||||||
Read the Docs has been using Elasticsearch for indexing and searching. To enable this on your local installation, you need to install elasticsearch and run the Elastic server locally.
|
|
||||||
|
|
||||||
Installation has been mainly divided into following steps.
|
|
||||||
|
|
||||||
Installing Java
|
|
||||||
---------------
|
|
||||||
|
|
||||||
Elasticsearch requires Java 8 or later. Use `Oracle official documentation <http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_.
|
|
||||||
or opensource distribution like `OpenJDK <http://openjdk.java.net/install/>`_.
|
|
||||||
|
|
||||||
After installing java, verify the installation by,::
|
|
||||||
|
|
||||||
$ java -version
|
|
||||||
|
|
||||||
The result should be something like this::
|
|
||||||
|
|
||||||
openjdk version "1.8.0_151"
|
|
||||||
OpenJDK Runtime Environment (build 1.8.0_151-8u151-b12-0ubuntu0.16.04.2-b12)
|
|
||||||
OpenJDK 64-Bit Server VM (build 25.151-b12, mixed mode)
|
|
||||||
|
|
||||||
|
|
||||||
Downloading and installing Elasticsearch
|
|
||||||
----------------------------------------
|
|
||||||
|
|
||||||
Elasticsearch can be downloaded directly from elastic.co. For Ubuntu, it's best to use the deb (Debian) package which will install everything you need to run Elasticsearch.
|
|
||||||
|
|
||||||
RTD currently uses elasticsearch 1.x which can be easily downloaded and installed from `elastic.co
|
|
||||||
<https://www.elastic.co/downloads/past-releases/elasticsearch-1-3-8/>`_.
|
|
||||||
|
|
||||||
Install the downloaded package by following command::
|
|
||||||
|
|
||||||
$ sudo apt install .{path-to-downloaded-file}/elasticsearch-1.3.8.deb
|
|
||||||
|
|
||||||
Custom setup
|
|
||||||
------------
|
|
||||||
|
|
||||||
You need the icu plugin::
|
|
||||||
|
|
||||||
$ elasticsearch/bin/plugin -install elasticsearch/elasticsearch-analysis-icu/2.3.0
|
|
||||||
|
|
||||||
Running Elasticsearch from command line
|
|
||||||
---------------------------------------
|
|
||||||
|
|
||||||
Elasticsearch is not started automatically after installation. How to start and stop Elasticsearch depends on whether your system uses SysV init or systemd (used by newer distributions). You can tell which is being used by running this command::
|
|
||||||
|
|
||||||
$ ps -p 1
|
|
||||||
|
|
||||||
**Running Elasticsearch with SysV init**
|
|
||||||
|
|
||||||
Use the ``update-rc.d command`` to configure Elasticsearch to start automatically when the system boots up::
|
|
||||||
|
|
||||||
$ sudo update-rc.d elasticsearch defaults 95 10
|
|
||||||
|
|
||||||
Elasticsearch can be started and stopped using the service command::
|
|
||||||
|
|
||||||
$ sudo -i service elasticsearch start
|
|
||||||
$ sudo -i service elasticsearch stop
|
|
||||||
|
|
||||||
If Elasticsearch fails to start for any reason, it will print the reason for failure to STDOUT. Log files can be found in /var/log/elasticsearch/.
|
|
||||||
|
|
||||||
**Running Elasticsearch with systemd**
|
|
||||||
|
|
||||||
To configure Elasticsearch to start automatically when the system boots up, run the following commands::
|
|
||||||
|
|
||||||
$ sudo /bin/systemctl daemon-reload
|
|
||||||
$ sudo /bin/systemctl enable elasticsearch.service
|
|
||||||
|
|
||||||
Elasticsearch can be started and stopped as follows::
|
|
||||||
|
|
||||||
$ sudo systemctl start elasticsearch.service
|
|
||||||
$ sudo systemctl stop elasticsearch.service
|
|
||||||
|
|
||||||
To verify run::
|
|
||||||
|
|
||||||
$ curl http://localhost:9200
|
|
||||||
|
|
||||||
|
|
||||||
You should get something like::
|
|
||||||
|
|
||||||
{
|
|
||||||
status: 200,
|
|
||||||
name: "Amina Synge",
|
|
||||||
version: {
|
|
||||||
number: "1.3.8",
|
|
||||||
build_hash: "475733ee0837fba18c00c3ee76cd49a08755550c",
|
|
||||||
build_timestamp: "2015-02-11T14:45:42Z",
|
|
||||||
build_snapshot: false,
|
|
||||||
lucene_version: "4.9"
|
|
||||||
},
|
|
||||||
tagline: "You Know, for Search"
|
|
||||||
}
|
|
||||||
|
|
||||||
Index the data available at RTD database
|
|
||||||
----------------------------------------
|
|
||||||
|
|
||||||
You need to create the indexes::
|
|
||||||
|
|
||||||
$ python manage.py provision_elasticsearch
|
|
||||||
|
|
||||||
In order to search through the RTD database, you need to index it into the elasticsearch index::
|
|
||||||
|
|
||||||
$ python manage.py reindex_elasticsearch
|
|
||||||
|
|
||||||
You are ready to go!
|
|
||||||
|
|
@ -0,0 +1,30 @@
|
||||||
|
Search
|
||||||
|
============
|
||||||
|
|
||||||
|
Read The Docs uses Elasticsearch_ instead of built in Sphinx search for providing better search result. Documentations are indexed in Elasticsearch index and the search is made through API. All the Search Code is Opensource and lives in `Github Repository`_. Currently we are using `Elasticsearch 6.3`_ version.
|
||||||
|
|
||||||
|
Local Development Configuration
|
||||||
|
----------------
|
||||||
|
|
||||||
|
Installing and running Elasticsearch
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
You must need to install and run `Elasticsearch 6.3`_ version in your local development machine. You can get installation instuction `here <https://www.elastic.co/guide/en/elasticsearch/reference/6.3/install-elasticsearch.html>`_.
|
||||||
|
Otherwise, you can also start a Elasticsearch Docker container by running following command::
|
||||||
|
|
||||||
|
docker run -p 9200:9200 -p 9300:9300 \
|
||||||
|
-e "discovery.type=single-node" \
|
||||||
|
docker.elastic.co/elasticsearch/elasticsearch:6.3.2
|
||||||
|
|
||||||
|
Indexing
|
||||||
|
^^^^^^^^
|
||||||
|
For using search, you need to index data to Elasticsearch Index. Run `reindex_elasticsearch` management command::
|
||||||
|
|
||||||
|
./manage.py reindex_elasticsearch
|
||||||
|
|
||||||
|
Auto Indexing
|
||||||
|
^^^^^^^^^^^^^
|
||||||
|
By default, Auto Indexing is turned off in development mode. To turn in on, change the `ELASTICSEARCH_DSL_AUTOSYNC` settings to `True` in `readthedocs/settings/dev.py` file. After that, whenever a documentation successfully build, or project gets added, the search index will update automatically.
|
||||||
|
|
||||||
|
.. _Elasticsearch: https://www.elastic.co/products/elasticsearch
|
||||||
|
.. _Elasticsearch 6.3: https://www.elastic.co/guide/en/elasticsearch/reference/6.3/index.html
|
||||||
|
.. _Github Repository: https://github.com/rtfd/readthedocs.org/tree/master/readthedocs/search
|
||||||
|
|
@ -95,6 +95,7 @@ Information about development is also available:
|
||||||
|
|
||||||
changelog
|
changelog
|
||||||
install
|
install
|
||||||
|
development/search
|
||||||
architecture
|
architecture
|
||||||
tests
|
tests
|
||||||
docs
|
docs
|
||||||
|
|
|
||||||
|
|
@ -57,7 +57,7 @@ need to install Python 2.7 with virtualenv in your system as well.
|
||||||
If you want full support for searching inside your Read the Docs
|
If you want full support for searching inside your Read the Docs
|
||||||
site you will need to install Elasticsearch_.
|
site you will need to install Elasticsearch_.
|
||||||
|
|
||||||
Ubuntu users could install this package by following :doc:`/custom_installs/elasticsearch`.
|
Follow :doc:`/development/search` documentation for more instruction.
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue