@@ -41,28 +41,194 @@ Welcome to **GitHub Tracker**, a web app designed to help you monitor and analyz
4141---
4242
4343## 🚀 Setup Guide
44- 1 . Clone the repository to your local machine:
44+
45+ ### 📋 Prerequisites
46+
47+ Before setting up the project locally, ensure the following tools are installed on your system:
48+
49+ - Node.js (v18 or later recommended)
50+ - npm
51+ - Docker
52+ - Docker Compose
53+ - MongoDB (required for backend services and testing)
54+
55+ ---
56+
57+ ## 📥 Clone the Repository
58+
59+ ``` bash
60+ git clone https://github.com/GitMetricsLab/github_tracker.git
61+ cd github-tracker
62+ ```
63+
64+ ---
65+
66+ # 💻 Local Development Setup
67+
68+ This project contains both frontend and backend services.
69+
70+ ## ▶️ Frontend Setup
71+
72+ Install frontend dependencies:
73+
74+ ``` bash
75+ npm install
76+ ```
77+
78+ Start the frontend development server:
79+
80+ ``` bash
81+ npm run dev
82+ ```
83+
84+ The frontend will run on:
85+
86+ ``` txt
87+ http://localhost:5173
88+ ```
89+
90+ ---
91+
92+ ## ⚙️ Backend Setup
93+
94+ Move into the backend directory:
95+
4596``` bash
46- $ git clone https://github.com/yourusername/github-tracker.git
97+ cd backend
4798```
4899
49- 2 . Navigate to the project directory:
100+ Install backend dependencies:
101+
50102``` bash
51- $ cd github-tracker
103+ npm install
52104```
53105
54- 3 . Run the frontend
106+ Start the backend server:
107+
55108``` bash
56- $ npm i
57- $ npm run dev
109+ npm run dev
110+ ```
111+
112+ The backend server will run on:
113+
114+ ``` txt
115+ http://localhost:5000
58116```
59117
60- 4 . Run the backend
118+ ---
119+
120+ # 🐳 Docker Development Workflow
121+
122+ The project includes Docker configurations for both development and production environments.
123+
124+ ## 📦 Development Environment
125+
126+ Run the complete development environment using Docker:
127+
61128``` bash
62- $ npm i
63- $ npm start
129+ npm run docker:dev
64130```
65131
132+ This command:
133+
134+ - Builds frontend and backend containers
135+ - Starts development services
136+ - Enables live file changes using Docker volumes
137+ - Runs frontend and backend simultaneously
138+
139+ ### Development Services
140+
141+ | Service | Port |
142+ | ----------| ------|
143+ | Frontend | 5173 |
144+ | Backend | 5000 |
145+
146+ ---
147+
148+ ## 🚀 Production Environment
149+
150+ Run the production Docker setup:
151+
152+ ``` bash
153+ npm run docker:prod
154+ ```
155+
156+ This command:
157+
158+ - Creates optimized production builds
159+ - Runs frontend using Nginx
160+ - Starts backend production services
161+
162+ ### Production Services
163+
164+ | Service | Port |
165+ | ----------| ------|
166+ | Frontend | 3000 |
167+ | Backend | 5000 |
168+
169+ ---
170+
171+ # 📂 Docker Configuration Overview
172+
173+ | File | Purpose |
174+ | ------| ----------|
175+ | ` Dockerfile.dev ` | Development container setup |
176+ | ` Dockerfile.prod ` | Production container setup |
177+ | ` docker-compose.yml ` | Multi-service container orchestration |
178+
179+ ---
180+
181+ # 🔄 Local Development Workflow
182+
183+ Recommended contributor workflow:
184+
185+ 1 . Fork the repository
186+ 2 . Clone your fork locally
187+ 3 . Create a new branch
188+ 4 . Install dependencies
189+ 5 . Run frontend/backend locally or using Docker
190+ 6 . Make changes
191+ 7 . Test your implementation
192+ 8 . Commit and push changes
193+ 9 . Open a Pull Request
194+
195+ ---
196+
197+ # 🌱 Environment Configuration
198+
199+ The project uses environment variables for configuration.
200+
201+ Frontend environment variables:
202+
203+ ``` env
204+ VITE_BACKEND_URL=http://localhost:5000
205+ ```
206+
207+ Backend environment variables:
208+
209+ ``` env
210+ PORT=5000
211+ MONGO_URI=your_mongodb_connection
212+ SESSION_SECRET=your_secret
213+ ```
214+
215+ Create corresponding ` .env ` files before running the application.
216+
217+ ---
218+
219+ # 🛠️ Useful Commands
220+
221+ | Command | Description |
222+ | ----------| -------------|
223+ | ` npm run dev ` | Start frontend locally |
224+ | ` npm run build ` | Create production build |
225+ | ` npm run docker:dev ` | Run Docker development environment |
226+ | ` npm run docker:prod ` | Run Docker production environment |
227+ | ` npm run test ` | Run frontend tests |
228+ | ` npm run test:backend ` | Run backend tests |
229+
230+ ---
231+
66232## 🧪 Backend Unit & Integration Testing with Jasmine
67233
68234This project uses the Jasmine framework for backend unit and integration tests. The tests cover:
@@ -140,3 +306,6 @@ spec_files: [
140306 ⬆️ Back to Top
141307 </a >
142308</p >
309+
310+
311+
0 commit comments