diff --git a/Dockerfile b/Dockerfile index 1612df5d..16684b1d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -18,7 +18,7 @@ RUN apk add --no-cache bash \ # reqs layer ADD requirements.txt . RUN pip3 install -U -r requirements.txt -RUN pip3 install gunicorn +RUN pip3 install gunicorn==19.7.1 # Bundle app source ADD . /src diff --git a/README.md b/README.md index 812a8a85..86c514e2 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ For **full** installation and configuration instructions, see [Getting Started]( 1. Download or clone the repository. 2. Open terminal and point to root of repository. Type: ``pip install -r requirements.txt`` -3. Run server with: `` python application.py ``. Alternatively: ``./manage.py runserver`` +3. Run server with: `` python3 application.py ``. Alternatively: ``./manage.py runserver`` 4. Access HQ with: `` http://localhost:5000 `` For further installation and configuration help, please read the docs: [ElasticHQ Documentation](http://docs.elastichq.org) diff --git a/deployment/supervisord.conf b/deployment/supervisord.conf index 4efaf7ae..d4cfb92f 100644 --- a/deployment/supervisord.conf +++ b/deployment/supervisord.conf @@ -3,4 +3,6 @@ nodaemon=true [program:gunicorn] command=/usr/local/bin/gunicorn application:application -w 1 --worker-class eventlet --config /src/gunicorn.conf --log-config /src/logging.conf --bind 0.0.0.0:5000 -directory=/src \ No newline at end of file +directory=/src +stdout_logfile=/var/log/supervisor/stdout.log +stderr_logfile=/var/log/supervisor/stderr.log \ No newline at end of file diff --git a/docs/.doctrees/developer-guide.doctree b/docs/.doctrees/developer-guide.doctree index 5f563d4e..06375ec8 100644 Binary files a/docs/.doctrees/developer-guide.doctree and b/docs/.doctrees/developer-guide.doctree differ diff --git a/docs/.doctrees/environment.pickle b/docs/.doctrees/environment.pickle index 530ae5af..7a51665d 100644 Binary files a/docs/.doctrees/environment.pickle and b/docs/.doctrees/environment.pickle differ diff --git a/docs/.doctrees/faq.doctree b/docs/.doctrees/faq.doctree index 2da6491d..6d373574 100644 Binary files a/docs/.doctrees/faq.doctree and b/docs/.doctrees/faq.doctree differ diff --git a/docs/.doctrees/index.doctree b/docs/.doctrees/index.doctree index b5ee6c84..5be16447 100644 Binary files a/docs/.doctrees/index.doctree and b/docs/.doctrees/index.doctree differ diff --git a/docs/.doctrees/installation.doctree b/docs/.doctrees/installation.doctree index c7b52611..49c7bf1e 100644 Binary files a/docs/.doctrees/installation.doctree and b/docs/.doctrees/installation.doctree differ diff --git a/docs/.doctrees/rest-api.doctree b/docs/.doctrees/rest-api.doctree index da474b91..52e2fe0f 100644 Binary files a/docs/.doctrees/rest-api.doctree and b/docs/.doctrees/rest-api.doctree differ diff --git a/docs/.doctrees/table-with-code.doctree b/docs/.doctrees/table-with-code.doctree index e589fd80..f867d9d1 100644 Binary files a/docs/.doctrees/table-with-code.doctree and b/docs/.doctrees/table-with-code.doctree differ diff --git a/docs/.doctrees/user-guide.doctree b/docs/.doctrees/user-guide.doctree index bf96c149..26dc022c 100644 Binary files a/docs/.doctrees/user-guide.doctree and b/docs/.doctrees/user-guide.doctree differ diff --git a/docs/_sources/installation.txt b/docs/_sources/installation.txt index 611cca83..f57527da 100644 --- a/docs/_sources/installation.txt +++ b/docs/_sources/installation.txt @@ -26,7 +26,7 @@ Install ElasticHQ 1. Download or clone the repository https://github.com/ElasticHQ/elasticsearch-HQ 2. Navigate to the root of the repository: ``pip install -r requirements.txt`` -3. Start the server: ``python application.py`` +3. Start the server: ``python3 application.py`` 4. Point your browser to: http://localhost:5000 .. note:: Alternatively, you can start the server with ``python manage.py runserver`` @@ -76,14 +76,16 @@ Command line Parameters The ``application.py`` start script takes parameters passed in as arguments from the command line: - =========== ========================= ==================================================================== - Arg Default Value Definition - =========== ========================= ==================================================================== - ``--host`` 127.0.0.1 Host the HQ server should be reachable on. - ``--port`` 5000 Port to reach HQ server. - ``--debug`` False If True, exposes debug data to UI and causes reload on code changes. - ``--url`` ``http://localhost:9200`` Default URL displayed on the initial connection screen. - =========== ========================= ==================================================================== + ================ ========================= ==================================================================== + Arg Default Value Definition + ================ ========================= ==================================================================== + ``--host`` 127.0.0.1 Host the HQ server should be reachable on. + ``--port`` 5000 Port to reach HQ server. + ``--debug`` False If True, exposes debug data to UI and causes reload on code changes. + ``--url`` ``http://localhost:9200`` Default URL displayed on the initial connection screen. + ``--enable-ssl`` False If flag is passed, assumes ssl cert will be used. + ``--ca-certs`` /path/to/your/ca.crt Path to your CA Certificate. Required if enable-ssl is passed. + ================ ========================= ==================================================================== .. _environment variables: @@ -94,6 +96,8 @@ Environment Variables Arg Default Value Definition ================== ========================= ==================================================================== ``HQ_DEFAULT_URL`` ``http://localhost:9200`` Default URL displayed on the initial connection screen. + ``HQ_ENABLE_SSL`` False If flag is passed, assumes ssl cert will be used. + ``HQ_CA_CERTS`` /path/to/your/ca.crt Path to your CA Certificate. Required if enable-ssl is passed. ================== ========================= ==================================================================== @@ -106,6 +110,16 @@ Advanced users that want to have control over the logging output, can adjust it Docker users will find the logfile location under ``/src/application.log`` +Connecting with SSL +^^^^^^^^^^^^^^^^^^^ + +Thanks to a community contribution, SSL Cert support has been added: `SSL Support `_. + +Enable SSL Cert support by starting HQ as so: + +``python -m application --enable-ssl --ca-certs /path/to/your/ca.crt`` + + Database ^^^^^^^^ @@ -113,6 +127,35 @@ ElasticHQ ships with SQLLite integration to store clusters you have connected to .. note:: In the event you want to start with a clean slate, simply delete the ``elastichq.db`` file. ElasticHQ will recreate it at next startup. +External Configuration +^^^^^^^^^^^^^^^^^^^^^^ + +External configuration files are supported for those wanting to preserve their user-specified settings between upgrades. + +On startup, HQ checks the following locations for a file named ``settings.json``: + +* `/etc/elastic-hq/settings.json` +* `~/settings.json` +* CURRENT WORKING DIRECTORY + ``/settings.json`` +* CURRENT WORKING DIRECTORY + ``/elastichq/settings.json`` +* CURRENT WORKING DIRECTORY + ``/config/settings.json`` + +Current supported parameters are: + + =========================== ==================================================================== + Key Definition + =========================== ==================================================================== + ``SQLALCHEMY_DATABASE_URI`` Location and Name of ElasticHQ database file. + =========================== ==================================================================== + +The settings file should be in standard JSON: + +.. code-block:: json + + { + "SQLALCHEMY_DATABASE_URI" : "sqlite:////SOME/PATH/TO/DB_NAME.db" + } + Upgrading --------- @@ -184,7 +227,7 @@ Failure in connecting initially to an Elasticsearch cluster, can happen for seve .. _xpack integration: X-Pack Integration -~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^ X-Pack is configured with authentication. To connect, you must pass along the username and password in the connection URL using the format ``http://USERNAME:PASSWORD@DOMAIN:PORT`` @@ -201,6 +244,32 @@ In the base installation, the logs are available under the ``/install/path/appli For docker images, the application logging can be found under ``/src/application.log``. +.. _ssl_trouble: + +SSL Cert not working +^^^^^^^^^^^^^^^^^^^^ + +**NOTE: Your CA file must be the same signer of your Elasticsearch node, for HQ to connect as a trusted source.** + +Verify that the certificate works by connecting directly from the HQ instance to the ES node in question, using the cert: + +``curl -u admin:password --ca-certs /path/to/ca.crt https://localhost:9200/_cluster/settings?pretty`` + +Preserving Database across Docker container restarts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following code block originated as an issue (https://github.com/ElasticHQ/elasticsearch-HQ/issues/409) for those wanting to preserve the HQ SQLLite DB between container restarts. + +.. code-block:: bash + + docker run --detach + --restart=always + --net host + --volume elastichq:/src/db + --name elastichq + elastichq/elasticsearch-hq + sh -x -c 'sed -i -r -e "s/_sqlalchemy_database_uri =.*/_sqlalchemy_database_uri = "sqlite:///" + os.path.join(BASEPATH, "db" , "elastichq.db")/" /src/elastichq/config/settings.py && exec supervisord -c /etc/supervisor/supervisord.conf' + License ------- diff --git a/docs/installation.html b/docs/installation.html index b9429e76..f092607c 100644 --- a/docs/installation.html +++ b/docs/installation.html @@ -92,7 +92,9 @@

Table Of Contents

  • Command line Parameters
  • Environment Variables
  • Logging
    • +
  • Connecting with SSL
  • Database
    • +
  • External Configuration
  • Upgrading
    • -
  • Upgrading