Skip to main content

Run OGRRE with Docker

The Docker development stack is the recommended way to run OGRRE locally. It starts the React frontend, FastAPI backend, and MongoDB together with one command.

Prerequisites​

  • Node.js with npm
  • Docker Desktop or Docker Engine
  • Docker Compose v2, available as docker compose
  • Docker running before you start the stack

Clone the frontend repository​

Clone the frontend repository and go to the repository root:

git clone https://github.com/CATALOG-Historic-Records/orphaned-wells-ui.git
cd orphaned-wells-ui

Start the stack​

Run:

npm run docker:start

The startup script creates deployment/.env from deployment/.env.example if the file does not already exist. Shell environment variables override matching values from deployment/.env for the Node-backed npm commands.

When startup finishes, open:

  • Frontend: http://localhost:3000
  • Backend health endpoint: http://localhost:8001/health
  • MongoDB host port: 127.0.0.1:27018

The Docker-published ports bind to 127.0.0.1 by default, so the development stack is reachable from your local machine without exposing the frontend, backend, or MongoDB on all host interfaces.

Backend mode​

By default, BACKEND_MODE=auto.

In auto mode, the Docker script checks for a sibling backend repository at ../orphaned-wells-ui-server:

  • If the backend source exists, Docker builds and runs the backend from local source.
  • If the backend source does not exist, Docker pulls and runs the backend image configured by BACKEND_IMAGE.

In source mode, Docker bind-mounts the backend source into the container and starts Uvicorn with --reload, scoped to /code/ogrre with a short reload delay and Python bytecode writes disabled so Docker Desktop file-sync timing is less likely to serve stale imports. Normal Python code edits are picked up by the running backend. Dependency, packaging, Dockerfile, and startup-command changes require npm run docker:start so Compose can rebuild and recreate the backend container.

For backend development, clone the backend repository next to the frontend repository:

cd ..
git clone https://github.com/CATALOG-Historic-Records/orphaned-wells-ui-server.git
cd orphaned-wells-ui
npm run docker:start

You can also set BACKEND_MODE in deployment/.env:

BACKEND_MODE=auto
BACKEND_MODE=source
BACKEND_MODE=image

Use source when you want to require a local backend checkout. Use image when you want to ignore local backend source and run the configured backend image.

Configure local settings​

Most local Docker settings live in deployment/.env.

Common frontend settings:

REACT_APP_BACKEND_URL=http://localhost:8001
REACT_APP_COLLABORATOR=isgs

Common backend settings:

ENVIRONMENT=development
COLLABORATOR=isgs
LOCATION=us
DB_CONNECTION=mongodb://mongodb:27017
DB_NAME=isgs
DB_USERNAME=
DB_PASSWORD=
REQUIRE_AUTH=false
USE_DB_PROCESSORS=false
STORAGE_BACKEND=local
LOCAL_STORAGE_URL_BASE=http://localhost:8001/local-storage
DOCUMENT_AI_BACKEND=google

Set DB_CONNECTION, DB_NAME, DB_USERNAME, and DB_PASSWORD in deployment/.env to use a different MongoDB instance. Existing .env files are not regenerated from .env.example, so add missing keys manually after pulling deployment changes.

With the default Docker settings, authentication is disabled, files are stored in the backend Docker volume, and schemas come from the installed ogrre_data_cleaning package in read-only mode. Set USE_DB_PROCESSORS=true explicitly to use editable, database-backed schemas. These defaults are suitable for local development and CI, but not for production.

If you enable Google Cloud integrations, add the relevant project, bucket, service-account, and OAuth values in deployment/.env. See Create Google service-account keys for the storage and Document AI runtime keys used by local Docker.

For Google-backed local Docker runs, set the runtime key paths in deployment/.env:

PROJECT_ID=<project-id>
LOCATION=us
STORAGE_BACKEND=google
STORAGE_BUCKET_NAME=<bucket-name>
STORAGE_SERVICE_KEY=ogrre-storage-runtime-service-key.json
DOCUMENT_AI_BACKEND=google
DOCUMENT_AI_SERVICE_KEY=ogrre-document-ai-service-key.json

Put those key files next to deployment/.env or use absolute paths. The Docker start scripts mount each file into the backend container separately.

For directory uploads using the staging bucket (uploaded_documents_v0), Terraform includes http://localhost:3000 and http://localhost:3001 in the bucket CORS defaults. Normal Docker development uses port 3000; the isolated E2E stack uses port 3001. The local backend's ALLOWED_ORIGINS must include the origin you open in the browser. See upload bucket configuration for other hosts or ports. With STORAGE_BACKEND=local, bucket CORS is not used.

Stop or reset the stack​

Stop containers without removing them:

npm run docker:stop

Stop and remove containers and the Docker network, while keeping named volumes:

npm run docker:down

Stop and remove containers, the Docker network, and named volumes:

npm run docker:clean

Use docker:clean when you want MongoDB and backend uploaded-file data to be reset.

Seed data​

The local MongoDB container restores the sample dump in deployment/mongo-dumps/sample_mongodump automatically the first time the mongodb_data volume is created.

To reset MongoDB and reinitialize from the sample dump:

npm run docker:clean
npm run docker:start

To restore the sample dump into an existing Docker MongoDB volume:

docker compose --env-file deployment/.env -f deployment/docker-compose.dev.yml --profile seed run --rm mongo-restore

The Cypress E2E suite uses the same sample dump for local and CI runs. Local E2E runs should use the isolated npm run docker:e2e stack, which restores into DB_NAME=isgs_e2e by default. See Testing and E2E CI for the test commands and reset behavior.

Shell script variants​

The Node-backed npm commands are the cross-platform path for macOS, Linux, and Windows.

Legacy shell script variants are also available for macOS, Linux, Git Bash, and WSL:

npm run docker:start:shell
npm run docker:stop:shell
npm run docker:down:shell
npm run docker:clean:shell

Troubleshooting​

If ports are already in use, change the host ports in deployment/.env:

FRONTEND_HOST_PORT=3000
BACKEND_HOST_PORT=8001
MONGODB_HOST_PORT=27018

If you change FRONTEND_HOST_PORT, also set ALLOWED_ORIGINS to the frontend's browser origin, for example http://localhost:3001. The browser uses the published host port even though the frontend listens on port 3000 inside Docker. For Google-backed development, keep the bucket CORS origin list aligned as documented above. Opening http://127.0.0.1:3001 requires that exact origin; it does not match http://localhost:3001.

If you change BACKEND_HOST_PORT, also update:

REACT_APP_BACKEND_URL=http://localhost:<BACKEND_HOST_PORT>
LOCAL_STORAGE_URL_BASE=http://localhost:<BACKEND_HOST_PORT>/local-storage

To inspect the running stack:

docker compose --env-file deployment/.env -f deployment/docker-compose.dev.yml ps
docker compose --env-file deployment/.env -f deployment/docker-compose.dev.yml logs --tail=200

If BACKEND_MODE=image uses a private backend image, authenticate with the container registry before running npm run docker:start.