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=true
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 and files are stored in the backend Docker volume. This is 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.

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