Deploying openSenseMap (OSEM)

Introduction

openSenseMap (OSEM) is an open citizen science platform designed for collecting, storing, and visualizing environmental sensor data. Developed by the senseBox project at the University of Muenster, OSEM enables individuals, schools, and organizations to contribute environmental measurements from sensors around the world, creating a collaborative map of air quality, temperature, humidity, and other environmental parameters.

The platform consists of a Node.js-based API backend, a MongoDB database for storing sensor data, and a React-based web frontend. OSEM supports various sensor devices including the senseBox hardware, Arduino-based setups, and any device capable of sending HTTP requests.

Key highlights of openSenseMap:

• Citizen Science Platform: Enable communities to collect and share environmental data
• Real-Time Data Ingestion: Accept sensor measurements via REST API or MQTT
• Interactive Map Visualization: Display sensor stations and measurements on an interactive map
• Open Data: All collected data is freely available through the API
• Multi-Sensor Support: Track multiple environmental parameters per station
• Historical Data: Store and analyze time-series data for trend analysis
• Device Agnostic: Connect any sensor device capable of HTTP requests
• Educational Focus: Designed for use in schools and educational programs
• RESTful API: Comprehensive API for data submission and retrieval

This guide walks through deploying openSenseMap on Klutch.sh using Docker, configuring the platform for environmental data collection, and setting up sensor integration.

Why Deploy OSEM on Klutch.sh

Deploying openSenseMap on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds OSEM without complex orchestration. Push to GitHub, and your sensor platform deploys automatically.

Persistent Storage: Attach persistent volumes for MongoDB data, ensuring sensor measurements survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure API access and data transmission from sensors.

GitHub Integration: Connect your configuration repository directly from GitHub for easy updates and version control.

Scalable Resources: Allocate CPU and memory based on the number of connected sensors and data volume.

Environment Variable Management: Securely store database credentials and API keys through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain for your citizen science platform.

Always-On Availability: Your sensor data platform remains accessible 24/7 for continuous data collection.

Prerequisites

Before deploying OSEM on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your OSEM configuration
• Basic familiarity with Docker and containerization concepts
• Understanding of REST APIs and sensor integration
• (Optional) Environmental sensors to connect
• (Optional) A custom domain for your platform

Understanding OSEM Architecture

openSenseMap uses a modern JavaScript stack:

API Server: Node.js Express application handling data ingestion, user management, and data retrieval. The API supports both REST and MQTT protocols.

MongoDB Database: Stores sensor boxes (stations), sensors, measurements, and user accounts. Time-series data is optimized for efficient storage and retrieval.

Web Frontend: React-based single-page application providing the map interface, data visualization, and user management.

Box Management: Each “senseBox” represents a sensor station with multiple sensors. Users register boxes and receive API keys for data submission.

Preparing Your Repository

To deploy OSEM on Klutch.sh, create a GitHub repository with your Dockerfile and configuration.

Repository Structure

osem-deploy/
├── Dockerfile
├── README.md
├── .dockerignore
└── config/
    └── config.json

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM node:18-alpine

# Install dependencies
RUN apk add --no-cache git python3 make g++

# Clone openSenseMap API
WORKDIR /app
RUN git clone https://github.com/sensebox/openSenseMap-API.git .

# Install Node.js dependencies
RUN npm ci --production

# Set environment variables
ENV NODE_ENV=production
ENV PORT=8080
ENV OSEM_DBHOST=${OSEM_DBHOST:-mongodb}
ENV OSEM_DBPORT=${OSEM_DBPORT:-27017}
ENV OSEM_DBNAME=${OSEM_DBNAME:-osem}
ENV JWT_SECRET=${JWT_SECRET}

# Expose API port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/stats || exit 1

CMD ["node", "app.js"]

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
node_modules
test

Environment Variables Reference

Variable	Required	Default	Description
OSEM_DBHOST	Yes	mongodb	MongoDB hostname
OSEM_DBPORT	No	27017	MongoDB port
OSEM_DBNAME	No	osem	Database name
JWT_SECRET	Yes	-	Secret for JWT token generation
OSEM_MAILER_URL	No	-	SMTP URL for email notifications
OSEM_FRONTEND_URL	No	-	Frontend URL for email links

Deploying OSEM on Klutch.sh

Generate Your JWT Secret

Before deployment, generate a secure secret for JWT tokens:

openssl rand -base64 64

Save this secret securely for the environment variables configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial OSEM deployment configuration"
git remote add origin https://github.com/yourusername/osem-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “osem” or “sensor-platform”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your OSEM Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8080

Set Environment Variables

In the environment variables section, add:

Variable	Value
OSEM_DBHOST	Your MongoDB hostname
OSEM_DBNAME	osem
JWT_SECRET	Your generated secret
OSEM_FRONTEND_URL	https://your-app-name.klutch.sh

Attach Persistent Volumes

For MongoDB data persistence, deploy MongoDB separately or use a managed database service.

Mount Path	Recommended Size	Purpose
/data/uploads	5 GB	Uploaded files and images

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build and deploy your OSEM API instance.

Access the API

Once deployment completes, access your API at https://your-app-name.klutch.sh. The API documentation is available at /docs.

Initial Setup and Configuration

Creating Your First senseBox

Register a sensor station through the API:

1. Create a user account via the API
2. Register a new senseBox with sensor definitions
3. Note the API key provided for data submission

Submitting Sensor Data

Send measurements to your OSEM instance:

POST /boxes/{boxId}/{sensorId}
Content-Type: application/json

{
  "value": 23.5
}

Or submit multiple measurements:

POST /boxes/{boxId}/data
Content-Type: application/json

[
  {"sensor": "sensorId1", "value": 23.5},
  {"sensor": "sensorId2", "value": 65}
]

Configuring Sensors

OSEM supports various sensor types:

• Temperature (Celsius, Fahrenheit)
• Humidity (%)
• Air Pressure (hPa)
• PM2.5, PM10 (particulate matter)
• UV Index
• Light intensity (lux)
• Custom sensor types

Troubleshooting Common Issues

Database Connection Errors

• Verify MongoDB hostname and credentials
• Check network connectivity to database
• Ensure database is accessible from Klutch.sh

Sensor Data Not Appearing

• Verify senseBox API key
• Check request format and sensor IDs
• Review API response for errors

Authentication Issues

• Verify JWT_SECRET is set correctly
• Check token expiration settings
• Ensure consistent secret across restarts

Additional Resources

• Official openSenseMap Website
• openSenseMap Documentation
• openSenseMap API GitHub
• senseBox Project
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying openSenseMap on Klutch.sh provides a robust platform for citizen science environmental monitoring. The combination of OSEM’s data collection capabilities and Klutch.sh’s deployment simplicity enables communities, schools, and organizations to easily set up environmental sensor networks.

Whether you’re running a local air quality monitoring project or coordinating a regional environmental study, OSEM on Klutch.sh offers the infrastructure needed to collect, store, and share valuable environmental data.