Script Manager

A web application for managing large collections of script files. Index, search, tag, and organize your Python, PowerShell, Bash, SQL, and other script files across multiple directories.

Features

• First-Time Installation Wizard: Guided onboarding for new administrators with three modes
• Script Indexing: Recursively scan and index scripts from multiple folder roots
• Metadata Management: Add notes, tags, status, and classifications to scripts
• Fast Search: Search by filename, path, content, tags, and metadata
• Full-Text Search (FTS): Porter-stemmed full-text search across script content and notes
• Lifecycle Tracking: Manage script status (draft, active, deprecated, archived)
• Duplicate Detection: Find identical scripts across different locations
• Similarity Detection: Discover similar scripts using content-based analysis
• Bulk Operations: Apply changes to multiple scripts at once
• Audit Trail: Track changes to metadata and script status
• Attachments: Upload and attach files to scripts or notes
• Saved Searches: Pin and reuse frequently used search queries
• Watch Mode: Automatically detect filesystem changes in real time
• Heartbeat Monitors: Track external cron jobs and services with fail-safe alerts
• Built-in Scheduler: Runs cron jobs in-process, with retries, overlap prevention, timeouts and full log capture
• Notifications: Real delivery via Slack, Discord, email (SMTP), generic webhook, PagerDuty or Twilio SMS
• Incident Management: Failures raise incidents automatically and resolve on recovery
• Authentication & RBAC: JWT auth enforced on every endpoint, with admin, editor and viewer roles
• Dark Mode & Responsive UI: Follows your system theme, works on phones and tablets

Installation Wizard

When you open Script Manager for the first time, you are greeted by the Installation Wizard — a guided onboarding experience that gets you up and running in seconds.

Wizard Modes

Mode	Description
🎮 Demo	One-click start with pre-loaded sample scripts, tags, and a demo folder root. No configuration needed — perfect for evaluation.
🚀 Production	Full setup flow: choose your database, configure the connection, and create a secure administrator account.
🛠️ Development	Streamlined setup for contributors and developers. Uses SQLite with sensible defaults, skipping unnecessary steps.

Wizard Steps (Production / Development)

1. Welcome — Select your desired mode
2. Database Configuration — Choose and configure your database backend:
   • SQLite (default, recommended for single-server deployments)
   • MySQL / MariaDB — provide host, port, database name, and credentials
   • PostgreSQL — provide host, port, database name, and credentials
   • Use the built-in Test Connection button to validate before proceeding
3. Admin Account — Create the first administrator account (username, email, password)
4. Done — Confirmation screen with an "Enter Script Manager" button

Note: MySQL and PostgreSQL support requires installing the corresponding driver package (aiomysql for MySQL, asyncpg for PostgreSQL) and restarting the backend after setup. SQLite works out-of-the-box with no additional dependencies.

Setup API

The wizard is powered by a dedicated REST API:

Endpoint	Method	Description
/api/setup/status	GET	Returns { setup_completed, mode } — used by the frontend on every load
/api/setup/demo	POST	Activates demo mode and seeds sample data
/api/setup/complete	POST	Completes setup with database + admin configuration
/api/setup/test-db	POST	Tests a database connection without persisting anything

Screenshots

Welcome Screen — Mode Selection

Database Configuration

Admin Account Creation

Setup Complete

Screenshots

Dashboard

Folder Roots

Scripts

Tags

Advanced Search

Monitors

Schedules

Notifications

Supported Script Types

• Python (.py)
• PowerShell (.ps1, .psm1)
• Bash (.sh)
• Batch (.bat, .cmd)
• SQL (.sql)
• JavaScript (.js)
• YAML (.yml, .yaml)
• JSON (.json)
• Terraform (.tf)

Heartbeat Monitors

Heartbeat Monitors track external cron jobs, backup scripts, or any scheduled process by waiting for periodic ping calls. If a ping doesn't arrive within the expected interval plus the grace period, the monitor transitions to failing and an Incident is created automatically.

How it works

