Skip to content

[docs] wrote docs about complete explain #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
devlopersabbir merged 1 commit into from
Jul 19, 2025
Merged

[docs] wrote docs about complete explain #18

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 68 additions & 31 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,35 +1,65 @@
# Code Executor Backend
<h1 align="center">🚀 ExecuteMe – Run Code Instantly and Securely</h1>

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/<uuid>`)
- 🧼 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).
Expand All @@ -50,13 +80,20 @@ 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!

- **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 💕
<a href="https://github.com/devlopersabbir/executeme/graphs/contributors">
<img src="https://contrib.rocks/image?repo=devlopersabbir/executeme" />
</a>

`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).