Update installation docs for v2 dashboard (#522)

montanalow · web-flow · commit c520804e68f9 · 2023-01-30T17:48:58.000-08:00
Co-authored-by: Montana Low &lt;montana.low@gmail.com&gt;
diff --git a/pgml-dashboard/README.md b/pgml-dashboard/README.md
@@ -0,0 +1,36 @@
+# PostgresML Dashboard
+
+PostgresML provides a dashboard with analytical views of the training data and model performance, as well as integrated notebooks for rapid iteration. It is primarily written in Rust using [Rocket](https://rocket.rs/) as a lightweight web framework and [SQLx](https://github.com/launchbadge/sqlx) to interact with the database.
+
+Please see the [online documentation](https://postgresml.org/user_guides/setup/quick_start_with_docker/) for general information on installing or deploying PostgresML. This document is intended to help developers set up a local copy of the dashboard. 
+
+## Requirements
+
+The dashboard requires a Postgres database with the [pgml-extension](https://github.com/postgresml/postgresml/tree/master/pgml-extension) to generate the core schema. See that subproject for developer setup.
+
+We develop and test this web application on Linux, OS X, and Windows using WSL2.
+
+## Build process
+
+You'll need to specify a database url for the extension to interact with via an environment variable:
+
+```commandline
+export DATABASE_URL=postgres://user_name:password@localhost:5432/database_name
+```
+
+Build and run:
+
+```commandline
+cargo run
+```
+
+Incremental and automatic compilation for development cycles is supported with: 
+
+```commandline
+cargo watch --exec run
+```
+
+Run tests:
+```commandline
+cargo test
+```
diff --git a/pgml-docs/docs/user_guides/setup/v2/installation.md b/pgml-docs/docs/user_guides/setup/v2/installation.md
@@ -216,46 +216,23 @@ That's it, PostgresML is ready. You can validate the installation by running:
 	(1 row)
 	```
 
-## Dashboard
+## Run the dashboard
 
-The dashboard is a Django application. Installing it requires no special dependencies or commands:
+The dashboard is a web app that can be run against any Postgres database with the extension installed. There is a Dockerfile included with the source code if you wish to run it as a container. Basic installation can be achieved with:
 
+1. Clone the repo (if you haven't already for the extension):
+```bash
+git clone https://github.com/postgresml/postgresml && cd postgresml/pgml-dashboard
+```
 
-=== ":material-linux: :material-microsoft: Linux & WSL"
-
-	Install Python if you don't have it already:
-
-	```bash
-	sudo apt-get update && \
-	sudo apt-get install python3 python3-pip python3-virtualenv
-	```
-
-=== ":material-apple: Mac"
-
-	Install Python if you don't have it already:
-
-	```bash
-	brew install python3
-	```
-
-1. Clone our repository (if you haven't already):
-
-	```bash
-	git clone https://github.com/postgresml/postgresml && \
-	cd postgresml/pgml-dashboard
-	```
-
-2. Setup a virtual environment (recommended but not required):
-
-	```bash
-	virtualenv venv && \
-	source venv/bin/activate
-	```
+2. Set the `DATABASE_URL` environment variable:
+```bash
+export DATABASE_URL=postgres://user_name:password@localhost:5432/database_name
+```
 
-3. Run the dashboard:
+3. Build and run the web application:
+```bash
+cargo run
+```
 
-	```bash
-	pip3 install -r requirements.txt && \
-	python manage.py migrate && \
-	python manage.py runserver
-	```
+The dashboard can be packaged for distribution. You'll need to copy the static files along with the `target/release` directory to your server.
diff --git a/pgml-extension/README.md b/pgml-extension/README.md
@@ -1,16 +1,16 @@
-# PostgresML 2.0
+# PostgresML Extension
 
-PostgresML is a PostgreSQL extension providing end-to-end machine learning inside your database. The extension is written in Rust using `tcdi/pgx` and provides LightGBM, XGBoost and [Linfa](https://github.com/rust-ml/linfa) algorithms.
+PostgresML is a PostgreSQL extension providing end-to-end machine learning inside your database. The extension is primarily written in Rust using [pgx](https://github.com/tcdi/pgx) and provides a SQL interface to various machine learning algorithm implementations such as [XGBoost](https://github.com/dmlc/xgboost), [LightGBM](https://github.com/microsoft/LightGBM), and [other classical methods](https://github.com/rust-ml/linfa).
 
-A backwards compatibility layer to Scikit-learn is provided as well, so the entirety of Scikit, XGBoost and LightGBM are available via the standard Scikit interface using Python. The Python layer is written using `pyo3`.
+Python seems to be the de facto ML industry standard, so we also include "reference" implementations of classical algorithms from Scikit-learn as well for comparison to the Rust implementations, but runtime performance and correctness. The Python integration is written using `pyo3`.
 
-See [our blog](https://postgresml.org/blog/postgresml-is-moving-to-rust-for-our-2.0-release/) for a performance comparison to Python.
+See [our blog](https://postgresml.org/blog/postgresml-is-moving-to-rust-for-our-2.0-release/) for a performance comparison and further motivations.
 
 ## Requirements
 
-PostgresML 2.0 requires Python 3.7 or above and the Rust compiler and toolchain. You can download the Rust compiler [here](https://rust-lang.org).
+PostgresML requires Python 3.7 or above and the Rust compiler and toolchain. You can download the Rust compiler [here](https://rust-lang.org).
 
-We develop this extension on Ubuntu, so it'll work best there, but it's very likely to work on other distros as well. Windows is only supported through WSL2. It's been tested and it works. Mac OS is also supported.
+We develop and test this extension on Linux, OS X, and Windows using WSL2.
 
 ## Dependencies
 
@@ -36,7 +36,7 @@ If your system comes with Python 3.6 or lower, you'll need to install `libpython
 
 ## Update postgresql.conf
 
-PostgresML 2.0 requires to be loaded as a shared library. For local development, this is in `~/.pgx/data-13/postgresql.conf`:
+PostgresML requires to be loaded as a shared library. For local development, this is in `~/.pgx/data-13/postgresql.conf`:
 
 ```
 shared_preload_libraries = 'pgml'     # (change requires restart)
@@ -54,6 +54,19 @@ shared_preload_libraries = 'pgml'     # (change requires restart)
 7. `SELECT * FROM pgml.train('Project name', 'regression', 'pgml.diabetes', 'target', 'xgboost');`
 8. `SELECT target, pgml.predict('Project name', ARRAY[age, sex, bmi, bp, s1, s2, s3, s4, s5, s6]) FROM pgml.diabetes LIMIT 10;`
 
+## Testing
+
+Run unit tests:
+```commandline
+cargo test
+```
+
+Run integration tests:
+```commandline
+cargo pgx run --release
+psql -h localhost -p 28813 -d pgml -f tests/test.sql -P pager
+```
+
 ## Packaging
 
 This requires Docker. Once Docker is installed, you can run:
diff --git a/pgml-extension/examples/image_classification.sql b/pgml-extension/examples/image_classification.sql
@@ -95,6 +95,6 @@ SELECT * FROM pgml.deploy('Handwritten Digits', 'rollback');
 SELECT * FROM pgml.deploy('Handwritten Digits', 'best_score', 'svm');
 
 -- check out the improved predictions
-SELECT target, pgml.predict('Handwritten Digits', image) AS prediction
+SELECT target, pgml.predict('Handwritten Digits', image::FLOAT4[]) AS prediction
 FROM pgml.digits 
 LIMIT 10;
diff --git a/pgml-extension/tests/test.sql b/pgml-extension/tests/test.sql
@@ -4,7 +4,7 @@
 --- Usage:
 ---
 ---   $ cargo pgx run --release
----   $ psql -P pager-off -h localhost -p 28813 -d pgml -f tests/test.sql
+---   $ psql -h localhost -p 28813 -d pgml -f tests/test.sql -P pager
 ---
 \set ON_ERROR_STOP true
 \timing on
