{"id":28088978,"url":"https://github.com/cheesebanana/yellowstack","last_synced_at":"2025-06-12T19:36:37.305Z","repository":{"id":292898636,"uuid":"981858242","full_name":"cheesebanana/yellowstack","owner":"cheesebanana","description":"Real-time Python script runner with scheduling, logging, and OpenAI-assisted debugging","archived":false,"fork":false,"pushed_at":"2025-05-12T17:43:31.000Z","size":537,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-12T18:37:58.770Z","etag":null,"topics":["automation","aws","devops","flask","job-scheduler","openai","python","rest-api","scheduler","scripts","sre"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cheesebanana.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-12T02:24:00.000Z","updated_at":"2025-05-12T17:49:03.000Z","dependencies_parsed_at":"2025-05-12T18:40:51.540Z","dependency_job_id":"77d3d774-dd32-46f4-980b-68540b7c6e70","html_url":"https://github.com/cheesebanana/yellowstack","commit_stats":null,"previous_names":["cheesebanana/yellowstack"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheesebanana%2Fyellowstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheesebanana%2Fyellowstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheesebanana%2Fyellowstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cheesebanana%2Fyellowstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cheesebanana","download_url":"https://codeload.github.com/cheesebanana/yellowstack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253947846,"owners_count":21988945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","aws","devops","flask","job-scheduler","openai","python","rest-api","scheduler","scripts","sre"],"created_at":"2025-05-13T12:52:54.923Z","updated_at":"2025-05-13T12:52:55.461Z","avatar_url":"https://github.com/cheesebanana.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# YellowStack – Real-Time Script Execution for Humans\n\n![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)\n![Flask](https://img.shields.io/badge/flask-3.1-green)\n\n\u003e Tired of juggling cron jobs, broken scripts, SSH sessions, and scattered logs?  \n\u003e YellowStack helps you run, schedule, and monitor Python scripts like a pro — in real time, with a modern UI and a dash of AI.\n\nYellowStack is a Python-based platform built for DevOps, SREs, and infrastructure-minded developers who need more than `nohup` and hope.  \nIt makes automation **visible**, **trackable**, and — dare we say — kinda enjoyable.\n\n🔧 Execute and schedule Python scripts  \n📊 Track outputs and errors in real time  \n🧠 Let OpenAI explain what broke (and how to fix it)  \n☁️ Manage AWS credentials for automation  \n🔐 Secure by default with CSRF, login, and role control\n\nWhether you're scripting AWS, scraping data, or automating chaos — YellowStack is the tool that meets you halfway between bash and bliss.\n\n## 🚀 Features\n\n- **Script Management**\n  - Register Python scripts with parameters\n  - Execute scripts manually or on schedule\n  - View execution history with detailed outputs\n  - Interactive script support with real-time output\n  - Script execution cancellation\n\n- **Scheduling**\n  - Daily schedules (specific time of day)\n  - Interval schedules (every 1, 2, 3, 4, 6, 8, 12, or 24 hours)\n  - Enable/disable schedules on-demand\n  - Persistent scheduling across application restarts\n\n- **AWS Integration**\n  - Manage AWS profiles (access key, secret key, region)\n  - Select profiles when executing AWS-related scripts\n  - Override AWS regions for specific executions\n  - Sample AWS scripts (EC2 tags, S3 buckets, security groups)\n\n- **User Management**\n  - User authentication with username/password\n  - Secure password handling with hashing\n  - Admin user role with special privileges\n  - User creation, deletion, and role management\n\n- **Real-time Monitoring**\n  - WebSocket-based real-time script output\n  - Dashboard with execution history\n  - Execution statistics and charts\n  - Status tracking for all executions\n\n- **AI-Assisted Error Analysis**\n  - OpenAI integration for script error analysis\n  - Intelligent suggestions for error resolution\n  - Configurable AI assistance (can be enabled/disabled)\n  - Uses OpenAI GPT-3.5 model by default\n  - Requires your own OpenAI API key (generated at OpenAI website)\n\n- **RESTful API**\n  - Complete API for all platform operations\n  - CSRF protection for enhanced security\n  - Authentication required for API access\n\n\n## 🖼️ Preview\n\n### 🔧 Dashboard\n![Dashboard Screenshot](docs/images/dashboard.png)\n\n### 🧾 AWS Profiles\n![AWS Profiles](docs/images/aws_profiles.png)\n\n### 🗂️ Scripts Management\n![Scripts Management](docs/images/scripts_management.png)\n\n### ➕ Script Registration\n![Script Registration](docs/images/script_registration.png)\n\n### 📜 Execution History\n![Execution History](docs/images/execution_history.png)\n\n\n## 📋 Requirements\n\n- Python 3.9 or newer\n- SQLite (for data storage)\n- Optional: AWS credentials for AWS-related functionality\n- Optional: OpenAI API key for AI-assisted error analysis (generate your own at OpenAI website)\n- Dependencies listed in `requirements.txt`\n\n### Python Version Note\n\n- If you're using Python 3.9, you'll need to update urllib3 in requirements.txt to version 1.26.x\n- For best compatibility and performance, Python 3.10+ is recommended, with Python 3.12+ being optimal\n\n## 📂 Project Structure\n\n```text\n├── app/                           # Core application package\n│   ├── auth/                      # Login/auth decorators\n│   ├── models/                    # ORM models (users, scripts, executions, etc.)\n│   ├── routes/                    # API and Web UI endpoints\n│   │   ├── *_api.py               # REST API routes\n│   │   └── views.py               # Web views\n│   ├── services/                  # Core business logic\n│   │   ├── *_service.py           # High-level services\n│   │   └── *_adapter.py           # Low-level data adapters\n│   └── utils/                     # Helper modules\n│       ├── ai_helper.py           # OpenAI integration\n│       ├── db.py                  # SQLite session helpers\n│       └── timezone_config.py     # Timezone conversions\n├── instance/                      # Instance-specific config (e.g. secrets)\n├── scripts/                       # Executable AWS-related scripts\n│   ├── ec2tags.py\n│   └── ...                        # Other automation scripts\n├── static/                        # Static frontend assets\n│   ├── css/\n│   ├── js/\n│   └── favicon.ico\n├── templates/                     # Jinja2 HTML templates\n│   ├── layout.html\n│   ├── login.html\n│   └── ...\n├── tests/                         # Pytest test suite\n│   ├── test_csrf_protection.py\n│   └── ...\n├── app.py                         # Main Flask entry point\n├── wsgi.py                        # WSGI-compatible entry\n└── yellowstack.db                 # Local SQLite database (dev only)\n```\n\n## ⚙️ Setup and Installation\n\n```bash\n# Clone the repository to your preferred directory\n# Replace /path/to/your/directory with your preferred installation location\ncd /path/to/your/directory\ngit clone https://github.com/cheesebanana/yellowstack.git\n\n# Set owner permissions (replace username:group with your username and group)\nsudo chown username:group /path/to/your/directory/yellowstack\ncd yellowstack\n\n# Make the setup script executable\nchmod +x setup.sh\n\n# Run the setup script\n./setup.sh\n\n# Create directory for logs (used by the app)\nsudo mkdir -p /var/log/yellowstack\nsudo chown username:group /var/log/yellowstack  # Replace username:group with your values\n\n# Activate virtual environment\nsource venv/bin/activate\n\n# Verify dependencies\npython3 verify_packages.py\n\n# Run the application\npython3 app.py\n```\n\n### Example Installation (with specific values)\n\n```bash\n# Using /data directory and user 'mike'\ncd /data\ngit clone https://github.com/cheesebanana/yellowstack.git\n\n# Set owner permissions\nsudo chown mike:mike /data/yellowstack\ncd yellowstack\n\n# Make the setup script executable\nchmod +x setup.sh\n\n# Run the setup script\n./setup.sh\n\n# Create directory for logs (used by the app)\nsudo mkdir -p /var/log/yellowstack\nsudo chown mike:mike /var/log/yellowstack\n\n# Activate virtual environment\nsource venv/bin/activate\n\n# Verify dependencies\npython3 verify_packages.py\n\n# Run the application\npython3 app.py\n```\n\nAlternatively, for manual setup without the setup script:\n\n```bash\n# Clone the repository\ncd /path/to/your/directory\ngit clone https://github.com/cheesebanana/yellowstack.git\ncd yellowstack\n\n# Create directory for logs (used by the app)\nsudo mkdir -p /var/log/yellowstack\nsudo chown mike:mike /var/log/yellowstack\n\n# Set up virtual environment\npython3 -m venv venv\nsource venv/bin/activate\n\n# Install dependencies\npip install -r requirements.txt\n```\n\nOnce the server is running, you can access it at:\n\n- http://localhost:5000 (from the same machine)\n- http://\u003cyour_ip_address\u003e:5000 (from another device on the same network)\n\n## 🔐 Default Login\n\nTo access the admin dashboard after starting the server, use the default credentials:\n\n- **Username:** `admin`  \n- **Password:** `admin`\n\n\u003e ⚠️ It is strongly recommended to change the default password in production environments.\n\n## 🖥️ Usage\n\n### AWS Integration\n\n1. Add AWS profiles through the settings page\n2. Select profiles when executing AWS-related scripts\n3. Override AWS regions as needed for specific executions\n\n### Script Registration\n\n1. Place your Python scripts in the `scripts/` directory\n2. Register scripts via the web interface (recommended) or API\n3. Define parameters for your scripts as needed\n\n### Execution\n\n- Run scripts manually from the web interface\n- Set up schedules for automated execution\n- Monitor execution status and output in real-time\n\n## 🧪 Testing\n\nThe project includes comprehensive tests:\n\n```bash\n# Run all tests\ncd /path/to/your/directory\nsource venv/bin/activate\npython3 -m pytest tests -v\n\n# Run specific test categories\npython3 -m pytest tests/test_csrf_api_protection.py -v\n\n```\n\n## 🛡️ Security\n\nYellowStack implements several security features:\n\n- CSRF protection on all form submissions and API endpoints\n- Secure password handling with hashing and salting\n- Protection against common web vulnerabilities\n\n## 🔄 API Access\n\nYellowStack provides a comprehensive RESTful API for internal automation, integrations, and advanced users who want full control over script execution workflows.\n\nThe API allows you to:\n\n- Manage scripts and their parameters\n- Trigger executions and view real-time output\n- Schedule recurring jobs\n- Handle user access and roles\n- Configure AWS credentials and settings\n- Analyze failures using OpenAI (if enabled)\n\n### 🔐 Authentication\n\nAll API endpoints require authentication via a valid user session. CSRF protection is enforced for all state-changing operations.\nBreaking changes, if introduced, will be reflected in the release changelog.\n\n\u003e ⚠️ **API Stability Notice**  \n\u003e This API is considered *internal-first*. While it is fully functional, we do not currently guarantee long-term backward compatibility.  \n\u003e Use in production systems at your own discretion.\n\n### 📚 API Endpoint Groups\n\n- `GET /api/scripts` — Script management  \n- `POST /api/run_script` — Trigger script execution  \n- `GET /api/execution_history` — View execution logs and stats  \n- `POST /api/cancel_execution/\u003cid\u003e` — Cancel a running script  \n- `GET /api/users` — User management  \n- `GET /api/aws_profiles` — Manage AWS credentials  \n- `GET /api/settings` — System configuration\n\n## 🤖 AI Involvement\n\nThis project was primarily developed with the assistance of AI tools — approximately **90%** of the codebase was generated or significantly shaped using large language models, including Claude (Anthropic) and ChatGPT (OpenAI).\n\nAI tools were used to assist with:\n- Writing core services, API routes, models, and decorators  \n- Generating test coverage for unit, integration, and edge cases  \n- Structuring reusable utilities and database logic  \n- Creating setup scripts and configuration scaffolding  \n- Drafting and refining documentation (including this README)\n\nHuman responsibilities focused on:\n- Designing the overall system architecture and project structure  \n- Reviewing and validating all AI-generated code  \n- Customizing logic for project-specific needs  \n- Configuring infrastructure, testing, and deployment flows  \n- Performing final QA, debugging, and reality-checking\n\nThis collaboration showcases how modern AI can accelerate development without compromising quality — when paired with thoughtful architectural design and careful human oversight.\n\n## 🧪 Test Scripts\n\nThe following files in `/scripts/` are used for internal testing and are required for the test suite to run correctly:\n\n- `error_test.py` – Simulates errors and outputs to `stderr`\n- `test_params.py` – Accepts arguments and simulates parameterized runs\n\nThese are not meant for production use, but should be kept in place unless you're modifying the test suite.\n\n## 📄 License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n---\n\n📬 Contact: hello@cheesebanana.com  \nMaintained by [@msnesar](https://github.com/msnesar)\n\nBuilt to save developers from running scripts manually at 2 AM.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheesebanana%2Fyellowstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcheesebanana%2Fyellowstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcheesebanana%2Fyellowstack/lists"}