Fix Docker build and runtime issues for cross-platform support

dev/Dockerfile

@@ -2,11 +2,13 @@ FROM python:3.11-slim
 # Install system libraries for Python packages:
 RUN apt-get update && \
     apt-get install --no-install-recommends --yes \
-    libpq-dev libvips-dev gcc libc6-dev gdal-bin git libgl1 libglx-mesa0 && \
+    libpq-dev libvips-dev gcc g++ libc6-dev gdal-bin libgdal-dev git libgl1 libglx-mesa0 && \
     rm -rf /var/lib/apt/lists/*
 
 ENV PYTHONDONTWRITEBYTECODE=1
 ENV PYTHONUNBUFFERED=1
+# Use system gdal-config instead of Python GDAL's version (which requires osgeo module)
+ENV GDAL_CONFIG=/usr/bin/gdal-config
 
 ARG TASKS
 

docker-compose.override.yml

@@ -3,7 +3,7 @@ services:
     build:
       context: .
       dockerfile: ./dev/Dockerfile
-    command: ["./manage.py", "runserver", "0.0.0.0:8000"]
+    command: ["python", "manage.py", "runserver", "0.0.0.0:8000"]
     # Log printing via Rich is enhanced by a TTY
     tty: true
     env_file: ./dev/.env.docker-compose
@@ -21,6 +21,7 @@ services:
       - rabbitmq
       - minio
 
+  # Default celery worker (CPU-only, runs by default)
   celery:
     build:
       context: .
@@ -49,12 +50,54 @@ services:
       - rabbitmq
       - minio
 
+  # GPU-enabled celery worker for accelerated inferencing
+  # Use with: docker compose --profile gpu up --scale celery=0
+  celery-gpu:
+    build:
+      context: .
+      dockerfile: ./dev/Dockerfile
+      args:
+        TASKS: 1
+    command:
+      [
+        "celery",
+        "--app",
+        "geoinsight.celery",
+        "worker",
+        "--loglevel",
+        "INFO",
+        "--without-heartbeat",
+      ]
+    tty: false
+    environment:
+      - DJANGO_HOMEPAGE_REDIRECT_URL=http://localhost:8080/
+    env_file: ./dev/.env.docker-compose
+    volumes:
+      - .:/opt/geoinsight-server
+    shm_size: 1gb
+    profiles: ["gpu"]  # Only runs with --profile gpu
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+    depends_on:
+      - postgres
+      - rabbitmq
+      - minio
+
   web:
-    image: node:latest
-    command: ["npm", "run", "serve"]
+    image: node:22
+    command: ["sh", "-c", "npm install && npm run serve"]
     working_dir: /web
     volumes:
       - ./web:/web
       - ./.git:/web/.git # allow fetching version tag
+      - web_node_modules:/web/node_modules  # Keep container's node_modules separate from host
     ports:
       - 8080:8080
+
+volumes:
+  web_node_modules:

docker-compose.yml

@@ -1,4 +1,3 @@
-version: "3"
 services:
   postgres:
     image: postgis/postgis:14-3.3
@@ -53,4 +52,4 @@ volumes:
   postgres:
   minio:
   rabbitmq:
-  redis-data:
+  redis-data:

docs/setup.md

@@ -1,36 +1,184 @@
-### Initial Setup
+# Setup Guide
 
-1. Prepare the web client with the following steps:
+This guide walks you through setting up GeoInsight for local development using Docker Compose.
 
-   1. Run `cp web/.env.example web/.env`.
-   2. Install client dependencies by running `cd web && npm i`.
+## Prerequisites
 
-2. Run the docker containers with `docker compose up`. Be sure to check that all containers were able to start and stay running successfully before continuing.
-3. While the containers are up, run the following commands in a separate terminal to prepare the database:
+- [Docker](https://docs.docker.com/get-docker/) (v20.10+)
+- [Docker Compose](https://docs.docker.com/compose/install/) (v2.0+)
+- [Node.js](https://nodejs.org/) (v22+ recommended)
+- [npm](https://www.npmjs.com/)
 
-   a. Run `docker compose run --rm django ./manage.py migrate`.
+---
 
-   b. Run `docker compose run --rm django ./manage.py createsuperuser`
-   and follow the prompts to create your own user.
+## Initial Setup
 
-   c. Run `docker compose run --rm django ./manage.py makeclient` to create a client Application object for authentication.
+### 1. Prepare the Web Client
 
-   d. Run `docker compose run --rm django ./manage.py ingest {JSON file}` to use sample data.
+```bash
+# Copy environment configuration
+cp web/.env.example web/.env
+```
 
-      - The JSON file can either be `multiframe_test.json`, `boston_floods.json`, `la_wildfires.json` or `./new_york_energy/data.json`
+### 2. Build and Start Docker Containers
 
-### Run Application
+```bash
+docker compose build
+docker compose up
+```
 
-1. Run `docker compose up`.
-2. You can access the admin page at port 8000: http://localhost:8000/admin/
-3. The user interface is on port **8080**: http://localhost:8080/
-4. When finished, use `Ctrl+C` to stop the docker compose command.
+> **Note:** Ensure all containers start and stay running before continuing. Check the logs for any errors.
 
-### Application Maintenance
+### 3. Initialize the Database
 
-Occasionally, new package dependencies or schema changes will necessitate
-maintenance. To non-destructively update your development stack at any time:
+While the containers are running, open a **separate terminal** and run:
 
-1. Run `docker compose pull`
-2. Run `docker compose build --pull --no-cache`
-3. Run `docker compose run --rm django ./manage.py migrate`
+```bash
+# Apply database migrations
+docker compose run --rm django python manage.py migrate
+
+# Create an admin user (you will be prompted for email and password)
+docker compose run --rm -it django python manage.py createsuperuser
+
+# Create OAuth client for authentication
+docker compose run --rm django python manage.py makeclient
+```
+
+> **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`:
+> ```bash
+> winpty docker compose run --rm -it django python manage.py createsuperuser
+> ```
+
+### 4. Load Sample Data (Optional)
+
+The ingest command loads datasets, charts, and project configuration from an ingestion file:
+
+```bash
+docker compose run --rm django python manage.py ingest {JSON_FILE}
+```
+
+Available ingest options (paths relative to `sample_data/`):
+- `multiframe_test.json`
+- `boston_floods.json`
+- `la_wildfires.json`
+- `new_york_energy/data.json`
+
+---
+
+## Running the Application
+
+### Start the Services
+
+**Default (CPU-only):**
+```bash
+docker compose up
+```
+
+**With GPU acceleration (NVIDIA systems only):**
+```bash
+docker compose --profile gpu up --scale celery=0
+```
+
+> **Note:** GPU mode requires NVIDIA drivers and [nvidia-docker](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) 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:
+
+```bash
+docker compose stop
+```
+
+---
+
+## Application Maintenance
+
+When new package dependencies or database schema changes occur, update your development environment:
+
+```bash
+# 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 python manage.py migrate
+```
+
+---
+
+## Troubleshooting
+
+### Container Build Failures
+
+If you encounter build errors related to Python packages:
+
+1. **Clear Docker build cache:**
+   ```bash
+   docker compose build --no-cache
+   ```
+
+2. **Prune unused Docker resources:**
+   ```bash
+   docker system prune -a
+   ```
+
+### Database Connection Issues
+
+Ensure PostgreSQL is running and healthy:
+
+```bash
+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:
+```bash
+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`:
+
+```bash
+winpty docker compose run --rm -it django python 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:
+
+```bash
+docker compose run --rm -it django python manage.py <command>
+```
+
+This creates a new container instance rather than attaching to an existing one.

setup.py

@@ -63,7 +63,7 @@
         'pooch[progress]==1.8.2',
         'psycopg[pool]',
         'pyshp==2.3.1',
-        'rasterio==1.3.10',
+        'rasterio==1.3.11',
         'urllib3==1.26.15',
         'webcolors==24.6.0',
         # Production only