Skip to main content

Install OGRRE on your computer

In addition to the frontend and backend code, OGRRE relies on a Mongo database and Google Cloud Platform. Before attempting to run OGRRE, follow the previous setup tutorials to learn how to set up MongoDB and configure GCP.

Install frontend​

1. Clone Repository​

Clone the frontend repository (https://github.com/CATALOG-Historic-Records/orphaned-wells-ui) and navigate to the root of the repository.

2. Install Javascript dependencies​

Prerequisites: Node Package Manager (npm). See https://www.npmjs.com/.

cd <orphaned-wells-ui-path>
npm clean-install

3. Set environment variables.​

Create a .env file at the root of the frontend project.

Required in all setups:

  • REACT_APP_BACKEND_URL: Backend URL the UI should call. For local development this is usually http://localhost:8001.

Optional, depending on your setup:

  • REACT_APP_GOOGLE_CLIENTID: Google OAuth client ID for frontend sign-in. Required when backend auth is enabled (REQUIRE_AUTH=true on the backend). Not required when running without auth.
  • REACT_APP_COLLABORATOR: Optional collaborator override (isgs, osage, etc.) used for collaborator-specific table configuration in the UI.

4. Run UI in browser​

cd <orphaned-wells-ui-path>
npm start

Install backend​

1. Clone Repository​

Clone the backend repository (https://github.com/CATALOG-Historic-Records/orphaned-wells-ui-server) and navigate to the root of the repository.

2. Create conda environment and install Python dependencies.​

Prerequisites: Python and conda. For more information on these see the Python and anaconda webpages.

Run the following command to create and activate a new Conda environment named uow-server-env:

conda env create --file environment.yml && conda activate uow-server-env

This will install the correct runtime versions of the backend (Python) and the backend dependencies.

Alternatively, if you already have an environment that you would like to install the dependencies in, activate your environment and run the command:

pip install .

3. Set environment variables.​

Create a .env file for the backend runtime (where your backend process loads environment variables).

Required in all setups:

  • ENVIRONMENT: Deployment environment name used by OGRRE (for example, isgs).
  • COLLABORATOR: Collaborator key used to load processor metadata (for example, isgs, calgem, or osage).
  • DB_USERNAME: MongoDB username. See database setup.
  • DB_PASSWORD: MongoDB password. See database setup.
  • DB_CONNECTION: MongoDB connection string. See database setup.
  • DB_NAME: MongoDB database name.

Optional toggles (defaults shown):

  • REQUIRE_AUTH: Enables API authentication/authorization checks (true or false, default: true).
  • USE_DB_PROCESSORS: If true, load processor definitions from MongoDB; if false, use collaborator processor API/defaults (default: false).
  • STORAGE_BACKEND: File storage backend (google or local, default: google).
  • DOCUMENT_AI_BACKEND: Document extraction backend (google or custom, default: google).

Required only when REQUIRE_AUTH=true:

  • token_uri: OAuth token endpoint used for token exchange/refresh. See GCP OAuth setup.
  • client_id: OAuth client ID used to validate user tokens. See GCP OAuth setup.
  • client_secret: OAuth client secret used for token exchange. See GCP OAuth setup.

Storage configuration:

When STORAGE_BACKEND=google:

  • STORAGE_BUCKET_NAME: Google Cloud Storage bucket for uploaded and generated files.
  • STORAGE_SERVICE_KEY: Service account key filename/path used to connect to Google Cloud Storage. See GCP service account setup.

When STORAGE_BACKEND=local:

  • LOCAL_STORAGE_ROOT: Local directory for uploaded/generated files (default: ~/.ogrre/uploads).
  • STORAGE_BUCKET_NAME is not required.

Document AI configuration:

When DOCUMENT_AI_BACKEND=google:

  • PROJECT_ID: Google Cloud project ID.
  • LOCATION: Google Cloud region for Document AI (for example, us).

When DOCUMENT_AI_BACKEND=custom:

  • DOCUMENT_AI_URL: HTTP endpoint for your custom document processing service.
  • DOCUMENT_AI_TIMEOUT: Timeout (seconds) for custom document-AI HTTP requests (default: 60).
  • PROJECT_ID and LOCATION are not required.

4. Start the backend server​

Ensure that the uow-server-env Conda environment is active​

conda activate uow-server-env

Start server on port 8001​

cd <orphaned-wells-ui-server-path>/app && uvicorn main:app --reload --host 127.0.0.1 --port 8001