*************
Project Setup
*************

Install the Project
===================

.. note::
   During the installation, an SQLite database will be generated automatically. 
   You can use the SQLite database for development and your local system. For the
   production system, you have to create a PostgreSQL database.

1. Open your **Anaconda Prompt** and activate your virtual environment

   .. code:: console

        conda activate iagos_dbms

2. Change to the directory in that you want to set up the project

   .. code:: console

        cd </your/directory/>

3. Obtain source code from git via HTTPS

   .. code:: console

        git clone https://jugit.fz-juelich.de/m.kennert/instruments-db.git

4. Change to your directory

   .. code:: console

        cd </your/directory/instruments-db>

5. Start the installation with the following command

   .. code:: console

        make install


Run the Web Application
=======================

This section describes how to run the web application (**Django-App**) as a stand-alone
application. Django provides a web server for development that restarts automatically by
changes. When you implement new features or want to test the web application,
there is no need to build the system.

1. Open your **Anaconda Prompt** and activate your virtual environment

   .. code:: console

        conda activate iagos_dbms

2. Run the web application

   .. code:: console

        make run

3. Open web browser and navigate to http://127.0.0.1:8000/

Run the Docker System
=====================

1. Open your **Anaconda Prompt** and activate your virtual environment

   .. code:: console

        conda activate iagos_dbms

2. Change to your directory

   .. code:: console

        cd </your/directory/instruments-db>

3. Build the **Docker** images

   .. code:: console

        make docker-build

4. Launch the **Docker** system

   .. code:: console

        make docker-up

5. Open web browser and navigate to http://127.0.0.1

Configure JupyterHub
====================

The following section is only relevant when you want to use the Docker system.
Since the *Django-App* and the *JupyterHub-App* are running in different
containers, you must create an entry for the in the database. Therefore, open your
browser and type http://127.0.0.1/o/applications/. Browser window will appear with
a list of applications (empty by default). Add new application by selecting "Click here",
and in the next step provide the following info:

* Name: JupyterHub
* Client id: Copy *CLIENT_ID* value from *iagos/deployment/.env*
* Client secret: Copy *CLIENT_SECRET* value from *iagos/deployment/.env*
* Client type: Confidential
* Authorization grant type: Authorization code
* Redirect URLs: http://127.0.0.1/jupyter/hub/oauth_callback

After you create an entry, you can start using the JupyterHub service.
Therefore, open http://127.0.0.1/jupyter/ and click on the button to authorize.
Subsequently, the notebook should start and is ready to use. In the folder
*team*, you can find notebooks that are shared within the group. In the folder
*work*, you can create your notebooks to experiment.

Configure the Production System
===============================

For this section, you need a virtual machine and a PostgreSQL database.
It's highly recommended to delegate this task to the IT department. In the following
example, we have a virtual machine that is reachable under the link **example-host.de**
and the database **iagos_db**.

.. important::

   You can switch between the production system and the development system by
   changing the variable **PRODUCTION**. For the production system set **PRODUCTION=True**,
   for the development system set **PRODUCTION=False**. If you use the development
   system, the generated SQLite database will be used.

1. Open the file *application/IAGOS/.env* and set your settings.

   .. code::

        PRODUCTION=True
        WEB_HOST=example-host.de
        DB_NAME=iagos_db
        DB_USER=m.kennert
        DB_PASSWORD=PASSWORD42
        DB_HOST=example-host.de
        DB_PORT=5432

2. Execute the following command to create the needed database tables

   .. code::
        
        make migrate

3. To verify that the application can connect with the PostgreSQL database and
   all needed database tables exist, run the web application with the following command

   .. code::
        
        make run

4. If the application starts without problems, then is application is connected
   with the PostgreSQL database. After it, you have to commit & push the settings
   file to the repository.