Features

Everything included, nothing to implement

Deploy one JAR, get a fully operational notification backend with auth, persistence, delivery tracking, and a built-in admin panel.

⚙

REST API

Send notifications to users, topics, or broadcast — via POST /api/notifications/*. Secure with JWT or API key. No SDK required on the caller side.

📦

PostgreSQL Persistence

Notifications for offline users are stored in queued_notifications and flushed on reconnect. Topic subscriptions and audit logs survive restarts.

🔒

JWT + API Key Auth

Admin access via short-lived JWTs with rotating refresh tokens. Machine-to-machine via X-API-Key. End-users authenticate WebSocket connections with per-user tokens.

⚡

Real-time WebSocket Delivery

Online users receive notifications instantly. ACK-based delivery tracking with automatic retries. Heartbeat ping/pong keeps connections alive and stale ones are cleaned up.

🖥

Admin GUI

Built-in admin panel at /admin.html — no extra deployment. Full Vue 3 dashboard available separately with user management, topic management, API key admin, and a live WebSocket test client.

📋

Swagger UI + Audit Log

Interactive API explorer at /swagger-ui/index.html. Every notification send, ACK, and retry failure is recorded in the notification_audit table.

Quick Start

Running in under 5 minutes

Choose the setup method that works for you — the install script handles everything automatically, or bring your own Docker Compose.

Run the install script

One command pulls and starts PostgreSQL, the NotiFlow app, and the admin dashboard — no manual configuration required.

bash

curl -fsSL https://app.notiflow.pl/install | bash

Configure first admin

Open the admin dashboard at http://localhost:3080. On first launch you'll be prompted to set a password for the admin account.

Admin dashboard first-run setup screen — Set your admin password — this runs once and cannot be repeated without a database reset.

Register a user and create an API key

In the dashboard, create a user to get their WebSocket token (nfu_…), then generate an API key (nf_…) for any backend service that will send notifications.

Open Users tab

Go to the Users section in the sidebar.

Fill in user details

Enter the external ID (must match the ID in your system) and a display name, then confirm.

Copy the WebSocket token

The nfu_… token is shown once — pass it to your frontend to authenticate the WebSocket connection.

Create API Key

Open API Keys

Go to the API Keys section in the sidebar.

Name the key

Give the key a descriptive name (e.g. order-service) so you can identify it later.

Copy the API key

The nf_… key is shown once — use it in the X-API-Key header when sending notifications.

Test delivery with the built-in WebSocket client

Use the dashboard's live WebSocket test client to connect as a user, send a notification, and confirm delivery end-to-end — no code required.

Admin dashboard live WebSocket test client — Paste the user token, connect, then send a notification and watch it arrive in real time.

Start PostgreSQL and the app

Use this docker-compose.yaml to start PostgreSQL and NotiFlow. The admin dashboard can be added separately.

docker-compose.yaml

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: notiflow
      POSTGRES_USER: notiflow_user
      POSTGRES_PASSWORD: changeme
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - notiflow-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U notiflow_user -d notiflow"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

  app:
    image: dpustula/notiflow-app:latest
    ports:
      - "8080:8080"
    environment:
      DB_URL: jdbc:postgresql://postgres:5432/notiflow
      DB_USERNAME: notiflow_user
      DB_PASSWORD: changeme
      JWT_SECRET: your-secret-key-here
      CORS_ORIGINS: http://localhost:3000
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - notiflow-net
    restart: unless-stopped
    read_only: true
    tmpfs:
      - /tmp
    security_opt:
      - no-new-privileges:true

networks:
  notiflow-net:
    driver: bridge

volumes:
  postgres-data:

Configure first admin

On first boot, set the admin password, then obtain a JWT for authenticated API calls.

curl

# One-time setup
curl -X POST http://localhost:8080/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"password":"changeme"}'

# Login — save the accessToken from the response
curl -c cookies.txt -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"changeme"}'

Register a user and create an API key

Registering a user returns a token (nfu_…) — pass it to the WebSocket connection so the frontend can receive notifications. API keys (nf_…) are for external services that send notifications through the REST API.

curl

# Register user — extract WebSocket token (nfu_…) for the frontend
WS_TOKEN=$(curl -s -X POST http://localhost:8080/api/users \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"externalId":"user-42","name":"Alice"}' | jq -r '.token')

# Create API key — extract key (nf_…) for external services
API_KEY=$(curl -s -X POST http://localhost:8080/api/admin/api-keys \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{"name":"order-service"}' | jq -r '.rawKey')

Connect via WebSocket and send a notification

The user connects with their token. Your backend sends a notification via the API.

client.js + curl

// Frontend uses WS_TOKEN from step 3 (delivered by your backend to the client)
const ws = new WebSocket(`ws://localhost:8080/ws/notifications?token=${wsToken}`);
ws.onmessage = (e) => {
  const { type, id, payload } = JSON.parse(e.data);
  if (type === 'NOTIFICATION') {
    console.log(payload.title, payload.message);
    ws.send(JSON.stringify({ type: 'ACK', payload: { notificationId: id } }));
  }
};

# Backend sends notification using API_KEY from step 3
curl -X POST http://localhost:8080/api/notifications/user/user-42 \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Order shipped","message":"On its way!","priority":"HIGH"}'

NotiFlow App

Everything included, nothing to implement

REST API

PostgreSQL Persistence

JWT + API Key Auth

Real-time WebSocket Delivery

Admin GUI

Swagger UI + Audit Log

From REST call to WebSocket delivery

Running in under 5 minutes

Run the install script

Configure first admin

Register a user and create an API key

Test delivery with the built-in WebSocket client

Start PostgreSQL and the app

Configure first admin

Register a user and create an API key

Connect via WebSocket and send a notification

Ready to deploy?