|
19 | 19 |
|
20 | 20 | --- |
21 | 21 |
|
22 | | -## 🧑💻 **Contributor Quick Start** |
| 22 | +## 🚀 Quick Start |
23 | 23 |
|
24 | | -> **We love contributors!** Follow these steps to get started quickly: |
| 24 | +### Prerequisites |
| 25 | + |
| 26 | +- **Node.js 18+** and **Yarn** package manager |
| 27 | +- **Docker & Docker Compose** (latest versions) |
| 28 | +- **Git** for version control |
| 29 | +- **MongoDB** (handled by Docker Compose) |
| 30 | +- **Redis** (handled by Docker Compose) |
| 31 | + |
| 32 | +## 🟢 **Contributor Quick Setup** |
| 33 | + |
| 34 | +> **We love contributors!** |
| 35 | +> |
| 36 | +> **Follow these steps to get started quickly as a contributor:** |
25 | 37 |
|
26 | 38 | ### 1. Fork & Clone the Repository |
27 | 39 |
|
|
30 | 42 | git clone https://github.com/YOUR_USERNAME/SafeExec.git |
31 | 43 | cd SafeExec |
32 | 44 |
|
| 45 | +# Add upstream remote for syncing |
33 | 46 | git remote add upstream https://github.com/vikashkrdeveloper/SafeExec.git |
34 | 47 | ``` |
35 | 48 |
|
36 | | -### 2. Quick Local Setup (Recommended) |
| 49 | +### 2. Quick Setup (Recommended for Contributors) |
37 | 50 |
|
38 | 51 | ```bash |
| 52 | +# Complete development setup in one command |
39 | 53 | yarn setup:dev |
40 | | -# Installs dependencies, builds Docker executors, starts dev environment, seeds DB |
| 54 | + |
| 55 | +# This command will: |
| 56 | +# - Install all dependencies |
| 57 | +# - Build Docker executor containers |
| 58 | +# - Start development environment with Docker |
| 59 | +# - Seed database with sample data |
41 | 60 | ``` |
42 | 61 |
|
43 | 62 | ### 3. Manual Setup (Step by Step) |
44 | 63 |
|
| 64 | +**3.1. Install Dependencies & Build Executors** |
| 65 | + |
45 | 66 | ```bash |
46 | 67 | yarn setup |
| 68 | +# Equivalent to: yarn install && yarn build:executors |
| 69 | +``` |
| 70 | + |
| 71 | +**3.2. Environment Configuration** |
| 72 | + |
| 73 | +```bash |
| 74 | +# Copy environment template |
47 | 75 | cp .env.example .env |
48 | | -# Edit .env as needed |
49 | 76 |
|
| 77 | +# Edit the .env file with your local configuration |
| 78 | +nano .env # or use your preferred editor |
| 79 | +``` |
| 80 | + |
| 81 | +**Sample .env for local development:** |
| 82 | + |
| 83 | +```env |
| 84 | +NODE_ENV=development |
| 85 | +PORT=5000 |
| 86 | +MONGO_URI=mongodb://localhost:27017/rce_dev |
| 87 | +REDIS_HOST=localhost |
| 88 | +REDIS_PORT=6379 |
| 89 | +JWT_SECRET=your-super-secret-jwt-key-for-development |
| 90 | +JWT_EXPIRES_IN=24h |
| 91 | +``` |
| 92 | + |
| 93 | +**3.3. Start Development Environment** |
| 94 | + |
| 95 | +```bash |
| 96 | +# Start all services: API, MongoDB, Redis, Nginx |
50 | 97 | yarn docker:setup:dev |
51 | | -# Or: yarn dev (if running MongoDB/Redis locally) |
| 98 | + |
| 99 | +# Or start services individually |
| 100 | +yarn docker:dev:build # Build containers |
| 101 | +yarn docker:dev # Start all services |
| 102 | +yarn docker:seed:dev # Seed database with sample data |
| 103 | + |
| 104 | +yarn dev # API only (requires local MongoDB/Redis) |
52 | 105 | ``` |
53 | 106 |
|
54 | | -### 4. Verify Setup |
| 107 | +**3.4. Verify Setup** |
55 | 108 |
|
56 | 109 | ```bash |
| 110 | +# Check all services are running |
57 | 111 | yarn docker:status |
| 112 | + |
| 113 | +# Check API health |
58 | 114 | yarn health |
59 | | -``` |
| 115 | +# Or manually: curl -f http://localhost:5000/health |
60 | 116 |
|
61 | | -### 5. Start Contributing! |
| 117 | +# View logs |
| 118 | +yarn logs |
| 119 | +# Or: yarn docker:dev:logs |
62 | 120 |
|
63 | | -- Create a feature branch: `git checkout -b feature/your-feature` |
64 | | -- Make your changes and add tests |
65 | | -- Run checks: `yarn test && yarn lint && yarn typecheck` |
66 | | -- Commit and push: `git commit -m "feat: your change" && git push` |
67 | | -- Open a Pull Request on GitHub |
| 121 | +# Access container shell (for debugging) |
| 122 | +yarn shell |
| 123 | +# Or: yarn docker:dev:shell |
| 124 | +``` |
68 | 125 |
|
69 | 126 | --- |
70 | 127 |
|
71 | | -## 🤝 How to Contribute |
| 128 | +## 📋 Development Workflow for Contributors |
72 | 129 |
|
73 | | -- **Find an issue**: Look for [good first issue](https://github.com/vikashkrdeveloper/SafeExec/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue) or [help wanted](https://github.com/vikashkrdeveloper/SafeExec/issues?q=is%3Aissue+is%3Aopen+label%3Ahelp-wanted) |
74 | | -- **Discuss**: Comment on issues or open a new one for ideas |
75 | | -- **Follow code style**: Use ESLint, Prettier, and TypeScript |
76 | | -- **Write tests**: Keep coverage high |
77 | | -- **Update docs**: If you change or add features |
| 130 | +### Daily Development |
78 | 131 |
|
79 | | -See the [Contributing Guide](CONTRIBUTING) for more details. |
| 132 | +```bash |
| 133 | +# 1. Sync with upstream |
| 134 | +git checkout main |
| 135 | +git pull upstream main |
| 136 | +git push origin main |
80 | 137 |
|
81 | | ---- |
| 138 | +# 2. Create feature branch |
| 139 | +git checkout -b feature/your-feature-name |
82 | 140 |
|
83 | | -## 🚀 Quick Start (for all users) |
| 141 | +# 3. Start development environment |
| 142 | +yarn setup:dev |
| 143 | +# Or if already set up: yarn docker:dev |
84 | 144 |
|
85 | | -### Prerequisites |
| 145 | +# 4. Make your changes... |
86 | 146 |
|
87 | | -- **Node.js 18+** and **Yarn** |
88 | | -- **Docker & Docker Compose** |
89 | | -- **Git** |
90 | | -- **MongoDB** and **Redis** (via Docker Compose) |
| 147 | +# 5. Run tests and checks |
| 148 | +yarn test |
| 149 | +yarn lint |
| 150 | +yarn typecheck |
91 | 151 |
|
92 | | -### Local Development Setup |
| 152 | +# 6. Test in different environments |
| 153 | +yarn docker:test:run # Run tests in test environment |
| 154 | +yarn docker:test:coverage # Generate coverage report |
93 | 155 |
|
94 | | -```bash |
95 | | -yarn setup:dev |
96 | | -# or step by step: |
97 | | -yarn setup |
98 | | -cp .env.example .env |
99 | | -# Edit .env |
| 156 | +# 7. Commit and push |
| 157 | +git add . |
| 158 | +git commit -m "feat: your descriptive commit message" |
| 159 | +git push origin feature/your-feature-name |
100 | 160 |
|
101 | | -yarn docker:setup:dev |
102 | | -# or: yarn dev |
| 161 | +# 8. Create Pull Request on GitHub |
103 | 162 | ``` |
104 | 163 |
|
105 | | ---- |
| 164 | +### Testing Your Changes |
| 165 | + |
| 166 | +```bash |
| 167 | +# Run all tests |
| 168 | +yarn test |
106 | 169 |
|
107 | | -## 📚 Documentation |
| 170 | +# Run tests with coverage |
| 171 | +yarn test:coverage |
108 | 172 |
|
109 | | -- [API Documentation](docs/API.md) |
110 | | -- [Development Guide](docs/DEVELOPMENT.md) |
111 | | -- [Docker Guide](docs/DOCKER.md) |
| 173 | +# Run integration tests |
| 174 | +yarn test:integration |
112 | 175 |
|
113 | | ---- |
| 176 | +# Test Docker containers |
| 177 | +yarn docker:test # Start test environment |
| 178 | +yarn docker:test:run # Run tests in containers |
| 179 | +yarn docker:test:coverage # Generate coverage in containers |
114 | 180 |
|
115 | | -## 📝 API Endpoints (Sample) |
| 181 | +# Manual API testing |
| 182 | +yarn health # Check API health |
| 183 | +curl http://localhost:5000/api-docs # Check API docs |
| 184 | +``` |
| 185 | + |
| 186 | +### Debugging and Troubleshooting |
| 187 | + |
| 188 | +```bash |
| 189 | +# View logs |
| 190 | +yarn logs # Development logs |
| 191 | +yarn docker:dev:logs # Development logs |
116 | 192 |
|
117 | | -- `POST /api/auth/register` — Register user |
118 | | -- `POST /api/auth/login` — Login |
119 | | -- `GET /api/auth/profile` — Get profile |
120 | | -- `POST /api/submit` — Submit code |
121 | | -- `GET /api/problems` — List problems |
| 193 | +# Access container shell |
| 194 | +yarn shell # Development container |
| 195 | +yarn docker:dev:shell # Development container |
122 | 196 |
|
123 | | -See [API.md](docs/API.md) for full details. |
| 197 | +# Check service status |
| 198 | +yarn docker:status # All containers status |
| 199 | +yarn docker:health # Health check status |
| 200 | + |
| 201 | +# Restart services |
| 202 | +yarn restart # Restart development environment |
| 203 | +yarn reset # Complete reset (clean + setup) |
| 204 | +``` |
124 | 205 |
|
125 | 206 | --- |
126 | 207 |
|
127 | | -## 🛡️ Security & Architecture |
| 208 | +## 🤝 Contributing to SafeExec |
| 209 | + |
| 210 | +We welcome contributions from developers of all skill levels! Whether you're fixing bugs, adding features, improving documentation, or enhancing security, your contributions help make this project better for everyone. |
| 211 | + |
| 212 | +### How to Contribute |
128 | 213 |
|
129 | | -- Isolated Docker containers for each code run |
130 | | -- JWT authentication & rate limiting |
131 | | -- Input validation & sanitization |
132 | | -- Resource limits (CPU, memory, time) |
133 | | -- Audit logs & monitoring |
| 214 | +- **Find an issue**: Look for [good first issue](https://github.com/vikashkrdeveloper/SafeExec/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue) or [help wanted](https://github.com/vikashkrdeveloper/SafeExec/issues?q=is%3Aissue+is%3Aopen+label%3Ahelp-wanted) |
| 215 | +- **Discuss**: Comment on issues or open a new one for ideas |
| 216 | +- **Follow code style**: Use ESLint, Prettier, and TypeScript |
| 217 | +- **Write tests**: Keep coverage high |
| 218 | +- **Update docs**: If you change or add features |
| 219 | + |
| 220 | +See the [Contributing Guide](CONTRIBUTING) for more details. |
134 | 221 |
|
135 | 222 | --- |
136 | 223 |
|
137 | | -## 📦 Project Structure |
| 224 | +## 📦 Deployment |
138 | 225 |
|
139 | | -``` |
140 | | -SafeExec/ |
141 | | -├── src/ # Source code |
142 | | -├── docker/ # Docker configs |
143 | | -├── tests/ # Tests |
144 | | -├── docs/ # Documentation |
145 | | -├── scripts/ # Utility scripts |
146 | | -├── ... # More files |
147 | | -``` |
| 226 | +> **Note:** This project is open source and intended for local development, testing, and educational use. For production deployment, please refer to the [DEPLOYMENT.md](docs/DEPLOYMENT.md) guide and follow security best practices. **Production-specific instructions have been removed from this README.** |
148 | 227 |
|
149 | 228 | --- |
150 | 229 |
|
151 | | -## 🆘 Getting Help |
| 230 | +## 🛡️ Security Best Practices |
152 | 231 |
|
153 | | -- Check [issues](https://github.com/vikashkrdeveloper/SafeExec/issues) |
154 | | -- Read the docs |
155 | | -- Open a discussion or ask a question |
| 232 | +> For production security, see [DEPLOYMENT.md](docs/DEPLOYMENT.md) and [DOCKER.md](docs/DOCKER.md). |
156 | 233 |
|
157 | 234 | --- |
158 | 235 |
|
| 236 | +**Thank you for contributing to SafeExec! 🚀** |
| 237 | + |
| 238 | +Your contributions help create a better, more secure code execution platform for developers worldwide. |
| 239 | + |
159 | 240 | ## 📄 License |
160 | 241 |
|
161 | 242 | MIT License - see LICENSE file for details |
162 | 243 |
|
| 244 | +## 🆘 Support |
| 245 | + |
| 246 | +For issues and questions: |
| 247 | + |
| 248 | +- Create GitHub issues for bugs |
| 249 | +- Check documentation for common solutions |
| 250 | +- Review logs for detailed error information |
| 251 | +- Test with provided test scripts |
| 252 | + |
163 | 253 | --- |
164 | 254 |
|
165 | | -**Thank you for contributing to SafeExec! 🚀** |
| 255 | +**⚠️ Security Notice**: This is a powerful system that executes arbitrary code. Always run in isolated environments and follow security best practices for production deployments. |
0 commit comments