diff --git a/README.md b/README.md index 8002ba0..f9392e0 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,65 @@ -# Code Executor Backend +

๐Ÿš€ ExecuteMe โ€“ Run Code Instantly and Securely

-A robust and secure backend service for executing user-submitted code in isolated Docker containers. This project provides an API endpoint to receive code snippets in various programming languages and runs them within dedicated, resource-limited Docker environments, returning the execution output. +**[ExecuteMe](https://executeme.vercel.app)** is a powerful and minimalistic online code execution platform that allows developers to write, run, and test code in multiple programming languages instantly and securely โ€” all within the browser. -## โœจ Features - -- **Multi-Language Support:** Execute code written in Python, Node.js, and Java out-of-the-box. Easily extensible to support more languages. - -- **Docker Isolation:** Each code execution runs in its own ephemeral Docker container, ensuring process isolation and preventing interference between different code submissions. - -- **Resource Limiting:** Configurable memory and CPU limits for each execution to prevent resource exhaustion from malicious or inefficient code. - -- **API-Driven:** Simple RESTful API endpoint for seamless integration with frontend applications or other services. - -- **Temporary File Handling:** Manages temporary directories and files for each execution, ensuring clean-up after completion. - -## ๐Ÿš€ Technologies Used - -- **Node.js:** The primary backend language, utilizing Express.js for the API. - -- **Express.js:** Fast, unopinionated, minimalist web framework for Node.js. - -- **Docker:** Containerization platform used for isolating code execution environments. - -- **Python:** Supported language for code execution. - -- **Java (OpenJDK):** Supported language for code execution. - -- **uuid:** For generating unique identifiers for temporary execution directories. - -## ๐Ÿ“‹ Prerequisites +Whether you're experimenting with a new idea or teaching code, ExecuteMe gives you a real-time, sandboxed environment that works out of the box. +## โœจ Features +- **โšก Instant Code Execution** โ€“ Run your code in real-time with just one click +- **๐Ÿ”’ Secure Sandbox** โ€“ Ensures your code runs in a safe, isolated environment +- **๐Ÿง  Multi-language Support** โ€“ Supports a growing list of languages including: + - ๐Ÿ Python + - ๐ŸŸจ JavaScript + - ๐ŸŸฆ TypeScript + - โ˜• Java + - ๐Ÿ’™ Kotlin +- **๐ŸŽจ Full Syntax Highlighting** โ€“ Modern and readable code editor with theme support +- **๐Ÿ–ฅ๏ธ Responsive UI** โ€“ Works smoothly across all devices +- **๐ŸŒ Live User Activity** โ€“ Shows active coders in real-time +- **๐Ÿ’พ Open Source** โ€“ Freely available to use, modify, and contribute + +## ๐Ÿ› ๏ธ Built With +- **โš›๏ธ NextJs** โ€“ For frontend and tailwindcss for designing user interface +- **๐Ÿงฐ Monaco Editor** โ€“ Powerful web-based code editor (from VS Code) +- **๐ŸŒ Node.js + Express** โ€“ Backend service for execution management +- **๐Ÿ”„ Docker** โ€“ Containerized code execution +- **๐Ÿ“ก Socket.IO** โ€“ Real-time connection to track active users +- **๐Ÿ“ NodeCache** โ€“ In-memory cache for managing live sessions +- **๐Ÿ” Custom Docker Images** โ€“ Tailored environments per language + +## ๐Ÿงฉ Architecture & Execution Challenges +Designing ExecuteMe required solving real-world challenges in scalability, isolation, and memory/resource management: + +## โš™๏ธ On-Demand Container Execution +- ๐Ÿ“ฆ Each execution triggers a **new Docker container**, isolated per language and user +- ๐Ÿงพ Code is saved temporarily in a unique `UUID` directory (e.g., `/temp/`) +- ๐Ÿงผ After execution, both the **container and the temporary code directory** are destroyed automatically +- โœ… Ensures **complete statelessness** and no leftover data between runs + +## ๐Ÿง  Memory & CPU Management +- ๐Ÿง  Containers are limited via flags: + --memory=512m and --cpus=0.5 +- ๐Ÿ” Ensures no user can overuse system resources +- ๐Ÿงน Automatic cleanup after every run helps maintain low disk and memory usage + +## ๐Ÿ” Concurrent Execution Handling +- โฑ๏ธ Uses `async/await` and `promisify(exec)` to avoid blocking the event loop +- โšก Handles **multiple user requests at the same time**, spawning separate containers for each +- ๐Ÿ› ๏ธ Every language is handled via its own custom-built Docker image (`executor-python`, `executor-java`, etc.) + +## ๐Ÿ”’ Security Isolation +- ๐Ÿ” Code runs in **completely sandboxed containers** with: + - No access to host machine + - No persistent file system or shared memory +- ๐Ÿšซ Containers are removed after use with --rm to prevent abuse +- โœ… Each language has its own minimal, locked-down Docker image + +## ๐Ÿ‘ฅ Real-Time User Tracking +- ๐Ÿ“ก `Socket.IO + NodeCache` manage user connections in real-time +- ๐Ÿ‘€ Displays current active users to the frontend +- โ™ป๏ธ Cleans up cache on disconnect to prevent stale connections + +## ๐Ÿ“‹ Prerequisites - For contribution Before you get started, ensure you have the following installed on your system: - [**Docker**](https://docs.docker.com/get-docker/): Docker Engine and Docker Compose (Docker Desktop includes both). @@ -50,6 +80,10 @@ Before you get started, ensure you have the following installed on your system: 4. Make your changes, write tests, and ensure code quality. 5. Open a Pull Request with a clear description of your work. +## ๐Ÿ“„ License + +This project is licensed under the MIT License - see the [LICENSE](/LICENSE) file for details. + ### Support the Project: If `executeme` helps you or your project, consider showing your support. Your contributions help maintain and improve this tool for the entire developer community! @@ -57,6 +91,9 @@ If `executeme` helps you or your project, consider showing your support. Your co - **Sponsor on GitHub:** [https://github.com/sponsors/devlopersabbir](https://github.com/sponsors/devlopersabbir) - **Buy Me a Coffee:** [https://buymeacoffee.com/devlopersabbir](https://buymeacoffee.com/devlopersabbir) -## ๐Ÿ Conclusion +### Specially Thanks ๐Ÿ’• + + + -`executeme` offers a powerful, secure, and flexible solution for executing code in a sandboxed environment. By leveraging Docker, it provides the isolation needed for production use cases while remaining easy to integrate and extend. Give it a try for your next project that requires dynamic code execution! +Made with [contrib.rocks](https://contrib.rocks).