Flood Forecast REST API Deployment Guide

Overview

This API provides flood forecasting capabilities for various sites in multiple countries. It uses historical rainfall data and machine learning models to predict flood risks based on current precipitation patterns.

Prerequisites

• Docker installed on your system
• AWS CLI configured with appropriate permissions
• Access to the ECR repository containing the API image
• Store the dataset in an s3 bucket on your AWS account

Deployment

1. Pull the Docker Image from AWS ECR

# Authenticate Docker with AWS ECR
aws ecr get-login-password --region eu-west-1 | docker login --username AWS --password-stdin 237710157910.dkr.ecr.eu-west-1.amazonaws.com

# Pull the image
docker pull 237710157910.dkr.ecr.eu-west-1.amazonaws.com/nestler/flood-forecast-api:latest

2. Environment Variables Configuration

Create a .env file with the following variables:

# S3 Configuration
S3_BUCKET=your-s3-bucket-name
S3_DATASET_PREFIX=dataset/gold
AWS_REGION=your-aws-region

# Optional AWS credentials (only needed if not using IAM roles)
# AWS_ACCESS_KEY_ID=your-access-key
# AWS_SECRET_ACCESS_KEY=your-secret-key

3. Run the Container

docker run -d \
  --name flood-forecast-api \
  -p 8000:8000 \
  --env-file .env \
  <your-account-id>.dkr.ecr.<your-region>.amazonaws.com/flood-forecast-api:latest

4. Verify Deployment

Check the health endpoint:

curl http://localhost:8000/health

API Endpoints

1. Root Endpoint

• GET /
• Returns a welcome message

2. Site List

• GET /site-list
• Returns a list of all available sites with their coordinates and rainy seasons

3. Historical Rain Data

• GET /dataset/flood
• Parameters:
  • country (string): Country name (e.g., "cameroon")
  • sitename (string): Site name (e.g., "garoua")
• Returns historical rain data for the specified site

4. Flood Forecast

• POST /forecast/flood
• Request Body:

  {
    "country": "string",
    "sitename": "string",
    "period": "string",
    "thres": 0.5
  }

• Returns flood forecast with model metrics

5. Health Check

• GET /health
• Returns service health status

Usage Examples

Get Site List

curl http://localhost:8000/site-list

Get Historical Data

curl "http://localhost:8000/dataset/flood?country=cameroon&sitename=garoua"

Get Flood Forecast

curl -X POST "http://localhost:8000/forecast/flood" \
  -H "Content-Type: application/json" \
  -d '{"country": "cameroon", "sitename": "douala", "period": "JUL-SEP", "thres": 0.5}'

Deployment Options

AWS ECS/Fargate

1. Create a task definition referencing your ECR image
2. Configure the environment variables in the task definition
3. Deploy as a service or run as a task

Troubleshooting

1. S3 Access Issues:

   • Verify IAM permissions or AWS credentials
   • Check the S3 bucket name and region

2. Dataset Not Loading:

   • Check the S3_DATASET_PREFIX matches your S3 folder structure
   • Verify the health endpoint for dataset status

3. CORS Issues:

   • Ensure ALLOWED_ORIGINS includes your frontend domains
   • Separate multiple domains with commas (no spaces)

Monitoring

The API includes a health endpoint (/health) that reports:

• Service status
• S3 connectivity
• Dataset availability

License

[Specify your license here]