A privacy-focused page hit counter with analytics dashboard

Kamifusen is a simple yet powerful page hit counter written in Kotlin using the Quarkus framework. It tracks page visits by hashing user agent information to ensure unique visit counting while maintaining user privacy. Features include API key management, analytics dashboard, and session tracking.

• Java 17+
• PostgreSQL 15+
• Node.js 22+ (for UI development)

1. Clone the repository

   git clone https://github.com/thwbh/kamifusen.git
   cd kamifusen

2. Set up PostgreSQL database

   # Create database and user
   createdb dev
   psql -d dev -c "CREATE USER kamifusen WITH PASSWORD 'kamifusen';"
   psql -d dev -c "GRANT ALL PRIVILEGES ON DATABASE dev TO kamifusen;"

3. Configure environment (optional)

   The application uses sensible defaults for development. You can override any configuration by setting environment variables or modifying application.properties:

   # Database (defaults shown)
   export QUARKUS_DATASOURCE_USERNAME=kamifusen
   export QUARKUS_DATASOURCE_PASSWORD=kamifusen
   export QUARKUS_DATASOURCE_REACTIVE_URL=postgresql://localhost:5432/dev
   
   # Auth (required for production)
   export QUARKUS_HTTP_AUTH_SESSION_ENCRYPTION_KEY=your-32-char-encryption-key
   
   # CORS (optional)
   export QUARKUS_HTTP_CORS=true
   export QUARKUS_HTTP_CORS_ORIGINS=http://localhost:3000,https://yourdomain.com

4. Run in development mode

   ./gradlew quarkusDev

   This starts:

   • Backend server on http://localhost:8080
   • React dev server on http://localhost:3000 (proxy to backend)
   • Database migration (creates tables automatically)
   • Live reload for both backend and frontend

5. First login

   • Navigate to http://localhost:8080
   • Login with username: admin, password: admin
   • You'll be prompted to change the password on first login

Required environment variables for production:

# Database (both reactive and JDBC for Flyway migrations)
QUARKUS_DATASOURCE_USERNAME=your_db_user
QUARKUS_DATASOURCE_PASSWORD=your_db_password
QUARKUS_DATASOURCE_REACTIVE_URL=postgresql://your_host:5432/your_db
QUARKUS_DATASOURCE_JDBC_URL=jdbc:postgresql://your_host:5432/your_db

# Security
QUARKUS_HTTP_AUTH_SESSION_ENCRYPTION_KEY=your-32-character-encryption-key

# CORS (if serving from different domains)
QUARKUS_HTTP_CORS=true
QUARKUS_HTTP_CORS_ORIGINS=https://yourdomain.com

1. Access the admin interface at your server URL
2. Navigate to "User Management"
3. Click "CREATE KEY" in the API Keys section
4. Copy the generated key (shown only once)

Add this JavaScript to your pages:

<script>
document.addEventListener('DOMContentLoaded', function () {
    const url = new URL(window.location.href);

    fetch('https://your-server.com/public/visits/hit', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Basic YOUR_API_KEY_HERE'
        },
        body: JSON.stringify({
            path: url.pathname,
            domain: url.hostname
        })
    });
});
</script>

curl -H "Authorization: Basic YOUR_API_KEY" \
     "https://your-server.com/public/visits/count/{pageId}"

Replace {pageId} with the UUID of the page you want to get visit counts for. Page IDs are available through the admin interface or by tracking the response from the hit endpoint.

./gradlew build
java -jar build/quarkus-app/quarkus-run.jar

# Build native binary (requires Docker/Podman for cross-compilation)
./gradlew build -Dquarkus.native.enabled=true -Dquarkus.native.container-build=true -Dquarkus.package.jar.enabled=false -Dquarkus.native.container-runtime=podman -Dquarkus.native.native-image-xmx=6g -Dquarkus.application.version=VERSION_NUMBER

docker build -f src/main/docker/Dockerfile.jvm -t kamifusen:jvm .
docker run -p 8080:8080 kamifusen:jvm

• Backend: Kotlin + Quarkus + PostgreSQL
• Frontend: React + TypeScript + crt-dojo
• Build: Gradle + Quinoa (integrates npm builds)
• Database: Flyway migrations
• Auth: Form-based authentication with secure sessions
• Deployment: Docker + GraalVM native compilation support

cd src/main/webui
npm run dev  # Separate dev server

./gradlew regenerateClient  # Updates TypeScript API client

./gradlew test              # Backend tests
cd src/main/webui && npm test  # Frontend tests

• Quarkus Framework
• Database Schema
• API Documentation