pyPASreporter-superset 0.1.0
Lightweight Apache Superset wrapper for DuckDB analytics - part of pyPASreporter ecosystem
License: MIT
Requires Python: >=3.10
Keywords: analytics, cyberark, dashboard, duckdb, pam, superset, visualization

# pyPASreporter-superset

**Lightweight Apache Superset wrapper for DuckDB analytics** - part of the pyPASreporter ecosystem.

[![PyPI version](https://badge.fury.io/py/pyPASreporter-superset.svg)](https://pypi.org/project/pyPASreporter-superset/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

Zero-configuration Apache Superset deployment for analytics dashboards:

- **No PostgreSQL** - Uses SQLite for Superset metadata
- **No Redis** - Uses in-memory caching (SimpleCache)
- **No Celery** - Runs synchronously (perfect for single-user deployments)
- **DuckDB Read-Only** - Safe, fast analytics on your DuckDB databases
- **CLI-driven** - Simple commands to init, run, and manage

Perfect for:
- Local analytics dashboards
- Quick data exploration
- Prototyping before production deployment
- Single-user or small team setups

## Installation

```bash
pip install pyPASreporter-superset
```

Or with UV:

```bash
uv pip install pyPASreporter-superset
```

## Quick Start

### 1. Initialize Superset

```bash
# Initialize with a DuckDB database
superset-runner init --duckdb ./my_data.duckdb

# Or customize the setup
superset-runner init \
    --duckdb ./analytics.duckdb \
    --port 9090 \
    --admin-user myuser \
    --admin-password mypassword \
    --app-name "My Analytics"
```

### 2. Start the Server

```bash
# Start with Gunicorn (production)
superset-runner run

# Or use Flask dev server (development)
superset-runner run --dev --reload
```

### 3. Access Superset

Open http://127.0.0.1:8088 and log in with `admin` / `admin` (or your custom credentials).

## CLI Reference

### `superset-runner init`

Initialize Superset for first use.

```bash
superset-runner init [OPTIONS]

Options:
  -d, --base-dir PATH      Base directory for Superset files [default: .superset]
  -db, --duckdb PATH       Path to DuckDB database file
  -h, --host TEXT          Host to bind to [default: 127.0.0.1]
  -p, --port INTEGER       Port to bind to [default: 8088]
  --admin-user TEXT        Admin username [default: admin]
  --admin-password TEXT    Admin password [default: admin]
  --app-name TEXT          Application name shown in UI
  --skip-migrations        Skip database migrations
  --skip-admin             Skip admin user creation
  --skip-datasource        Skip DuckDB datasource import
```

### `superset-runner run`

Start the Superset web server.

```bash
superset-runner run [OPTIONS]

Options:
  -d, --base-dir PATH   Base directory for Superset files
  -h, --host TEXT       Host to bind to
  -p, --port INTEGER    Port to bind to
  -w, --workers INT     Number of Gunicorn workers [default: 2]
  -t, --threads INT     Threads per worker [default: 4]
  --timeout INT         Worker timeout in seconds [default: 120]
  --reload              Enable auto-reload (development)
  --dev                 Use Flask dev server instead of Gunicorn
```

### `superset-runner status`

Show Superset installation status.

```bash
superset-runner status [OPTIONS]

Options:
  -d, --base-dir PATH   Base directory for Superset files
```

### `superset-runner reset`

Reset Superset installation (delete all data).

```bash
superset-runner reset [OPTIONS]

Options:
  -d, --base-dir PATH   Base directory for Superset files
  -y, --yes             Skip confirmation prompt
```

### `superset-runner add-db`

Add or update a DuckDB database connection.

```bash
superset-runner add-db DUCKDB_PATH [OPTIONS]

Options:
  -d, --base-dir PATH   Base directory for Superset files
  -n, --name TEXT       Database name in Superset [default: duckdb]
```

## Configuration

All configuration is stored in the base directory (default: `.superset/`):

```
.superset/
├── superset_config.py    # Generated Superset configuration
├── superset_home/        # Superset home directory
├── metadata/
│   └── superset.db       # SQLite metadata database
├── logs/
│   ├── access.log        # Gunicorn access logs
│   └── error.log         # Gunicorn error logs
├── cache/                # File-based cache for SQL Lab
├── datasources/
│   └── duckdb.yaml       # DuckDB datasource definition
├── .secret_key           # Flask secret key (auto-generated)
└── .admin_password       # Admin password (if not default)
```

## Architecture

### No Redis Required

Unlike standard Superset deployments, this package uses:
- `SimpleCache` for in-memory caching
- `FileSystemCache` for SQL Lab results
- No async query execution

### No PostgreSQL Required

Superset's metadata (dashboards, charts, users) is stored in SQLite:
- Single-file database
- No external database server needed
- Easy to backup and migrate

### Read-Only DuckDB

The DuckDB connection is configured read-only:
- Safe for analytics workloads
- No accidental data modification
- Optimal for concurrent reads

## Python API

You can also use the package programmatically:

```python
from pathlib import Path
from pypasreporter_superset import SupersetConfig, SupersetBootstrap

# Create configuration
config = SupersetConfig(
    base_dir=Path(".superset"),
    duckdb_path=Path("./data.duckdb"),
    port=8088,
    admin_username="admin",
    admin_password="admin",
)

# Initialize Superset
bootstrap = SupersetBootstrap(config)
bootstrap.initialize()

# Start server (programmatically)
from pypasreporter_superset.server import run_gunicorn
run_gunicorn(config, workers=2)
```

## Requirements

- Python 3.10+
- apache-superset >= 4.0.0
- duckdb-engine >= 0.13.0
- gunicorn >= 21.0.0

## Related Packages

- [pyPASreporter-EVDparser](https://pypi.org/project/pyPASreporter-EVDparser/) - Parse CyberArk EVD exports
- [pyPASreporter-PACLIparser](https://pypi.org/project/pyPASreporter-PACLIparser/) - Parse CyberArk PACLI configs

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions welcome! Please open an issue or PR on [GitHub](https://github.com/itpamltd/pyPASreporter).