A powerful full-stack application for managing programming languages and executing code in isolated Docker environments
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
| 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 |
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
- ➕ Add Languages – Register new programming languages
- 📋 List Languages – View all available languages
- 🗑️ Remove Languages – Clean up unused languages
- 📦 Docker Management – Install/uninstall language environments
- 🏃♂️ 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
- 🎨 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
Make sure you have the following installed:
- 🐳 Docker & Docker Compose
- 🐹 Go 1.22+
- 📦 Node.js 16+ & npm
-
Start PostgreSQL Database
docker-compose up -d
-
Configure Database Connection
Ensure your
DB_URLpoints to the running PostgreSQL container:postgres://user:password@localhost:5432/puppet -
Launch API Server
go run ./cmd/puppet-api
The API will be available at
http://localhost:8080🎉
-
Navigate to Frontend Directory
cd web-install -
Install Dependencies
npm install
-
Start Development Server
npm run dev
The frontend will be available at
http://localhost:5173✨
| 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 |
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/executions |
🏃♂️ Execute code in Docker container |
{
"languageId": 1,
"code": "print('Hello from Puppet! 🎭')",
"stdin": ""
}{
"success": true,
"output": "Hello from Puppet! 🎭\n",
"error": "",
"executionTime": "0.043s"
}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
We welcome contributions! Here's how you can help:
- 🍴 Fork the repository
- 🌿 Create a feature branch (
git checkout -b feature/amazing-feature) - 💾 Commit your changes (
git commit -m 'Add amazing feature') - 📤 Push to the branch (
git push origin feature/amazing-feature) - 🔄 Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.