HarborMaster

🌊 Introduction

Welcome to HarborMaster, your ultimate solution for managing conversational AI-driven workflows in the maritime domain.
This containerized chatbot combines Rasa, Telegram, Ngrok, Docker, Redis and FastAPI to deliver real-time port-monitoring and decision-support features.
Designed for developers and port-operations teams alike, HarborMaster streamlines:

• Automating vessel-related queries
• Caching and performance optimization
• Secure webhook tunneling
• Modular deployment across environments

---

📑 Table of Contents

1. What is Rasa?
2. Telegram Integration
3. Ngrok
4. Docker & Docker Compose
5. Features
6. Quick Start
7. Monitoring & APIs
8. Contributors
9. License

---

📚 What is Rasa?

Rasa is an open-source machine learning framework for building conversational AI. With powerful tools for intent recognition, dialogue management, and natural language understanding, Rasa lets you build robust chatbots that understand and respond intelligently.

🔗 Learn more at Rasa's Official Website.

---

📱 Telegram Integration

Telegram is a widely-used messaging app known for its speed and simplicity. HarborMaster integrates with Telegram to deliver chatbots that can engage users directly on this popular platform. With a Telegram bot token, you can easily connect and deploy your bot.

🔗 Telegram Bot API Documentation

---

🌍 Ngrok

Ngrok is a tunneling tool that exposes your local server to the internet securely. It's essential for testing Telegram webhooks and ensuring your chatbot is reachable from anywhere in the world during development.

🔗 Learn more about Ngrok.

---

🐳 Docker and Docker Compose

Docker is a platform for building, shipping, and running applications inside containers. Docker Compose is a tool for defining and running multi-container Docker applications. HarborMaster uses Docker and Docker Compose to simplify setup and deployment, ensuring consistency across environments.

🔗 Docker Documentation

🔗 Docker Compose Documentation

---

🚀 Features

• Weather Forecast
  Get current or next-day weather for any city (via OpenWeather).
  

• Vessel Count Prediction
  Predict number of vessels in Ancona or Venice for today/tomorrow.
  

• List Ships in Area
  Query MMSI list by date, time, lat/lon.
  

• Last Known Position
  Retrieve the latest GPS fix of any vessel (MMSI).
  

• Full Position History
  Fetch and visualize historical track with GeoJSON link.
  

• Interactive Stop/Restart
  Gracefully quit, reask or restart any form.
  

• Greeting & Fallback
  Friendly welcomes & robust fallback messages.
  

• Live Weather Interaction
  Emoji-rich prompts & buttons on Telegram.
  

---

🚀 Quick Start

1. Set Up the Environment File

# Telegram Bot credentials (from BotFather)
TELEGRAM_BOT_TOKEN=<your_token>
TELEGRAM_BOT_USERNAME="<your_botname>"

# Ngrok credentials
NGROK_AUTHTOKEN=<your_token>
NGROK_PORT=4040

# OpenWeather
OPENWEATHER_API_KEY=<your_API_key>
OPENWEATHER_MAX_CALLS_PER_MINUTE=4

# Inference Model (FastAPI)
INFERENCE_API_BASE_URL="http://fastapi_inference_api:8000"
INFERENCE_API_PORT=8000
INFERENCE_MAX_CALLS_PER_MINUTE=10

# Rasa
RASA_PORT=5005
RASA_TO_TRAIN=true
RASA_TO_STORY_GRAPH=true
RASA_TO_TEST=false
RASA_TO_TEST_E2E=false

ACTION_SERVER_PORT=5055

# Redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=0

# Tracker Store
TRACKER_STORE_TYPE=redis
TRACKER_STORE_URL=redis://redis:6379
TRACKER_STORE_QUEUE_LIMIT=100
TRACKER_STORE_INDEX=0

Create a Telegram Bot

1. Open Telegram and search for BotFather.
2. Start a conversation and use the /newbot command to create a new bot.
3. Follow the instructions to name your bot and get your bot token.
4. Copy the bot token and bot username into the .env file under TELEGRAM_BOT_TOKEN and TELEGRAM_BOT_USERNAME.

Set Up Ngrok

1. Visit Ngrok's website and create an account.
2. Obtain your authtoken from the Ngrok dashboard.
3. Add the authtoken to the .env file under NGROK_AUTHTOKEN.
4. Add the Domain to the .env file under NGROK_WEBHOOK_URL=https://some-thinglike-that.ngrok-free.app.

Set Up OpenWeather

1. Visit OpenWeather's website and create an account.
2. Obtain your api_key from the dashboard.
3. Add the api_key to the .env file under OPENWEATHER_API_KEY.

---

2. Set Up Docker Compose 🐳

1. Build and launch the Docker containers:

   docker compose --env-file .env build --no-cache
   docker-compose up --build -d

⚠️ Note:
You might encounter connection issues between Ngrok and your service because Rasa starts training immediately after the container builds. I suggest monitoring the logs and waiting for confirmation that the server is active before initiating a dialog with the bot on Telegram.

3. Monitor Requests 🌐

Once all Docker containers are up and running, you can view the requests made by Telegram and Rasa through Ngrok's interface.

🔗 Open your browser and navigate to: http://localhost:4040/inspect/http You can inspect all incoming HTTP requests and responses in real-time! 🚀

4. Monitor Redis cache 🌐

🔗 Open your browser and navigate to: http://localhost:8081/ You can inspect all record in redis using redis-commander! 🚀

5. API inference service 🌐

🔗 Open your browser and navigate to: http://localhost:8000/docs You can inspect all path of the API inference service! 🚀

---

👥 Contributors

• Andrea Fiorani
• Micol Zazzarini
• Antonio Antonini

---

🛡️ License

This project is licensed under the MIT License.
See LICENSE for details.