diff --git a/dev/Dockerfile b/dev/Dockerfile index c06f6ef3..a15b5e89 100644 --- a/dev/Dockerfile +++ b/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 diff --git a/docker-compose.override.yml b/docker-compose.override.yml index 66404aa1..40f46387 100644 --- a/docker-compose.override.yml +++ b/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: diff --git a/docker-compose.yml b/docker-compose.yml index eded1e56..24ef1ce9 100644 --- a/docker-compose.yml +++ b/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: \ No newline at end of file diff --git a/docs/setup.md b/docs/setup.md index 4e5c90a4..0c3afdc9 100644 --- a/docs/setup.md +++ b/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 +``` + +This creates a new container instance rather than attaching to an existing one. diff --git a/setup.py b/setup.py index fba2b72d..0dbb81b0 100644 --- a/setup.py +++ b/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