Skip to content

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.

License

Notifications You must be signed in to change notification settings

prabalesh/puppet

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

🧩 Puppet – Code Execution and Language Management API

License Go Version React Docker

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:

🚀 Backend Setup

  1. Start PostgreSQL Database

    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

    go run ./cmd/puppet-api

    The API will be available at http://localhost:8080 🎉

🎨 Frontend Setup

  1. Navigate to Frontend Directory

    cd web-install
  2. Install Dependencies

    npm install
  3. Start Development Server

    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

{
  "languageId": 1,
  "code": "print('Hello from Puppet! 🎭')",
  "stdin": ""
}

📊 Example Response

{
  "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 file for details.


About

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.

Topics

Resources

License

Stars

Watchers

Forks

Contributors 2

  •  
  •