https://github.com/anqorithm/ntfy-mq
Simple notification microservice that uses ntfy.sh to send notifications through RabbitMQ and Celery.
https://github.com/anqorithm/ntfy-mq
asynchronous celery microservice notifications ntfy push-notifications rabbitmq
Last synced: 3 months ago
JSON representation
Simple notification microservice that uses ntfy.sh to send notifications through RabbitMQ and Celery.
- Host: GitHub
- URL: https://github.com/anqorithm/ntfy-mq
- Owner: anqorithm
- License: mit
- Created: 2025-02-05T09:24:54.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2025-02-11T08:02:01.000Z (3 months ago)
- Last Synced: 2025-02-15T18:53:43.009Z (3 months ago)
- Topics: asynchronous, celery, microservice, notifications, ntfy, push-notifications, rabbitmq
- Language: HTML
- Homepage:
- Size: 120 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Ntfy MQ
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://fastapi.tiangolo.com)
[](https://github.com/psf/black)
[](https://www.docker.com/)
Simple notification microservice that uses ntfy.sh to send notifications through RabbitMQ and Celery.
## Tech Stack
- **Python**: Core programming language
- **FastAPI**: High-performance web framework for building APIs
- **RabbitMQ**: Message broker for handling notification queue
- **Celery**: Distributed task queue for processing notifications
- **Poetry**: Dependency management and packaging
- **ntfy.sh**: Push notification service
- **Docker**: Containerization
## Architecture
```mermaid
graph LR
Client([Client]) --> API[FastAPI Service]
API --> RMQ[(RabbitMQ)]
RMQ --> W1[Worker 1]
RMQ --> W2[Worker 2]
RMQ --> W3[Worker 3]
RMQ --> W4[Worker 4]
W1 --> N[ntfy.sh]
W2 --> N
W3 --> N
W4 --> N
N --> D[Device]
```
## Features
- Asynchronous notification processing
- Scalable architecture using message queues
- RESTful API endpoints for sending notifications
- Easy integration with existing systems
- Support for multiple notification types
- Docker support for easy deployment
## Getting Started
### Prerequisites
- Docker and Docker Compose
- Poetry (for local development)
### Using Docker
1. Clone the repository:
```bash
git clone https://github.com/anqorithm/ntfy-mq.git
cd ntfy-mq
```
2. Build and run with Docker Compose (development):
```bash
docker-compose -f docker-compose.dev.yml up --build
```
3. Build and run with Docker Compose (production):
```bash
docker-compose -f docker-compose.prod.yml up --build
```
### Local Development
1. Install dependencies:
```bash
poetry install
```
2. Configure environment variables:
```bash
cp .env.example .env
# Edit .env with your configuration
```
3. Start RabbitMQ server
4. Start Celery worker:
```bash
poetry run celery -A app.worker worker --loglevel=info --concurrency=4
```
5. Start FastAPI server:
```bash
poetry run fastapi dev notification_service/main.py
```
## API Endpoints
### Send Notification
- **POST** `/api/v1/notify`
- Creates a new notification
- Request body:
```json
{
"title": "string",
"message": "string",
"priority": 1 // Priority level from 1-5
"topic": "string" // Topic to send the notification to
}
```
#### Priority Levels
| Priority Level | Value | Description | Behavior |
|---------------|-------|-------------|-----------|
| Max/Urgent | 5 | Highest priority notifications | Really long vibration bursts, default notification sound with pop-over |
| High | 4 | Important notifications | Long vibration burst, default notification sound with pop-over |
| Default | 3 | Standard notifications | Short default vibration and sound, default notification behavior |
| Low | 2 | Non-urgent notifications | No vibration or sound, only visible when notification drawer is pulled down |
| Min | 1 | Minimal priority | No vibration or sound, shown under "Other notifications" |
### Check Task Status
- **GET** `/api/v1/tasks/{task_id}`
- Returns the status of a notification task
### Health Check
- **GET** `/health`
- Returns service health status
- Example response:
```json
{
"service": "Ntfy MQ Service",
"description": "Ntfy MQ is a modern async notification service using ntfy.sh through RabbitMQ and Celery",
"status": "healthy",
"version": "1.0.0",
"timestamp": "2025-02-05T09:30:23.962722Z",
"environment": "development"
}
```
### Root Endpoint
- **GET** `/`
- Returns service information and available endpoints
- Example response:
```json
{
"name": "Notification Service",
"description": "Modern async notification service using ntfy.sh",
"version": "1.0.0",
"endpoints": {
"root": "/",
"health": "/health",
"docs": "/docs",
"redoc": "/redoc",
"openapi": "/openapi.json",
"api_v1": "/api/v1"
},
"timestamp": "2025-02-05T09:30:33.522773Z"
}
```
## Documentation
API documentation is available at:
- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Contributors
- [Abdullah Alqahtani](https://github.com/anqorithm)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## References
- [ntfy.sh](https://ntfy.sh)
- [RabbitMQ](https://www.rabbitmq.com)
- [Celery](https://docs.celeryq.dev)
- [FastAPI](https://fastapi.tiangolo.com)