Split installation and user_guide from index.rst

BEMServer · Aug 25, 2022 · 672d0f7 · 672d0f7
1 parent 6dbad51
commit 672d0f7
Show file tree

Hide file tree

Showing 3 changed files with 190 additions and 170 deletions.
diff --git a/source/index.rst b/source/index.rst
@@ -19,175 +19,11 @@ BEMServer uses a relational database to store
 BEMServer manages data access permissions by groups of users.
 
 
-Basic concepts
-==============
+Guide
+=====
 
-The high-level entity for a project is the campaign. A campaign may span on
-several sites and buildings. It has beginning and end dates, although the end
-date may be left open to let the campaign last indefinitely.
+.. toctree::
+    :maxdepth: 1
 
-Users are associated to user groups. User groups provide access to campaigns.
-
-Timeseries and events data in a campaign may be split into separate scopes.
-Campaign scopes are used to organize data and to provide more fine-grained
-permissions.
-
-
-Architecture
-============
-
-BEMServer is made of several software bricks.
-
-BEMServer Core
---------------
-
-BEMServer Core is the central part. It is responsible for the connection with
-the database. It exposes objects that can be used by other blocks.
-
-It implements the authorization and authorization layer.
-
-It is meant to be imported and used by blocks trusted code as it gives direct
-acces to the database.
-
-BEMServer API
--------------
-
-BEMServer API is a web REST API that exposes the core. It can be exposed over
-the Internet to be accessed by external modules.
-
-It exposes its own documentation in the OpenAPI format for module developers.
-
-BEMServer UI
-------------
-
-BEMServer UI is the web interface to BEMServer. It communicates with the core
-via BEMServer API.
-
-This is the part that is meant to be exposed to final users.
-
-It provides an interface for both administrative tasks (user management,...)
-and data analysis (data visualization).
-
-
-Installation
-============
-
-To get BEMServer up and running, one needs to run both BEMServer API and
-BEMServer UI.
-
-All BEMServer blocks are written in Python and require Python 3.9+.
-
-The instructions that follow are tested on a Debian 11 (Bullseye) system.
-
-Prerequisites
--------------
-
-BEMServer relies on PostgreSQL and the TimescaleDB extension.
-
-First, install PostgreSQL 13::
-
-    $ aptitude install postgresql
-
-TimescaleDB is not in the Debian repositories. Follow instructions in
-https://docs.timescale.com/latest/getting-started/setup
-
-.. note::
-    There is no need to install PostgreSQL from external repositories as
-    suggested in TimescaleDB docs.
-
-Create a database and install TimescaleDB extension (should be done after each
-TimescaleDB update).
-
-Assuming the user has database creation permission:::
-
-    $ createdb bemserver
-    $ psql -U $USER -d bemserver -c "CREATE EXTENSION IF NOT EXISTS timescaledb"
-
-Install prerequisites for psycopg2 compilation (used by BEMServer Core)::
-
-    $ aptitude install python3-dev libpq-dev
-
-BEMServer API
--------------
-
-.. note::
-    It is advised to work in a dedicated virtual environment.
-
-Install bemserver_api::
-
-    $ pip install bemserver_core
-
-Database setup
-^^^^^^^^^^^^^^
-
-Set DB URI in an environment variable (adapt line with actual values)::
-
-    $ export SQLALCHEMY_DATABASE_URI="postgresql+psycopg2://user:password@localhost:5432/bemserver"
-
-Use `setup_db` command to initialize a clean database::
-
-    $ bemserver_setup_db
-
-Create an admin user::
-
-    $ bemserver_create_user --name chuck --email chuck@norris.com --admin
-
-API setup
-^^^^^^^^^
-
-Create a configuration file (e.g. bemserver-api.cfg). Add API parameters:
-
-.. code-block::
-
-       SQLALCHEMY_DATABASE_URI="postgresql+psycopg2://user:password@localhost:5432/bemserver"
-
-Set an environment variable to point to that file::
-
-    $ export FLASK_SETTINGS_FILE="/path/to/bemserver-api.cfg"
-
-At this point, the web API can be launched from the command line::
-
-    $ flask run
-
-It can be accessed in a local browser at http://localhost:5000.
-
-.. warning::
-    While this is fine in development mode, production setups should use a real
-    webserver such as Apache or Nginx.
-
-
-BEMServer UI
-------------
-
-.. note::
-    It is advised to work in a dedicated virtual environment.
-
-Install bemserver_ui::
-
-    $ pip install bemserver_ui
-
-UI setup
-^^^^^^^^
-
-Create a configuration file (e.g. bemserver-ui.cfg). Add UI parameters:
-
-.. code-block::
-
-    BEMSERVER_API_HOST = "localhost:5000"
-    BEMSERVER_API_USE_SSL = False
-
-Set an environment variable to point to that file::
-
-    $ export FLASK_SETTINGS_FILE="/path/to/bemserver-ui.cfg"
-
-At this point, the web UI can be launched from the command line::
-
-    $ flask run -p 5001
-
-.. note::
-    Flask uses port 5000 by default. Be sure to specify another port for either
-    bemserver_api or bemserver_ui to avoid a conflict.
-
-.. warning::
-    While this is fine in development mode, production setups should use a real
-    webserver such as Apache or Nginx.
+    installation
+    user_guide
diff --git a/source/installation.rst b/source/installation.rst
@@ -0,0 +1,166 @@
+.. _installation:
+
+============
+Installation
+============
+
+Architecture
+============
+
+BEMServer is made of several software bricks.
+
+BEMServer Core
+--------------
+
+BEMServer Core is the central part. It is responsible for the connection with
+the database and the authorization and authorization layer.
+
+It exposes objects that can be used by other blocks.
+
+It is meant to be imported and used by trusted code as it gives direct acces to
+the database.
+
+It is used internally by BEMServer API.
+
+BEMServer API
+-------------
+
+BEMServer API is a web REST API that exposes the core. It can be exposed over
+the Internet to be accessed by external modules.
+
+It exposes its own documentation in the OpenAPI format for module developers.
+
+BEMServer UI
+------------
+
+BEMServer UI is the web interface to BEMServer. It communicates with the core
+via BEMServer API.
+
+This is the interface that is meant to be exposed to final users.
+
+It provides an interface for both administrative tasks (user management,...)
+and data analysis (data visualization).
+
+
+Install BEMServer
+=================
+
+To get BEMServer up and running, one needs to run both BEMServer API and
+BEMServer UI.
+
+All BEMServer blocks are written in Python and require Python 3.9+.
+
+The instructions that follow are tested on a Debian 11 (Bullseye) system.
+
+Prerequisites
+-------------
+
+BEMServer relies on PostgreSQL and the TimescaleDB extension.
+
+First, install PostgreSQL 13::
+
+    $ aptitude install postgresql
+
+TimescaleDB is not in the Debian repositories. Follow instructions in
+https://docs.timescale.com/latest/getting-started/setup
+
+.. note::
+    There is no need to install PostgreSQL from external repositories as
+    suggested in TimescaleDB docs.
+
+Create a database and install TimescaleDB extension (should be done after each
+TimescaleDB update).
+
+Assuming the user has database creation permission:::
+
+    $ createdb bemserver
+    $ psql -U $USER -d bemserver -c "CREATE EXTENSION IF NOT EXISTS timescaledb"
+
+Install prerequisites for psycopg2 compilation (used by BEMServer Core)::
+
+    $ aptitude install python3-dev libpq-dev
+
+BEMServer API
+-------------
+
+.. note::
+    It is advised to work in a dedicated virtual environment.
+
+Install bemserver_api::
+
+    $ pip install bemserver_core
+
+Database setup
+^^^^^^^^^^^^^^
+
+Set DB URI in an environment variable (adapt line with actual values)::
+
+    $ export SQLALCHEMY_DATABASE_URI="postgresql+psycopg2://user:password@localhost:5432/bemserver"
+
+Use `setup_db` command to initialize a clean database::
+
+    $ bemserver_setup_db
+
+Create an admin user::
+
+    $ bemserver_create_user --name chuck --email chuck@norris.com --admin
+
+API setup
+^^^^^^^^^
+
+Create a configuration file (e.g. bemserver-api.cfg). Add API parameters:
+
+.. code-block::
+
+       SQLALCHEMY_DATABASE_URI="postgresql+psycopg2://user:password@localhost:5432/bemserver"
+
+Set an environment variable to point to that file::
+
+    $ export FLASK_SETTINGS_FILE="/path/to/bemserver-api.cfg"
+
+At this point, the web API can be launched from the command line::
+
+    $ flask run
+
+It can be accessed in a local browser at http://localhost:5000.
+
+.. warning::
+    While this is fine in development mode, production setups should use a real
+    webserver such as Apache or Nginx.
+
+
+BEMServer UI
+------------
+
+.. note::
+    It is advised to work in a dedicated virtual environment.
+
+Install bemserver_ui::
+
+    $ pip install bemserver_ui
+
+UI setup
+^^^^^^^^
+
+Create a configuration file (e.g. bemserver-ui.cfg). Add UI parameters:
+
+.. code-block::
+
+    BEMSERVER_API_HOST = "localhost:5000"
+    BEMSERVER_API_USE_SSL = False
+
+Set an environment variable to point to that file::
+
+    $ export FLASK_SETTINGS_FILE="/path/to/bemserver-ui.cfg"
+
+At this point, the web UI can be launched from the command line::
+
+    $ flask run -p 5001
+
+.. note::
+    Flask uses port 5000 by default. Be sure to specify another port for either
+    bemserver_api or bemserver_ui to avoid a conflict.
+
+.. warning::
+    While this is fine in development mode, production setups should use a real
+    webserver such as Apache or Nginx.
diff --git a/source/user_guide.rst b/source/user_guide.rst
@@ -0,0 +1,18 @@
+.. _user_guide:
+
+==========
+User guide
+==========
+
+Basic concepts
+==============
+
+The high-level entity for a project is the campaign. A campaign may span on
+several sites and buildings. It has beginning and end dates, although the end
+date may be left open to let the campaign last indefinitely.
+
+Users are associated to user groups. User groups provide access to campaigns.
+
+Timeseries and events data in a campaign may be split into separate scopes.
+Campaign scopes are used to organize data and to provide more fine-grained
+permissions.