Skip to content

Latest commit

 

History

History
251 lines (165 loc) · 7.31 KB

README.md

File metadata and controls

251 lines (165 loc) · 7.31 KB
Raw

scope-web

Core UW Scope components, including:

  • Provider registry web client in web_registry.
  • Server components:
    • Application server in server_flask.

Development Environment

With prerequisites:

A typical registry development environment then:

  • Runs a registry web client locally, with hot reloading.
  • Runs a Flask application server locally, with hot reloading.
invoke depend.install.all        # Install all dependencies.
invoke dev.registry.serve        # Serve the registry client, listening on `localhost:3000`, including hot reloading.
invoke dev.server.flask.serve    # Start Flask, listening on `localhost:4000`, including hot reloading.

The registry web client will then be accessible at http://localhost:3000/.

Using Invoke

This project uses Invoke for task execution.

invoke -l

For example:

Available tasks:

  database.forward          Forward the database cluster, listening on `localhost:5000`.
  depend.install.all        Install all dependencies.
  depend.install.flask      Install flask dependencies.
  depend.install.registry   Install registry dependencies.
  depend.install.tasks      Install tasks dependencies.
  depend.update.all         Update all dependencies.
  depend.update.flask       Update flask dependencies.
  depend.update.registry    Update registry dependencies.
  depend.update.tasks       Update tasks dependencies.
  dev.registry.serve        Serve the registry client, listening on `localhost:3000`, including hot reloading.
  dev.server.flask.serve    Start Flask, listening on `localhost:4000`, including hot reloading.
  prod.registry.build       Build a bundle of the registry client.
  prod.registry.serve       Serve a bundle of the registry client, listening on `0.0.0.0:3000`.
  prod.server.flask.serve   Start Flask, listening on `0.0.0.0:4000`.

Providing Secrets

Runtime secrets are expected in the secrets directory.

  • secrets/configuration/database_dev.yaml
  • secrets/configuration/flask_dev_local.yaml
  • secrets/configuration/documentdb.yaml
  • secrets/configuration/instance_ssh.yaml

Database Access

Contents of the database cluster can be directly inspected using:

  • MongoDB Compass

    Free and open source. To establish a connection:

    • Obtain a connection string from Invoke task database.forward.
    • Paste the connection string in a new connection.
    • Select 'Fill in connection fields individually'.
    • Select 'More Options'.
    • Select SSL value 'Unvalidated'.

  • Studio 3T

    Offers a non-commercial license. To establish a connection:

    • Obtain a connection string from Invoke task database.forward.
    • Paste the connection string via 'From URI...' in a new connection.

Installation of System Dependencies

Requires availability of Git, of Javascript dependencies, and of Python dependencies.

Git

Requires a Git executable on the path.

Javascript

For Javascript components, requires Node.js and the Yarn package manager.

Python

For Python components, requires Python and the Pipenv package manager.

  • Python

    Development uses version 3.9.x.

    On Windows, specific versions can be installed: https://www.python.org/downloads/

    On Mac, specific versions are managed using pyenv: https://github.com/pyenv/pyenv

  • Pipenv

    Pipenv manages creation of a Python virtual environment and pip installation of dependencies in that environment.

    Pipenv must be installed in an existing Python installation, typically a global installation:

    pip install pipenv

    The pipenv command is then available in that Python installation. For example:

    pipenv --version

    or as a module:

    python -m pipenv --version

    Depending on how a machine manages specific versions of Python, possibilities for accessing Pipenv include:

    • On Windows, install a specific version of Python in a known directory.
      Then use a full path to that installation:

      C:\Python39\Scripts\pip install pipenv
C:\Python39\Scripts\pipenv --version

    • On a Mac:

      • Install pyenv using Homebrew or pyenv-installer.
      • Install Pipenv in any Python environment, such as the global environment.

      Pipenv will detect a Pipfile's desired version of Python and use pyenv to create an appropriate virtual environment.

      pip install pipenv
pipenv --version

    With Pipenv installed and access to the pipenv command, see Initializing and Using Pipenv.

Initializing and Using Pipenv

Pipenv creates a Python virtual environment that includes the dependencies in a Pipfile.lock. You must first initialize the virtual environment, then activate a shell within the virtual environment.

Initializing Pipenv

Ensure Pipenv is installed and the pipenv command is accessible, as in Installation of System Dependencies:

pipenv --version

Initialize a virtual environment by using the pipenv command to install the Pipfile.lock dependencies:

pipenv sync

Then activate a shell inside the created virtual environment.

On Windows:

  • The pipenv shell implementation has issues (e.g., lacks command history). You may prefer:

    pipenv run cmd

  • As a convenience, this project includes:

    pipenv_activate.bat

  • When Pipenv is activated, the cmd environment will display (Pipenv):

    C:\devel\scope-web (Pipenv)>

On a Mac:

  • The default pipenv shell works well.

    pipenv shell

Using Pipenv

Within a Pipenv shell, all commands benefit from dependencies in Pipfile and Pipfile.lock. See examples in Development Environment and in Using Invoke.

This project's development dependencies also include Pipenv, so the pipenv command is available locally (e.g., without a need to reference a specific global installation).

  • To ensure all dependencies are current (i.e., match all Pipfile.lock and all yarn.lock):

    invoke depend.install.all

  • To install a new dependency, update versions of all dependencies, and update Pipfile and Pipfile.lock, first change into the project directory and then issue use pipenv install:

    cd <directory>
pipenv install <package>
cd ..

  • To install a new development dependency, update versions of all dependencies, and update Pipfile and Pipfile.lock, first change into the project directory and then issue use pipenv install --dev:

    cd <directory>
pipenv install --dev <package>
cd ..