Skip to content

Latest commit

 

History

History
187 lines (120 loc) · 4.54 KB

setup.md

File metadata and controls

187 lines (120 loc) · 4.54 KB

Setup Guide

This guide walks you through setting up GeoDatalytics for local development using Docker Compose.

Prerequisites

Initial Setup

1. Prepare the Web Client

# Copy environment configuration
cp web/.env.example web/.env

2. Build and Start Docker Containers

docker compose up

Note: Ensure all containers start and stay running before continuing. Check the logs for any errors.

3. Initialize the Database

While the containers are running, open a separate terminal and run:

# Apply database migrations
docker compose run --rm django ./manage.py migrate

# Create an admin user (you will be prompted for email and password)
docker compose run --rm -it django ./manage.py createsuperuser

Note: The createsuperuser command prompts you to create login credentials (email and password). Use these credentials to sign into both the Admin Panel and User Interface. If you forget your password, run createsuperuser again to create a new admin account.

Windows Users: If the createsuperuser command hangs or doesn't show prompts, prefix the command with winpty:

winpty docker compose run --rm -it django ./manage.py createsuperuser

4. Load Sample Data (Optional)

The ingest command loads datasets, charts, and project configuration from an ingestion file:

docker compose run --rm django ./manage.py ingest {JSON_FILE}

Available ingest options (paths relative to sample_data/):

  • boston_floods/data.json
  • multiframe_test.json
  • la_wildfires.json
  • new_york_energy/data.json

Running the Application

Start the Services

Default (CPU-only):

docker compose up

With GPU acceleration (NVIDIA systems only):

docker compose --profile gpu up --scale celery=0

Note: GPU mode requires NVIDIA drivers and nvidia-docker runtime.

Access Points

Service URL
User Interface http://localhost:8080/
Admin Panel http://localhost:8000/admin/
API Documentation http://localhost:8000/api/docs/swagger/

Log in using the credentials you created with createsuperuser.

Stop the Services

Press Ctrl+C in the terminal running docker compose up, or run:

docker compose stop

Application Maintenance

When new package dependencies or database schema changes occur, update your development environment:

# Pull latest base images
docker compose pull

# Rebuild containers (no cache)
docker compose build --pull --no-cache

# Apply any new migrations
docker compose run --rm django ./manage.py migrate

Troubleshooting

Container Build Failures

If you encounter build errors related to Python packages:

  1. Clear Docker build cache:

    docker compose build --no-cache

  2. Prune unused Docker resources:

    docker system prune -a

Database Connection Issues

Ensure PostgreSQL is running and healthy:

docker compose ps
docker compose logs postgres

Port Conflicts

If ports 8000, 8080, 5432, or 9000 are in use, modify the port mappings in docker-compose.override.yml.

GPU Not Available

If you see an error like:

Error response from daemon: could not select device driver "nvidia" with capabilities: [[gpu]]

This means GPU mode was requested but NVIDIA drivers aren't available. Use the default CPU mode instead:

docker compose up

GPU acceleration is optional and only needed for accelerated inferencing.

Windows-Specific Issues

Interactive commands don't work or hang:

On Windows (especially Git Bash/MINGW), interactive Docker commands like createsuperuser may hang or fail to display prompts. Prefix the command with winpty:

winpty docker compose run --rm -it django ./manage.py createsuperuser

"No such container" errors:

If you see errors like No such container: django when trying to attach to a running container, use docker compose run instead:

docker compose run --rm -it django ./manage.py <command>

This creates a new container instance rather than attaching to an existing one.