From 47ece732d0d1ba68d30a3df0d5667d1927c579d4 Mon Sep 17 00:00:00 2001 From: Stuart McAlpine Date: Mon, 30 Sep 2024 14:46:37 +0200 Subject: [PATCH] Update installation docs --- docs/source/index.rst | 1 + docs/source/installation.rst | 91 ++++++++-------------------------- docs/source/tutorial_setup.rst | 7 ++- 3 files changed, 24 insertions(+), 75 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 99a10d90..0eabf1d4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -59,6 +59,7 @@ them. dev_notes_spin dev_notes_database + installation_locally .. toctree:: :maxdepth: 2 diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 385974c3..5e3a97b1 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -3,76 +3,22 @@ Installation ============ -Currently the DESC data registry software can only be used at NERSC (i.e., -PerlMutter). +Currently the DESC ``dataregistry`` database is only accessible through NERSC +(i.e., PerlMutter). -Main installation steps ------------------------ +Using the ``dataregistry`` at NERSC +------------------------------------ -When installing the ``dataregistry`` package, it is recommended to work within -your own Conda or Python virtual environment. +The ``dataregistry`` package is readily available as part of the +``desc-python-bleed`` environment (see `here +`__ +for details about the *Conda* environments available at NERSC). Therefore +before getting started, make sure to activate the ``desc-python-bleed`` +environment from the command line, or, when working at the NERSC JupyterHub, +select the ``desc-python-bleed`` kernel. -Creating a Conda environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can make a new Conda environment via - -.. code-block:: bash - - module load conda/Mambaforge-22.11.1-4 - conda create -p ./datareg_env psycopg2 - -where ``./datareg_env`` is the path where the environment will be installed -(change this as required). To activate the environment do - -.. code-block:: bash - - conda activate - -Creating a Python venv -~~~~~~~~~~~~~~~~~~~~~~ - -or, you can work within a Python virtual environment via - -.. code-block:: bash - - module load python/3.10 - python3 -m venv ./datareg_env - -where ``./datareg_env`` is the path where the environment will be installed -(change this as required). To activate the environment do - -.. code-block:: bash - - source /bin/activate - -Note the specific version of Python used above (``3.10``) is only an example, -the ``dataregistry`` package is supported on Python versions ``>3.7``. - -Installing the ``dataregistry`` package -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Now we can install the DESC data registry software. First clone the GitHub -repository - -.. code-block:: bash - - git clone https://github.com/LSSTDESC/dataregistry.git - -then, navigate to the ``dataregistry`` directory and install via *pip* using - -.. code-block:: bash - - python3 -m pip install . - -You can test to see if the ``dataregistry`` package has installed successfully -by typing - -.. code-block:: bash - - python3 -c "import dataregistry; print(dataregistry.__version__)" - -If you see the current package version printed to the console, success! +If you wish to install the ``dataregistry`` package yourself, see the +instructions :ref:`here `. .. _one-time-setup: @@ -90,7 +36,10 @@ entry .. code-block:: yaml - sqlalchemy.url : postgresql://reg_writer@data-registry-dev-loadbalancer.jrb-test.development.svc.spin.nersc.org:5432/desc_data_registry + sqlalchemy.url : postgresql://@dataregistry-release-test-loadbalancer.mcalpine-test.development.svc.spin.nersc.org:5432/desc_data_registry + +where ```` should either be ``reg_writer`` or ``reg_reader``, +depending on what account you have access to. Then (if you don't have one already), create a file named ``~/.pgpass`` in your ``$HOME`` directory, and append the entry @@ -98,11 +47,11 @@ Then (if you don't have one already), create a file named ``~/.pgpass`` in your .. code-block:: bash # data registry db - data-registry-dev-loadbalancer.jrb-test.development.svc.spin.nersc.org:5432:desc_data_registry:reg_writer: + dataregistry-release-test-loadbalancer.mcalpine-test.development.svc.spin.nersc.org:5432:desc_data_registry:: where ```` is provided on demand by the DESC data registry admins. As -a final step, the ``.pgpass`` file must only be readable by you, which you -can ensure by doing +a final step, the ``.pgpass`` file must only be readable by you, which you can +ensure by doing .. code-block:: bash diff --git a/docs/source/tutorial_setup.rst b/docs/source/tutorial_setup.rst index fd7ddf7e..abc6f3ca 100644 --- a/docs/source/tutorial_setup.rst +++ b/docs/source/tutorial_setup.rst @@ -6,9 +6,8 @@ This section has some tutorials on how to get started using the Before we begin, make sure that you have the ``dataregistry`` package installed and available to you at NERSC (installation instructions :ref:`here -`). This is generally -simplest within a Conda or Python virtual environment (note that the -``dataregistry`` is not yet part of the `desc-python` environment). +`). This is generally simplest working within the +``desc-python-bleed`` Conda environment. Also, make sure you have completed the one-time-setup for the data registry (more details :ref:`here `), @@ -30,6 +29,6 @@ reference materials, however they can also be used interactively. To do this at NERSC, first clone the ``dataregistry`` repository to your home space, then load the notebooks through the NERSC JupyterHub portal. Note that you will need to be operating within a kernel that has the ``dataregistry`` -package installed (see `here +package installed, i.e., ``desc-python-bleed`` (see `here `__ how to register your own Python environments as Jupyter kernels).