https://github.com/prabalesh/puppet
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.
https://github.com/prabalesh/puppet
code-execution docker go golang language-runner online-compiler postgresql
Last synced: 4 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/prabalesh/puppet
- Owner: prabalesh
- License: mit
- Created: 2025-05-24T04:56:13.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-06-19T13:48:42.000Z (6 months ago)
- Last Synced: 2025-06-19T14:46:57.198Z (6 months ago)
- Topics: code-execution, docker, go, golang, language-runner, online-compiler, postgresql
- Language: Go
- Homepage:
- Size: 78.1 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🧩 Puppet – Code Execution and Language Management API
[](LICENSE)
[](https://golang.org)
[](https://reactjs.org)
[](https://docker.com)
*A powerful full-stack application for managing programming languages and executing code in isolated Docker environments*
---
## ✨ Overview
Puppet is a comprehensive code execution platform that provides:
🔧 **Language Management** – Add, remove, and manage programming languages with Docker environments
💻 **Code Execution** – Run code snippets safely in isolated Docker containers
📥 **Stdin Support** – Execute code with custom input streams
🌐 **RESTful API** – Clean Go-based backend with comprehensive endpoints
⚛️ **Modern Frontend** – Intuitive React interface built with Vite
---
## 🚀 Tech Stack
Layer
Technology
Purpose
🔙 Backend
Go (net/http)
API server & business logic
🎨 Frontend
React + Vite
User interface & interactions
🐳 Container
Docker
Code execution isolation
🗄️ Database
PostgreSQL
Data persistence
🚀 Deployment
Docker Compose
Infrastructure orchestration
---
## 📁 Project Structure
```
puppet/
├── 🚀 cmd/puppet-api/ # Main entry point for the Go API
├── 🔧 internal/ # Backend application logic
│ ├── 📡 handler/ # HTTP request handlers
│ ├── 🔨 service/ # Business logic layer
│ ├── 📊 repository/ # Database abstraction layer
│ ├── 📋 model/ # Data models & entities
│ ├── 📦 dto/ # Data Transfer Objects
│ ├── 🧩 module/ # Dependency injection
│ └── ⚙️ config/, db/, logging/ # Configuration & infrastructure
├── 🌐 web-install/ # React frontend application
└── 🐳 docker-compose.yml # PostgreSQL container setup
```
---
## 🌟 Features
### 🔄 Language Management
- ➕ **Add Languages** – Register new programming languages
- 📋 **List Languages** – View all available languages
- 🗑️ **Remove Languages** – Clean up unused languages
- 📦 **Docker Management** – Install/uninstall language environments
### 💻 Code Execution
- 🏃♂️ **Safe Execution** – Run code in isolated Docker containers
- 📥 **Stdin Support** – Provide custom input to programs
- ⚡ **Fast Response** – Optimized execution pipeline
- 🛡️ **Security** – Sandboxed environment for code execution
### 🖥️ User Interface
- 🎨 **Modern Design** – Clean, intuitive React interface
- 📱 **Responsive** – Works seamlessly across devices
- 🔄 **Real-time** – Live code execution and results
- 🎯 **User-friendly** – Simple workflow for all skill levels
---
## ⚙️ Quick Start
### Prerequisites
Make sure you have the following installed:
- 🐳 [Docker](https://docker.com) & Docker Compose
- 🐹 [Go 1.22+](https://golang.org)
- 📦 [Node.js 16+](https://nodejs.org) & npm
### 🚀 Backend Setup
1. **Start PostgreSQL Database**
```bash
docker-compose up -d
```
2. **Configure Database Connection**
Ensure your `DB_URL` points to the running PostgreSQL container:
```
postgres://user:password@localhost:5432/puppet
```
3. **Launch API Server**
```bash
go run ./cmd/puppet-api
```
The API will be available at `http://localhost:8080` 🎉
### 🎨 Frontend Setup
1. **Navigate to Frontend Directory**
```bash
cd web-install
```
2. **Install Dependencies**
```bash
npm install
```
3. **Start Development Server**
```bash
npm run dev
```
The frontend will be available at `http://localhost:5173` ✨
---
## 📡 API Reference
### 🔧 Language Management
Method
Endpoint
Description
GET
/api/languages
📋 List all available languages
POST
/api/languages
➕ Add a new programming language
DELETE
/api/languages/{id}
🗑️ Remove a language
POST
/api/languages/{id}/installations
📦 Install Docker image for language
DELETE
/api/languages/{id}/installations
🗑️ Uninstall Docker image
### 💻 Code Execution
Method
Endpoint
Description
POST
/api/executions
🏃♂️ Execute code in Docker container
#### 📝 Example Execution Request
```json
{
"languageId": 1,
"code": "print('Hello from Puppet! 🎭')",
"stdin": ""
}
```
#### 📊 Example Response
```json
{
"success": true,
"output": "Hello from Puppet! 🎭\n",
"error": "",
"executionTime": "0.043s"
}
```
---
## 🐳 Docker Integration
Puppet leverages Docker for secure code execution:
- **🛡️ Isolation** – Each code execution runs in a separate container
- **🔒 Security** – Sandboxed environment prevents system access
- **📦 Flexibility** – Support for multiple programming languages
- **⚡ Performance** – Efficient container lifecycle management
---
## 🤝 Contributing
We welcome contributions! Here's how you can help:
1. 🍴 **Fork** the repository
2. 🌿 **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. 💾 **Commit** your changes (`git commit -m 'Add amazing feature'`)
4. 📤 **Push** to the branch (`git push origin feature/amazing-feature`)
5. 🔄 **Open** a Pull Request
---
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
Made with ❤️
[⭐ Star this repo](../../stargazers) • [🐛 Report Bug](../../issues) • [💡 Request Feature](../../issues)