Skip to main content

Install OGRRE on your computer

OGRRE requires MongoDB. Follow the database setup guide, then configure GCP if you will use Google sign-in, Cloud Storage, or Document AI. Local development can instead use local storage, a custom document processing service, and disabled authentication. The Docker development guide also provides a local setup with MongoDB included.

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.​

Copy ogrre/.env.example to ogrre/.env and fill in the settings for your local backend. Keep this file and credential files out of Git.

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_CONNECTION: Full mongodb:// or mongodb+srv:// URI, or the short Atlas cluster identifier described in database setup.
  • DB_NAME: MongoDB database name.

When using a short Atlas cluster identifier, also set DB_USERNAME and DB_PASSWORD. A full MongoDB URI includes its own connection credentials when authentication is required.

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: Storage runtime 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).
  • DOCUMENT_AI_SERVICE_KEY: Document AI runtime service-account key filename/path used to connect to Google Document AI. See GCP service account setup.

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.

For local non-Docker backend runs with Google Cloud integrations, put the storage and Document AI runtime key files in orphaned-wells-ui-server/ogrre/ or set STORAGE_SERVICE_KEY and DOCUMENT_AI_SERVICE_KEY to absolute paths. Do not use a deployment or platform-administration service-account key as a backend runtime key.

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> && uvicorn ogrre.main:app --reload --host 127.0.0.1 --port 8001