1. Create a monitor. Its ping URL is shown once on creation, and can be fetched again from GET /api/monitors/{id}/ping-url or the monitor's detail dialog.
2. Add a curl call to the end of your cron job: curl -fsS -m 10 --retry 3 -o /dev/null https://your-host/api/monitors/ping/<ping_key>
3. A background task evaluates every monitor on a timer, so an incident is raised and the configured channels are alerted whether or not anyone has the UI open. A monitor that never receives its first ping is measured from its creation time.

The ping endpoint is deliberately unauthenticated: the random ping key is the credential, so a cron job needs nothing but the URL. For that reason the key is kept out of monitor listings.

Monitor API

Endpoint	Method	Description
/api/monitors/	GET	List all monitors
/api/monitors/	POST	Create a monitor
/api/monitors/{id}	GET / PUT / DELETE	Read, update, or delete a monitor
/api/monitors/{id}/pause	POST	Pause alerting for a monitor
/api/monitors/{id}/resume	POST	Resume alerting for a monitor
/api/monitors/ping/{ping_key}	POST	Record a heartbeat ping
/api/monitors/{id}/pings	GET	List recent ping history
/api/monitors/{id}/incidents	GET	List incidents for a monitor
/api/monitors/{id}/ping-url	GET	Reveal the monitor's ping key

Schedule Jobs

Schedule Jobs let you define cron-scheduled tasks that run shell commands or indexed scripts. The backend runs them itself: a background scheduler wakes on a timer, fires jobs whose next_run_at has passed and records the result. No external cron is required.

Execution history is captured (stdout, stderr, exit code, duration) and performance metrics are available for trend analysis.

Note: a job runs an arbitrary shell command with the backend's own privileges. Creating, editing and running jobs each require an explicit permission, and only administrators hold them by default.

Features

