{"id":29049306,"url":"https://github.com/prabalesh/puppet","last_synced_at":"2025-08-20T22:23:45.888Z","repository":{"id":300031456,"uuid":"989433216","full_name":"prabalesh/puppet","owner":"prabalesh","description":"Puppet is a scalable and extensible code execution engine written in Go. It allows secure execution of code in multiple programming languages using Docker containers. Designed for online judges, coding platforms, and educational tools.","archived":false,"fork":false,"pushed_at":"2025-06-19T13:48:42.000Z","size":80,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-19T14:46:57.198Z","etag":null,"topics":["code-execution","docker","go","golang","language-runner","online-compiler","postgresql"],"latest_commit_sha":null,"homepage":"","language":"Go","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/prabalesh.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-24T04:56:13.000Z","updated_at":"2025-06-19T13:48:46.000Z","dependencies_parsed_at":"2025-06-19T14:47:02.539Z","dependency_job_id":"64d151c3-ff69-47d8-b057-b26564b5349e","html_url":"https://github.com/prabalesh/puppet","commit_stats":null,"previous_names":["prabalesh/puppet"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/prabalesh/puppet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prabalesh%2Fpuppet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prabalesh%2Fpuppet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prabalesh%2Fpuppet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prabalesh%2Fpuppet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prabalesh","download_url":"https://codeload.github.com/prabalesh/puppet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prabalesh%2Fpuppet/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262128872,"owners_count":23263350,"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":["code-execution","docker","go","golang","language-runner","online-compiler","postgresql"],"created_at":"2025-06-26T19:08:13.850Z","updated_at":"2025-06-26T19:08:14.556Z","avatar_url":"https://github.com/prabalesh.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧩 Puppet – Code Execution and Language Management API\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n  \r\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\r\n[![Go Version](https://img.shields.io/badge/go-1.22+-00ADD8.svg)](https://golang.org)\r\n[![React](https://img.shields.io/badge/react-18+-61DAFB.svg)](https://reactjs.org)\r\n[![Docker](https://img.shields.io/badge/docker-20+-2496ED.svg)](https://docker.com)\r\n\r\n*A powerful full-stack application for managing programming languages and executing code in isolated Docker environments*\r\n\r\n\u003c/div\u003e\r\n\r\n---\r\n\r\n## ✨ Overview\r\n\r\nPuppet is a comprehensive code execution platform that provides:\r\n\r\n🔧 **Language Management** – Add, remove, and manage programming languages with Docker environments  \r\n💻 **Code Execution** – Run code snippets safely in isolated Docker containers  \r\n📥 **Stdin Support** – Execute code with custom input streams  \r\n🌐 **RESTful API** – Clean Go-based backend with comprehensive endpoints  \r\n⚛️ **Modern Frontend** – Intuitive React interface built with Vite  \r\n\r\n---\r\n\r\n## 🚀 Tech Stack\r\n\r\n\u003ctable align=\"center\"\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e\u003cstrong\u003eLayer\u003c/strong\u003e\u003c/td\u003e\r\n    \u003ctd\u003e\u003cstrong\u003eTechnology\u003c/strong\u003e\u003c/td\u003e\r\n    \u003ctd\u003e\u003cstrong\u003ePurpose\u003c/strong\u003e\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e🔙 Backend\u003c/td\u003e\r\n    \u003ctd\u003eGo (net/http)\u003c/td\u003e\r\n    \u003ctd\u003eAPI server \u0026 business logic\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e🎨 Frontend\u003c/td\u003e\r\n    \u003ctd\u003eReact + Vite\u003c/td\u003e\r\n    \u003ctd\u003eUser interface \u0026 interactions\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e🐳 Container\u003c/td\u003e\r\n    \u003ctd\u003eDocker\u003c/td\u003e\r\n    \u003ctd\u003eCode execution isolation\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e🗄️ Database\u003c/td\u003e\r\n    \u003ctd\u003ePostgreSQL\u003c/td\u003e\r\n    \u003ctd\u003eData persistence\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e🚀 Deployment\u003c/td\u003e\r\n    \u003ctd\u003eDocker Compose\u003c/td\u003e\r\n    \u003ctd\u003eInfrastructure orchestration\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n\u003c/table\u003e\r\n\r\n---\r\n\r\n## 📁 Project Structure\r\n\r\n```\r\npuppet/\r\n├── 🚀 cmd/puppet-api/             # Main entry point for the Go API\r\n├── 🔧 internal/                   # Backend application logic\r\n│   ├── 📡 handler/                # HTTP request handlers\r\n│   ├── 🔨 service/                # Business logic layer\r\n│   ├── 📊 repository/             # Database abstraction layer\r\n│   ├── 📋 model/                  # Data models \u0026 entities\r\n│   ├── 📦 dto/                    # Data Transfer Objects\r\n│   ├── 🧩 module/                 # Dependency injection\r\n│   └── ⚙️  config/, db/, logging/ # Configuration \u0026 infrastructure\r\n├── 🌐 web-install/                # React frontend application\r\n└── 🐳 docker-compose.yml          # PostgreSQL container setup\r\n```\r\n\r\n---\r\n\r\n## 🌟 Features\r\n\r\n### 🔄 Language Management\r\n- ➕ **Add Languages** – Register new programming languages\r\n- 📋 **List Languages** – View all available languages\r\n- 🗑️ **Remove Languages** – Clean up unused languages\r\n- 📦 **Docker Management** – Install/uninstall language environments\r\n\r\n### 💻 Code Execution\r\n- 🏃‍♂️ **Safe Execution** – Run code in isolated Docker containers\r\n- 📥 **Stdin Support** – Provide custom input to programs\r\n- ⚡ **Fast Response** – Optimized execution pipeline\r\n- 🛡️ **Security** – Sandboxed environment for code execution\r\n\r\n### 🖥️ User Interface\r\n- 🎨 **Modern Design** – Clean, intuitive React interface\r\n- 📱 **Responsive** – Works seamlessly across devices\r\n- 🔄 **Real-time** – Live code execution and results\r\n- 🎯 **User-friendly** – Simple workflow for all skill levels\r\n\r\n---\r\n\r\n## ⚙️ Quick Start\r\n\r\n### Prerequisites\r\n\r\nMake sure you have the following installed:\r\n- 🐳 [Docker](https://docker.com) \u0026 Docker Compose\r\n- 🐹 [Go 1.22+](https://golang.org)\r\n- 📦 [Node.js 16+](https://nodejs.org) \u0026 npm\r\n\r\n### 🚀 Backend Setup\r\n\r\n1. **Start PostgreSQL Database**\r\n   ```bash\r\n   docker-compose up -d\r\n   ```\r\n\r\n2. **Configure Database Connection**\r\n   \r\n   Ensure your `DB_URL` points to the running PostgreSQL container:\r\n   ```\r\n   postgres://user:password@localhost:5432/puppet\r\n   ```\r\n\r\n3. **Launch API Server**\r\n   ```bash\r\n   go run ./cmd/puppet-api\r\n   ```\r\n   \r\n   The API will be available at `http://localhost:8080` 🎉\r\n\r\n### 🎨 Frontend Setup\r\n\r\n1. **Navigate to Frontend Directory**\r\n   ```bash\r\n   cd web-install\r\n   ```\r\n\r\n2. **Install Dependencies**\r\n   ```bash\r\n   npm install\r\n   ```\r\n\r\n3. **Start Development Server**\r\n   ```bash\r\n   npm run dev\r\n   ```\r\n   \r\n   The frontend will be available at `http://localhost:5173` ✨\r\n\r\n---\r\n\r\n## 📡 API Reference\r\n\r\n### 🔧 Language Management\r\n\r\n\u003ctable\u003e\r\n  \u003ctr\u003e\r\n    \u003cth\u003eMethod\u003c/th\u003e\r\n    \u003cth\u003eEndpoint\u003c/th\u003e\r\n    \u003cth\u003eDescription\u003c/th\u003e\r\n  \u003c/tr\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e\u003ccode\u003eGET\u003c/code\u003e\u003c/td\u003e\r\n    \u003ctd\u003e\u003ccode\u003e/api/languages\u003c/code\u003e\u003c/td\u003e\r\n    \u003ctd\u003e📋 List all available languages\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e\u003ccode\u003ePOST\u003c/code\u003e\u003c/td\u003e\r\n    \u003ctd\u003e\u003ccode\u003e/api/languages\u003c/code\u003e\u003c/td\u003e\r\n    \u003ctd\u003e➕ Add a new programming language\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e\u003ccode\u003eDELETE\u003c/code\u003e\u003c/td\u003e\r\n    \u003ctd\u003e\u003ccode\u003e/api/languages/{id}\u003c/code\u003e\u003c/td\u003e\r\n    \u003ctd\u003e🗑️ Remove a language\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e\u003ccode\u003ePOST\u003c/code\u003e\u003c/td\u003e\r\n    \u003ctd\u003e\u003ccode\u003e/api/languages/{id}/installations\u003c/code\u003e\u003c/td\u003e\r\n    \u003ctd\u003e📦 Install Docker image for language\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e\u003ccode\u003eDELETE\u003c/code\u003e\u003c/td\u003e\r\n    \u003ctd\u003e\u003ccode\u003e/api/languages/{id}/installations\u003c/code\u003e\u003c/td\u003e\r\n    \u003ctd\u003e🗑️ Uninstall Docker image\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n\u003c/table\u003e\r\n\r\n### 💻 Code Execution\r\n\r\n\u003ctable\u003e\r\n  \u003ctr\u003e\r\n    \u003cth\u003eMethod\u003c/th\u003e\r\n    \u003cth\u003eEndpoint\u003c/th\u003e\r\n    \u003cth\u003eDescription\u003c/th\u003e\r\n  \u003c/tr\u003e\r\n  \u003ctr\u003e\r\n    \u003ctd\u003e\u003ccode\u003ePOST\u003c/code\u003e\u003c/td\u003e\r\n    \u003ctd\u003e\u003ccode\u003e/api/executions\u003c/code\u003e\u003c/td\u003e\r\n    \u003ctd\u003e🏃‍♂️ Execute code in Docker container\u003c/td\u003e\r\n  \u003c/tr\u003e\r\n\u003c/table\u003e\r\n\r\n#### 📝 Example Execution Request\r\n\r\n```json\r\n{\r\n  \"languageId\": 1,\r\n  \"code\": \"print('Hello from Puppet! 🎭')\",\r\n  \"stdin\": \"\"\r\n}\r\n```\r\n\r\n#### 📊 Example Response\r\n\r\n```json\r\n{\r\n  \"success\": true,\r\n  \"output\": \"Hello from Puppet! 🎭\\n\",\r\n  \"error\": \"\",\r\n  \"executionTime\": \"0.043s\"\r\n}\r\n```\r\n\r\n---\r\n\r\n## 🐳 Docker Integration\r\n\r\nPuppet leverages Docker for secure code execution:\r\n\r\n- **🛡️ Isolation** – Each code execution runs in a separate container\r\n- **🔒 Security** – Sandboxed environment prevents system access\r\n- **📦 Flexibility** – Support for multiple programming languages\r\n- **⚡ Performance** – Efficient container lifecycle management\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\nWe welcome contributions! Here's how you can help:\r\n\r\n1. 🍴 **Fork** the repository\r\n2. 🌿 **Create** a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. 💾 **Commit** your changes (`git commit -m 'Add amazing feature'`)\r\n4. 📤 **Push** to the branch (`git push origin feature/amazing-feature`)\r\n5. 🔄 **Open** a Pull Request\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n---\r\n\u003cdiv align=\"center\"\u003e\r\n\u003cb\u003eMade with ❤️\u003c/b\u003e\r\n\r\n[⭐ Star this repo](../../stargazers) • [🐛 Report Bug](../../issues) • [💡 Request Feature](../../issues)\r\n\r\n\u003c/div\u003e\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprabalesh%2Fpuppet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprabalesh%2Fpuppet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprabalesh%2Fpuppet/lists"}