Skip to main content

​
Quickstart Guide

Get your predictive maintenance system up and running with Docker in minutes.

​
Prerequisites

Before you begin, ensure you have the following installed:

Docker

Docker 24.x or later

Docker Compose

Included with Docker Desktop

Git

For cloning the repository

InfluxDB Cloud Account

Free tier available at influxdata.com
The system requires InfluxDB Cloud for time-series data persistence. You can use the free tier for development and testing.

​
Installation

1

Clone the Repository

Clone the project from GitHub:
git clone https://github.com/BhaveshBytess/PREDICTIVE-MAINTENANCE.git
cd PREDICTIVE-MAINTENANCE
2

Configure Environment Variables

Create a .env file in the backend/ directory with your InfluxDB credentials:
backend/.env
ENVIRONMENT=local
PORT=8000
INFLUX_URL=https://us-east-1-1.aws.cloud2.influxdata.com
INFLUX_TOKEN=<your-influxdb-token>
INFLUX_ORG=<your-org-id>
INFLUX_BUCKET=sensor_data
Replace <your-influxdb-token> and <your-org-id> with your actual InfluxDB Cloud credentials.
Get your InfluxDB credentials:
  1. Sign up at influxdata.com
  2. Create a new bucket named sensor_data
  3. Generate an API token with read/write permissions
  4. Copy your Organization ID from the settings
3

Start All Services

Launch the backend and frontend using Docker Compose:
docker-compose up --build
The --build flag ensures Docker builds fresh images. Subsequent starts can omit this flag for faster startup.
You should see output indicating both services are starting:
[+] Running 2/2
✔ Container pm_backend   Started
✔ Container pm_frontend  Started
4

Verify Services are Running

Check that all services are healthy:
docker-compose ps
Expected output:
NAME            STATUS          PORTS
pm_backend      Up (healthy)    0.0.0.0:8000->8000/tcp
pm_frontend     Up              0.0.0.0:5173->80/tcp
5

Access the Application

Open your browser and navigate to:

Frontend Dashboard

http://localhost:5173

Backend API

http://localhost:8000

API Documentation

http://localhost:8000/docs

Health Check

http://localhost:8000/health

​
Verify the Installation

1

Test the Health Endpoint

Verify the backend is connected to InfluxDB:
curl http://localhost:8000/health
Expected response:
{
  "status": "healthy",
  "db_connected": true
}
If db_connected is false, check your InfluxDB credentials in the .env file.
2

Calibrate the Baseline Model

Before detecting anomalies, the system needs to learn what “healthy” looks like. Use the calibration endpoint:
curl -X POST http://localhost:8000/system/calibrate \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "Motor-01",
    "duration_seconds": 60,
    "sampling_rate_hz": 100
  }'
This generates 60 seconds of healthy baseline data and trains both ML models.
The system will automatically generate synthetic sensor data matching real-world industrial patterns.
3

View the Dashboard

Open the dashboard at http://localhost:5173 and verify:
  • STATUS: LIVE badge is green
  • Real-time charts are updating
  • Health score shows 100 (LOW risk)
  • Baseline target values are displayed
4

Test Fault Injection

Simulate a fault to verify the anomaly detection pipeline:
curl -X POST http://localhost:8000/system/inject-fault \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "Motor-01",
    "fault_type": "SPIKE",
    "severity": "MEDIUM",
    "duration_seconds": 30
  }'
Within seconds, you should see:
  • Health score decreasing
  • Risk level changing to HIGH or CRITICAL
  • Red dashed anomaly markers on the charts
  • Explanations appearing in the Insight Panel

​
Local Development (Manual Setup)

If you prefer to run services individually without Docker: 
cd backend
python -m venv venv

# Windows
.\venv\Scripts\activate

# Linux/Mac
source venv/bin/activate

pip install -r requirements.txt
uvicorn backend.api.main:app --reload
The backend will be available at http://localhost:8000.

​
Common Issues

Cause: Invalid InfluxDB credentials or network connectivity issue.Solution:
  1. Verify your InfluxDB token and organization ID
  2. Check that the bucket sensor_data exists
  3. Test connectivity: curl https://us-east-1-1.aws.cloud2.influxdata.com/health
  4. Ensure your token has read/write permissions
Cause: Backend is not running or CORS configuration issue.Solution:
  1. Verify backend is running: curl http://localhost:8000/ping
  2. Check Docker logs: docker-compose logs backend
  3. Ensure port 8000 is not blocked by firewall
Cause: Line endings or path issues.Solution:
  1. Configure Git to use LF line endings: git config core.autocrlf false
  2. Re-clone the repository
  3. Run Docker Desktop as Administrator
Cause: System not calibrated or insufficient baseline data.Solution:
  1. Run calibration: POST /system/calibrate with at least 60 seconds duration
  2. Verify baseline targets appear on status cards in the dashboard
  3. Check model training logs: docker-compose logs backend | grep "Model trained"

​
Next Steps

Explore the Architecture

Learn how the ML pipeline processes sensor data

API Reference

Integrate real sensors using the REST API

Production Deployment

Deploy to Render (backend) and Vercel (frontend)

Testing Guide

Run the 182-test suite and benchmark models

​
Stop the Services

To stop all running containers: 
docker-compose down
To stop and remove all data volumes: 
docker-compose down -v

Build docs developers (and LLMs) love

Get started for freeTalk to us