Skip to content

README.md

Latest commit

 

History

History
191 lines (147 loc) · 4.6 KB

README.md

File metadata and controls

191 lines (147 loc) · 4.6 KB

NullStack ⚡

A lightweight, self-hosted platform for running and testing Python, SQL, and Java code — with sandboxed execution and optional AI-powered feedback.

✨ Features

  • 🧪 Automated testing — public + hidden test cases with instant pass/fail results
  • 🐳 Sandboxed execution — all code runs in isolated Docker containers (no network, memory-limited, time-limited)
  • 🤖 AI code review — optional constructive feedback via Phi-3 Mini running locally through Ollama
  • 📝 Multi-language support — Python, SQL, and Java out of the box
  • 🔒 Hidden test protection — hidden test cases are never exposed to the frontend
  • ⚡ One-command setup — docker compose up and you're running

🚀 Quick Start

docker compose up

Then open http://localhost:8501 in your browser.

🏗️ Architecture

┌─────────────┐
│  Streamlit  │  (Port 8501) - Web UI
│     UI      │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Flask     │  (Port 5000) - REST API
│    API      │
└──────┬──────┘
       │
       ├──────► SQLite Database (assignments, submissions, results)
       │
       └──────► Code Executor (isolated Docker containers)
                        │
                        └──► Phi-3 AI via Ollama (optional)
Layer Tech
Frontend Streamlit
Backend Flask (Python 3.11)
Database SQLite
Execution Docker containers
AI Feedback Phi-3 Mini via Ollama (optional)
Orchestration Docker Compose

📁 Project Structure

nullstack/
├── api/
│   ├── app.py              # Flask REST API
│   ├── database.py         # DB operations
│   ├── executor.py         # Sandboxed code runner
│   ├── ai_feedback.py      # Ollama integration
│   └── requirements.txt
├── ui/
│   ├── streamlit_app.py    # Web interface
│   └── requirements.txt
├── assignments/
│   ├── python_two_sum.json
│   ├── sql_top_salaries.json
│   └── java_palindrome.json
├── database/
│   └── nullstack.db          # Auto-created on first run
├── docker-compose.yml
├── Dockerfile.api
└── Dockerfile.ui

🔐 Security

All user-submitted code runs in ephemeral Docker containers with:

  • --network none — no internet access
  • --memory 128m — memory cap
  • --cpus 0.5 — CPU cap
  • 5-second execution timeout
  • Read-only code mounts
  • No eval() on the host — ever

Hidden test cases are stored server-side only and never sent to the frontend or AI model.

🤖 AI Feedback (Optional)

NullStack can generate 2–3 sentence code reviews using a local LLM — no API keys, no data leaving your machine.

Setup:

# Install Ollama: https://ollama.ai
ollama pull phi3:mini
# Then restart the API — it auto-detects Ollama

Alternative models:

  • qwen2.5-coder:1.5b — faster, lighter
  • deepseek-coder:1.3b — good code understanding

➕ Adding Your Own Problems

Create a JSON file in /assignments/:

{
  "id": "unique_id",
  "language": "python",
  "title": "Problem Title",
  "description": "Problem description...",
  "starter_code": "def solution():\n    pass",
  "entry_point": "solution",
  "public_tests": [
    { "input": [1, 2], "expected_output": 3, "description": "basic case" }
  ],
  "hidden_tests": [
    { "input": [5, 5], "expected_output": 10 }
  ],
  "limits": {
    "time_seconds": 5,
    "memory_mb": 128
  }
}

Then run:

cd api && python database.py

🛠️ Run Without Docker

API:

cd api
pip install -r requirements.txt
python database.py   # initialize DB
python app.py

UI:

cd ui
pip install -r requirements.txt
streamlit run streamlit_app.py

📋 Sample Problems Included

Problem Language Description
Two Sum Python Find two numbers that add up to a target
Top Salaries SQL Query top 3 salaries per department
Valid Palindrome Java Check if a string is a palindrome

⚠️ Known Limitations

  • SQL uses SQLite (not MySQL/PostgreSQL) — some syntax may differ
  • Java recompiles on every submission — no caching yet
  • No user authentication — open access by design for now
  • Basic textarea editor — no syntax highlighting

📄 License

MIT © Syed Rizwan Uddin — 2026