Browse Source

HUE-9368 [docs] Improve dev onboarding experience (sree) (#1151)

Co-authored-by: Romain Rigaux <romain.rigaux@gmail.com>
Sreenath Somarajapuram 5 years ago
parent
commit
a795011efd

+ 17 - 3
README.md

@@ -22,20 +22,31 @@ Hue is also ideal for building your own [Cloud SQL Editor](https://docs.gethue.c
 
 ![Hue Editor](https://cdn.gethue.com/uploads/2020/04/hue-4.7.png)
 
-
 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.
+
 The [Forum](https://discourse.gethue.com/) is here in case you are looking for help.
 
-First, add the development packages, build and get the development server running:
+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.
 ```
+# Install dependencies
 git clone https://github.com/cloudera/hue.git
 cd hue
 make apps
 build/env/bin/hue runserver
 ```
-Now Hue should be running on [http://localhost:8000](http://localhost:8000) ! The configuration in development mode is `desktop/conf/pseudo-distributed.ini`. Read more in the [installation documentation](https://docs.gethue.com/administrator/installation/).
 
+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
 ------
@@ -44,6 +55,9 @@ Start Hue in a single click with the [Docker Guide](https://github.com/cloudera/
 
     docker run -it -p 8888:8888 gethue/hue:latest
 
+Now Hue should be up and running on your default Docker IP on the port 8888 [http://localhost:8888](http://localhost:8888)!
+
+Read more about configurations [here](https://github.com/cloudera/hue/tree/master/tools/docker/hue#configuration).
 
 Kubernetes
 ----------

+ 1 - 1
docs/docs-site/content/administrator/configuration/_index.md

@@ -11,5 +11,5 @@ Note: in development mode (when using `runserver` and not `runcpserver`), the co
 
 The most important sections to configure are about the:
 
-* [Hue service](/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...
+* [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...
 * [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.

+ 13 - 2
docs/docs-site/content/administrator/installation/dependencies/_index.md

@@ -5,12 +5,19 @@ draft: false
 weight: -1
 ---
 
-## Dependencies
+### Python
 
 Hue employs some Python modules which use native code and requires certain development libraries be installed on your system. To install from the tarball, you'll need these library development packages and tools installed on your system:
 
+Versions supported:
 * Python 2.7
-* Python 3 (can be tested cf. instructions on [HUE-8737](https://issues.cloudera.org/browse/HUE-8737))
+* Python 3.5+ (can be tested cf. instructions on [HUE-8737](https://issues.cloudera.org/browse/HUE-8737))
+```
+# If you are using Python 3.5+, set PYTHON_VER before the build, like
+export PYTHON_VER=python3.8
+```
+
+### Database
 * [MySQL InnoDB or PostgreSQL or Oracle](https://www.cloudera.com/documentation/enterprise/latest/topics/hue_dbs_0.html)
 
 
@@ -101,6 +108,10 @@ Fix openssl errors (required for MacOS 10.11+)
 
     export LDFLAGS=-L/usr/local/opt/openssl/lib && export CPPFLAGS=-I/usr/local/opt/openssl/include
 
+If you are getting **"Could not find Python.h"** message
+
+    export SKIP_PYTHONDEV_CHECK=true
+
 On macOS 10.15+, install an older version of openssl
 
     brew uninstall --ignore-dependencies openssl && brew install https://github.com/tebelorg/Tump/releases/download/v1.0.0/openssl.rb

+ 23 - 3
docs/docs-site/content/developer/development/_index.md

@@ -22,8 +22,16 @@ This section goes into greater detail on how to build and reuse the components o
 
 Build once:
 
+    # If you are using Python 3.5+, set PYTHON_VER before the build, like
+    export PYTHON_VER=python3.8
+
+    # Mac user might need to set
+    export SKIP_PYTHONDEV_CHECK=true
+
     make apps
 
+[Dependencies documentation](/administrator/installation/dependencies/) must help in troubleshooting build issues.
+
 Then start the dev server (which will auto reload):
 
     ./build/env/bin/hue runserver
@@ -32,10 +40,15 @@ If you are changing Javascript or CSS files, also start:
 
     npm run dev
 
-Then it is recommended to use MySQL or PostGres as the database.
+### 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.
 
-Open the `hue.ini` file in a text editor. Directly below the `[[database]]` line, add the following options (and modify accordingly for
-your MySQL setup):
+#### Configure MySQL
+
+Open the `desktop/conf/pseudo-distributed.ini` file in a text editor. Add the following options (and modify accordingly) for your MySQL setup:
+
+Directly below the `[[database]]` line, add the following.
 
     host=localhost
     port=3306
@@ -44,6 +57,13 @@ your MySQL setup):
     password=secretpassword
     name=hue
 
+Below the `[[interpreters]]` of `[notebook]`.
+
+    [[[mysql]]]
+    name=MySQL
+    interface=sqlalchemy
+    options='{"url": "mysql://${USER}:${PASSWORD}@localhost:3306/hue"}'
+
 ### Dev environment
 
 #### Visual Code