Przeglądaj źródła

HUE-8888 [docs] Rewrite the dev onboarding to be simpler

Romain 5 lat temu
rodzic
commit
5d382e8e84

+ 3 - 5
README.md

@@ -25,15 +25,15 @@ Hue is also ideal for building your own [Cloud SQL Editor](https://docs.gethue.c
 Getting Started
 ---------------
 
-You can start Hue in 3 ways - From source, Docker or Kubernetes. Once setup you would have to configure Hue to connect with the desired database.
+You can start Hue in 3 ways - From source, Docker or Kubernetes. Once setup you would have to configure Hue to point to the desired databases you want to query.
 
 The [Forum](https://discourse.gethue.com/) is here in case you are looking for help.
 
 Building From Source
 -----------
 
-First, install dependencies, clone Hue repo, build and get the development server running.
-[Dependencies documentation](https://docs.gethue.com/administrator/installation/dependencies/) must help you in installing dependencies, and troubleshooting build issues.
+First, clone Hue repo, install the [dependencies](https://docs.gethue.com/administrator/installation/dependencies/), build and get the development server running.
+
 ```
 # Install dependencies
 git clone https://github.com/cloudera/hue.git
@@ -44,8 +44,6 @@ build/env/bin/hue runserver
 
 Now Hue should be running on [http://localhost:8000](http://localhost:8000)!
 
-Then, configure Hue to connect to a database for running queries. It is recommended to use MySQL or PostGres for development.
-
 Read more about configurations in the [development documentations](https://docs.gethue.com/developer/development/).
 
 Docker

+ 7 - 13
docs/docs-site/content/administrator/administration/operations.md

@@ -19,8 +19,7 @@ Next in each screen:
 
 ### Configuration
 
-Displays a list of the installed Hue applications and their configuration. The location of the folder containing the Hue
-configuration files is shown at the top of the page. Hue configuration settings are in the hue.ini configuration file.
+Displays a list of the installed Hue applications and their configuration.
 
 Hue ships with a default configuration that assumes a various set of services to be present in the cluster. If you are running on a real cluster, you can customize the `hue.ini` configuration file (`/etc/hue/hue.ini` when installed from the package version) or `pseudo-distributed.ini` in `desktop/conf` when in development mode).
 
@@ -29,24 +28,19 @@ these settings, see [Configuration](/administrator/configuration/).
 
 Hue loads and merges all of the files with extension `.ini` located in the `/etc/hue` directory. Files that are alphabetically later take precedence.
 
-To list all available configuration options, run:
-
-    /usr/share/hue/build/env/bin/hue config_help | less
-
-This commands outlines the various sections and options in the configuration,
-and provides help and information on the default values.
+After editing the ini file, Hue needs to be restarted.
 
+### Configuration Validation
 
-To view the current configuration from within Hue, open:
+To view the configuration of a running Hue instance, navigate to:
 
     http://<hue>/hue/dump_config
 
+The location of the folder containing the Hue ini files is shown at the top of the page as well as all the configuration values with help and information on the default values.
 
-### Configuration Validation
-
-Hue can detect certain invalid configuration.
+To list all available configuration options via the command line, run:
 
-To view the configuration of a running Hue instance, navigate to `http://myserver:8888/hue/dump_config`.
+    /usr/share/hue/build/env/bin/hue config_help | less
 
 ### Server Logs
 

+ 7 - 3
docs/docs-site/content/administrator/configuration/_index.md

@@ -5,11 +5,15 @@ draft: false
 weight: 3
 ---
 
-The file to edit is `hue.ini` (wich is based on this [template](https://github.com/cloudera/hue/blob/master/desktop/conf.dist/hue.ini)) and the actual values used can be checked on the [Dump Config](/administrator/administration/operations/#configuration) page.
+The file to edit is `hue.ini` (wich is based on this [template](https://github.com/cloudera/hue/blob/master/desktop/conf.dist/hue.ini)). The actual values used by the API server can be checked on the [Dump Config](/administrator/administration/operations/#configuration) page.
 
-Note: in development mode (when using `runserver` and not `runcpserver`), the correct hue.ini is `desktop/conf/pseudo-distributed.ini`
 
 The most important sections to configure are about the:
 
-* [Hue Server](/administrator/configuration/server/). e.g. pointing the application to a relational database where Hue saves users and queries, selecting the login method, customizing the look & feel, activating the task server service...
+* [API Server](/administrator/configuration/server/). e.g. pointing to a relational database where Hue saves users and queries, selecting the login method like LDAP, customizing the look & feel, activating special features, disabling some apps...
 * [Connectors](/administrator/configuration/connectors/). e.g. pointing to Data Warehouse services you want to make easy to query or browse. Those are typically which databases we want users to query with SQL or filesystems to browse.
+
+**Notes**
+
+* Restarting the server is currently required after for taking ini changes into consideration
+* In development mode (i.e. when using `./build/env/bin/hue runserver` and not `runcpserver`), the correct ini file is `desktop/conf/pseudo-distributed.ini`

+ 19 - 15
docs/docs-site/content/developer/development/_index.md

@@ -30,21 +30,17 @@ Build once:
 
     make apps
 
-[Dependencies documentation](/administrator/installation/dependencies/) must help in troubleshooting build issues.
+The [dependencies documentation](/administrator/installation/dependencies/) is here to help for troubleshooting build issues.
 
-Then start the dev server (which will auto reload):
+Then start the dev server (which will auto reload on file changes):
 
     ./build/env/bin/hue runserver
 
-If you are changing Javascript or CSS files, also start:
+If you are changing JavaScript or CSS files, also start:
 
     npm run dev
 
-### Connecting Database
-
-Once build, you need to connect Hue to a database to start running queries. It is recommended to use MySQL or PostGres for development. Refer [connectors documentation](/administrator/configuration/connectors/) for other supported databases.
-
-#### Configure MySQL
+Once build, in order to avoid the `database is locked` errors, you also need to connect Hue to a transactional database. It is recommended to use MySQL or PostGreSQL for development.
 
 Open the `desktop/conf/pseudo-distributed.ini` file in a text editor. Add the following options (and modify accordingly) for your MySQL setup:
 
@@ -57,26 +53,34 @@ Directly below the `[[database]]` line, add the following.
     password=secretpassword
     name=hue
 
-Below the `[[interpreters]]` of `[notebook]`.
+Read more about how [configurations work](/administrator/configuration/).
+
+### First SQL queries!
+
+Here is how to point the Editor to MySql or [Apache Hive](https://hive.apache.org/) and execute your first SQL queries. For other supported databases refer to the [connectors](/administrator/configuration/connectors/).
+
+#### MySQL
+
+In `desktop/conf/pseudo-distributed.ini`, below the `[[interpreters]]` section of of `[notebook]`.
 
     [[[mysql]]]
     name=MySQL
     interface=sqlalchemy
     options='{"url": "mysql://${USER}:${PASSWORD}@localhost:3306/hue"}'
 
-#### Configure Apache Hive
+#### Apache Hive
 
-You can connect to an existing Hive instance or setup a new one locally. An easy way to setup Hive locally is using Docker. You could use this container for Hive 2.3.2 - https://github.com/big-data-europe/docker-hive.
+You can connect to an existing Hive instance or setup a new one locally. An easy way to setup one is with Docker. You could use this container for Hive 2.3.2 - https://github.com/big-data-europe/docker-hive.
 
     git clone https://github.com/big-data-europe/docker-hive
     cd docker-hive
     docker-compose up -d
 
-Just follow the above 3 steps and you would have a running Hive instance on jdbc:hive2://localhost:10000. Follow [testing section](https://github.com/big-data-europe/docker-hive#testing) in the readme of the above repo to check if things are working as expected.
+Just follow the above 3 steps and you would have a running Hive instance on jdbc:hive2://localhost:10000.
 
 Now under Hue open `desktop/conf/pseudo-distributed.ini` file in a text editor, and modify the following options.
 
-Directly below the `[[beeswax]]` line, add the following.
+Directly below the `[[beeswax]]` line, add the following:
 
     # Host where HiveServer2 is running.
     hive_server_host=localhost
@@ -86,13 +90,13 @@ Directly below the `[[beeswax]]` line, add the following.
 
     thrift_version=7
 
-Below the `[[interpreters]]` of `[notebook]`, add.
+Below the `[[interpreters]]` of `[notebook]`, add:
 
     [[[hive]]]
       name=Hive
       interface=hiveserver2
 
-Restart Hue and you must be able to run Hive queries.
+Restart Hue, open the Editors and start typing your first queries!
 
 ### Dev environment