• Cron expression scheduling with timezone support, validated on write
• A live preview of the next few run times while you are editing the schedule
• Overlap prevention (a job won't start a second instance while still running)
• Auto-retry on failure (configurable retries and delay)
• Timeout enforcement, which kills the whole process group rather than just the shell
• Full stdout/stderr capture per execution
• Failure raises an incident and alerts the job's notification channels
• Executions stranded by a backend restart are reaped on the next start

Schedule API

Endpoint	Method	Description
/api/schedules/	GET	List all scheduled jobs
/api/schedules/	POST	Create a scheduled job
/api/schedules/{id}	GET / PUT / DELETE	Read, update, or delete a job
/api/schedules/{id}/enable	POST	Enable a disabled job
/api/schedules/{id}/disable	POST	Disable a job
/api/schedules/{id}/trigger	POST	Manually trigger a job immediately
/api/schedules/{id}/executions	GET	List execution history
/api/schedules/{id}/metrics	GET	Performance metrics for a job
/api/schedules/preview/cron	GET	Validate an expression and preview its next runs

Notifications

Notification Channels deliver alerts when monitors fail, schedule jobs error, or incidents are created.

Supported Channel Types

Type	Description
slack	Post messages to a Slack channel via an Incoming Webhook (webhook_url)
discord	Send messages to a Discord channel via webhooks
email	SMTP email (smtp_host, smtp_port, to, optional smtp_user/smtp_pass)
webhook	HTTP POST to any generic webhook URL
pagerduty	Create PagerDuty incidents via Events API v2
sms	SMS via Twilio (account_sid, auth_token, from, to)

Notifications API

Endpoint	Method	Description
/api/notifications/channels/	GET / POST	List or create channels
/api/notifications/channels/{id}	GET / PUT / DELETE	Read, update, or delete a channel
/api/notifications/channels/types	GET	Describe each channel type's config fields
/api/notifications/channels/{id}/test	POST	Send a real test message and report the result
/api/notifications/incidents/stats	GET	Incident counts by status and severity
/api/notifications/incidents/	GET	List all incidents
/api/notifications/incidents/{id}	GET / PUT / DELETE	Read, update, or delete an incident

A channel's configuration is validated when it is saved, so a channel that could never deliver is rejected rather than failing silently at alert time. "Send test" performs a real delivery and reports the provider's response.

Security note: secret config keys (webhook_url, token, auth_token, routing_key, smtp_pass, ...) are never returned by the API; they appear as ***. Submitting *** back on an update keeps the stored value, so editing a channel's name cannot wipe its credentials.

Authentication & RBAC

Script Manager uses JWT Bearer tokens for authentication and role-based access control for authorization. Every API endpoint is gated except the setup wizard, the login and auth-config endpoints, /health, and the monitor ping endpoint (whose secret key is its own credential).

Set REQUIRE_AUTH=false to open the API for a local single-user setup; it is on by default.

Signing key

SECRET_KEY signs access tokens. Leave it unset and the backend generates a random key on first start and persists it beside the database. Set it explicitly whenever you run more than one backend process, since all workers must agree.

Accounts

The setup wizard creates the first administrator. After that, administrators create accounts from the Team page. Anonymous self-registration is off unless ALLOW_SELF_REGISTRATION=true. The last remaining administrator cannot be deleted, deactivated or demoted, so an installation cannot be locked out.

Default Roles

Role	Permissions
admin	Full access — manage users, roles, and every resource
editor	Create, update and delete scripts, tags, notes, searches, folder roots, monitors and schedules
viewer	Read-only access across the application

Permissions are named <resource>.<action>, and <resource>.* or superuser act as wildcards. The UI hides whatever the signed-in account cannot reach, so a viewer is never shown a button the API would refuse.

Auth API

Endpoint	Method	Description
/api/auth/login	POST	Log in and receive an access token (form data)
/api/auth/me	GET	Get the current authenticated user
/api/auth/register	POST	Register a new user (admin only)
/api/auth/change-password	PUT	Change the current user's password (JSON body)
/api/auth/config	GET	Public: whether auth is enforced and self-registration is on
/api/auth/users	GET	List all users (admin only)
/api/auth/roles	GET	List all roles

Quick Start

Using Makefile (Recommended for Development)

The project includes a comprehensive Makefile for common tasks:

# View all available commands
make help

# Install all dependencies
make install

# Run tests
make test

# Build for production
make build

# Start with Docker
make docker-up

See Makefile Documentation for complete command reference.

Docker Setup (Recommended for Production)

Prerequisites

• Docker and Docker Compose installed

Quick Start with Docker

# Clone the repository
git clone https://github.com/jomardyan/Script-Manager
cd Script-Manager

# Start the application
./docker.sh up
# or on Windows
docker.bat up

The application will be available at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

On first launch you will be redirected to the Installation Wizard automatically.

Stop the Application

./docker.sh down
# or on Windows
docker.bat down

Helper Commands

Use the convenient helper scripts for common tasks:

# View logs
./docker.sh logs -f

# Check health
./docker.sh health

# Access backend shell
./docker.sh shell-backend

# Production setup with Nginx
./docker.sh prod

# See all commands
./docker.sh help

Windows users: Replace ./docker.sh with docker.bat

See Docker Quick Reference for more commands.

Docker Configuration

Mounting Script Directories

To scan scripts from your host machine, edit docker-compose.yml and modify the backend service volumes:

volumes:
  - script_data:/app/data
  - /path/to/your/scripts:/scripts:ro

Then in the UI, create a folder root with path /scripts.

Environment Variables

Copy .env.example to .env and customize:

cp .env.example .env

Available variables:

• API_PORT: Backend API port (default: 8000)
• DATABASE_PATH: SQLite database location (default: /app/data/scripts.db)
• VITE_API_URL: Frontend API URL (default: http://localhost:8000)

Production Deployment with Nginx

For a production-like setup with Nginx reverse proxy:

./docker.sh prod
# or on Windows
docker.bat prod

Then access the application at http://localhost (port 80).

See Docker Deployment Guide for detailed configuration and troubleshooting.

Traditional Setup

Easy Start (Recommended)

On Linux/Mac:

./start.sh

On Windows:

start.bat

This will automatically:

1. Install dependencies if needed
2. Start both backend and frontend
3. Open the application in your browser
4. Redirect you to the Installation Wizard on first run

Manual Start

Prerequisites

• Python 3.8 or higher
• Node.js 16 or higher
• npm or yarn

Backend Setup

cd backend
pip install -r requirements.txt
python main.py

The API will be available at http://localhost:8000

Frontend Setup

cd frontend
npm install
npm run dev

The web interface will be available at http://localhost:3000

Architecture

• Backend: Python with FastAPI
• Database: SQLite (default) — MySQL and PostgreSQL configurable via setup wizard
• Frontend: React with modern UI components
• API: RESTful API with JSON responses
• Containerization: Docker and Docker Compose for easy deployment

Docker Architecture

When running with Docker Compose, the following services are orchestrated:

┌─────────────────────────────────────────────┐
│         Docker Compose Network              │
│                                             │
│  ┌──────────────┐      ┌──────────────┐     │
│  │  Frontend    │      │  Backend     │     │
│  │  React       │◄────►│  FastAPI     │     │
│  │  Port 3000   │      │  Port 8000   │     │
│  └──────────────┘      └──────────────┘     │
│         ▲                      ▲            │
│         │                      │            │
│         └──────┬───────────────┘            │
│                │                            │
│         ┌──────▼────────┐                   │
│         │  Volume       │                   │
│         │  script_data  │                   │
│         │  (Database)   │                   │
│         └───────────────┘                   │
│                                             │
└─────────────────────────────────────────────┘

Services

• backend: FastAPI application with Python
• frontend: React application (built with Vite)
• script_data volume: Persistent storage for SQLite database
• Optional nginx: Reverse proxy for production deployments

Configuration

Configuration is read from environment variables. .env.example at the repository root documents every option; the ones you are most likely to set are:

Variable	Default	Purpose
DATABASE_PATH	./data/scripts.db	SQLite database file
API_PORT	8000	Backend listen port
SECRET_KEY	generated	JWT signing key. Required when running more than one backend process
REQUIRE_AUTH	true	Enforce authentication and RBAC on the API
ALLOW_SELF_REGISTRATION	false	Let anonymous visitors create accounts
ACCESS_TOKEN_EXPIRE_MINUTES	1440	Access-token lifetime
ALLOWED_ORIGINS	localhost:3000,localhost:5173	CORS origins, when the UI is on another origin
ENABLE_SCHEDULER	true	Run due jobs and evaluate monitors in this process
SCHEDULER_TICK_SECONDS	30	How often the scheduler wakes up
ATTACHMENTS_DIR	./data/attachments	Where uploaded attachments are stored
MAX_ATTACHMENT_SIZE	10485760	Per-file upload limit, in bytes
LOG_LEVEL / LOG_FORMAT	INFO / text	Logging verbosity and format (json for aggregation)

Run the scheduler in exactly one process. If you scale the backend horizontally, set ENABLE_SCHEDULER=false on every replica but one, or jobs will run more than once per schedule.

API Reference

The full interactive API documentation is available at http://localhost:8000/docs when the backend is running.

Core Endpoints

Prefix	Description
/api/setup	Installation wizard
/api/auth	Authentication and user management
/api/folder-roots	Manage script folder roots
/api/scripts	Script CRUD and metadata
/api/tags	Tag management
/api/notes	Script notes (markdown supported)
/api/search	Advanced script search
/api/fts	Full-text search
/api/saved-searches	Save and pin search queries
/api/attachments	Upload and retrieve file attachments
/api/similarity	Find similar scripts
/api/watch	Real-time filesystem watch mode
/api/monitors	Heartbeat monitor management
/api/schedules	Scheduled job management
/api/folders	Folder tree and per-folder notes
/api/notifications	Notification channels and incidents

Every endpoint requires a bearer token and the matching permission, except /api/setup/*, /api/auth/login, /api/auth/config, /health, and POST /api/monitors/ping/{ping_key}.

Interactive API documentation is served at /docs (OpenAPI) once the backend is running.

Documentation

• Makefile Commands - Complete command reference for development
• Production Deployment Guide - Production-ready deployment best practices
• Docker Deployment Guide - Complete Docker setup and troubleshooting
• Docker Quick Reference - Quick command reference
• API Documentation
• User Guide
• Development Guide

License

MIT License - see LICENSE file for details