Skip to content

Arkiv-Network/usecases-umamidb

BranchesTags
 
 

Repository files navigation

📊 Umami Analytics - Arkiv DB Edition

Privacy-first web analytics with blockchain backup powered by Arkiv DB storage.

✨ Features

  • 🔒 Privacy First: No cookies, no cross-site tracking, GDPR compliant
  • ⚡ Lightweight: 2KB tracking script that won't slow down your website
  • ⛓️ Blockchain Backup: Automatic data sync to Arkiv DB for decentralized storage
  • 🌐 Multi-Website: Track multiple websites from one dashboard
  • 📊 Real-time Analytics: Live dashboard with essential metrics
  • 🚀 Self-hosted: Full control over your data

🛠️ Tech Stack

  • Frontend: Next.js 15, React 18, Tailwind CSS
  • Backend: Node.js, PostgreSQL 15, Prisma ORM
  • Blockchain: Arkiv DB (Kaolin testnet)
  • Infrastructure: Docker Compose, Traefik reverse proxy
  • Analytics: Real-time tracking with session management

🚀 Quick Start

Prerequisites

  • Docker & Docker Compose
  • Traefik reverse proxy (for SSL)

Installation

  1. Clone the repository

    git clone https://github.com/m00npl/umamidb.git
cd umamidb

  2. Configure environment

    cp .env.example .env
# Edit .env with your settings

  3. Start services

    docker compose up -d

  4. Access dashboard

🔧 Configuration

Environment Variables

Create .env file with:

# Umami Configuration
DATABASE_URL=postgresql://umami_user:YOUR_DB_PASSWORD@db:5432/umami
APP_SECRET=YOUR_APP_SECRET

# Umami API Access
UMAMI_URL=https://umami.usecases.arkiv.network
UMAMI_USERNAME=admin
UMAMI_PASSWORD=YOUR_PASSWORD

# PostgreSQL
POSTGRES_DB=umami
POSTGRES_USER=umami_user
POSTGRES_PASSWORD=YOUR_DB_PASSWORD

# Arkiv Configuration
ARKIV_PRIVATE_KEY=0xYOUR_PRIVATE_KEY
ARKIV_CHAIN_ID=60138453025
ARKIV_RPC_URL=https://kaolin.hoodi.arkiv.network/rpc
ARKIV_WS_URL=wss://kaolin.hoodi.arkiv.network/rpc/ws

Adding Websites

Use the automated setup script:

node setup-all-projects.js

Or manually through the dashboard at https://umami.usecases.arkiv.network/dashboard

📈 Adding Tracking to Your Website

Add this script to your website's <head> section:

<script
  async
  src="https://umami.usecases.arkiv.network/script.js"
  data-website-id="YOUR_WEBSITE_ID"
></script>

With Docker Compose

Add to your service in docker-compose.yml:

networks:
  default:
    external: true
    name: traefik-network

Then add Traefik labels for script proxying:

labels:
  - "traefik.http.routers.myapp-script.rule=Host(\`myapp.com\`) && Path(\`/script.js\`)"
  - "traefik.http.routers.myapp-script.service=umami-app@docker"

⛓️ Arkiv DB Integration

Real-time Sync

Data is automatically synced to Arkiv DB blockchain in real-time using a sophisticated queue system:

  • 🚀 Instant Sync: Data synced immediately after being recorded in Umami
  • 📦 Batch Processing: Queue batches up to 10 items or 5-second timeout
  • 🔄 Retry Logic: Exponential backoff with 3 retry attempts (1s → 2s → 4s)
  • 💾 Database Triggers: PostgreSQL triggers for instant notifications
  • ⚡ Performance: Optimized for high throughput with minimal latency

Synced Data Types

  • Pageviews: URL, referrer, timestamp, hostname
  • Events: Custom events with metadata and event names
  • Sessions: User sessions, device info, geolocation
  • Websites: Site metadata and domain information

Data Retention & Storage

  • Database: Indefinite PostgreSQL storage
  • Blockchain: 30 days retention (BTL: ~1,296,000 blocks)
  • Annotations: Smart tagging with type, source, website_id, timestamp
  • Querying: Efficient blockchain queries using annotation filters

Sync Services

Real-time Sync (Default)

# Runs automatically with main services
docker compose up -d

Legacy Manual Sync

# One-time sync for historical data
docker compose --profile sync up arkiv-sync

Monitoring Real-time Sync

# View real-time sync logs
docker compose logs arkiv-realtime-sync -f

# Check sync service status
docker compose ps arkiv-realtime-sync

🔍 API Endpoints

Method Endpoint Description
POST /api/auth/login Authenticate user
GET /api/websites List websites
POST /api/websites Create website
GET /api/websites/:id/stats Get analytics
POST /api/send Receive tracking data
GET /script.js Tracking script

📊 Configured Websites

The following websites are pre-configured:

  • CopyPal (copypal.online)
  • DrawioDB (drawiodb.online)
  • FileDB (filedb.online)
  • ImageDB (imagedb.online)
  • WebDB (webdb.site)

🛡️ Security

  • No Tracking Cookies: Fully cookieless tracking
  • IP Hashing: Anonymized visitor identification
  • GDPR Compliant: No consent banners required
  • Encrypted Backup: Secure blockchain storage
  • Environment Secrets: All credentials in .env

🔧 Development

Running Sync Services

# Install dependencies
bun install

# Run real-time sync
node real-time-sync.js

# Run legacy manual sync
node golem-sync.js sync

# Query blockchain data
node golem-sync.js query

Database Access

docker compose exec db psql -U umami_user -d umami

📁 Project Structure

├── docker-compose.yml      # Main services configuration
├── real-time-sync.js       # Real-time blockchain sync with queue
├── golem-sync.js          # Legacy manual sync script
├── setup-all-projects.js  # Automated website setup
├── public/
│   └── index.html         # Landing page
├── .env                   # Environment configuration
└── README.md             # This file

🤝 Contributing

  1. Fork the repository
  2. Create feature branch
  3. Make changes
  4. Test thoroughly
  5. Submit pull request

📜 License

MIT License - see LICENSE file for details

🔗 Links

Built with ❤️ for the decentralized web

About

Privacy-first web analytics with Arkiv backup

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • JavaScript 76.8%
  • HTML 23.2%