@@ -28,6 +28,7 @@ Before starting, ensure you have the following installed:
2828- ** Git** - [ Download] ( https://git-scm.com/ )
2929
3030Verify installations:
31+
3132``` bash
3233node --version
3334npm --version
@@ -41,26 +42,29 @@ docker compose version
4142
4243The project uses three environment files:
4344
44- | File | Purpose | When to Use |
45- | ------| ---------| -------------|
46- | ** ` .env ` ** | Local development | Running NestJS locally (outside Docker) |
47- | ** ` .env.docker ` ** | Docker environment | Running with Docker Compose |
48- | ** ` .example.env ` ** | Template file | Reference for creating new environment files |
45+ | File | Purpose | When to Use |
46+ | ------------------ | ------------------ | -------------------------------------------- |
47+ | ** ` .env ` ** | Local development | Running NestJS locally (outside Docker) |
48+ | ** ` .env.docker ` ** | Docker environment | Running with Docker Compose |
49+ | ** ` .example.env ` ** | Template file | Reference for creating new environment files |
4950
5051### 🔐 Environment File Locations
52+
5153All environment files are located in: ` src/environment/ `
5254
5355---
5456
5557## 🎯 Initial Setup
5658
5759### Step 1: Clone the Repository
60+
5861``` bash
5962git clone < repository-url>
6063cd < project-directory>
6164```
6265
6366### Step 2: Install Dependencies
67+
6468``` bash
6569npm install
6670# or
@@ -70,12 +74,15 @@ yarn install
7074### Step 3: Set Up Environment Files
7175
7276#### Option A: Local Development (without Docker for app)
77+
73781 . Copy the example environment file:
79+
7480``` bash
7581cp src/environment/.example.env src/environment/.env
7682```
7783
78842 . Edit ` src/environment/.env ` with your configuration:
85+
7986``` env
8087# ===========================
8188# Application Configuration
@@ -114,12 +121,15 @@ SWAGGER_VERSION=1
114121```
115122
116123#### Option B: Docker Environment
124+
1171251 . Copy the example Docker environment file:
126+
118127``` bash
119128cp src/environment/.example.env src/environment/.env.docker
120129```
121130
1221312 . Edit ` src/environment/.env.docker ` :
132+
123133``` env
124134# ===========================
125135# PostgreSQL Configuration
@@ -146,34 +156,41 @@ PGADMIN_DEFAULT_PASSWORD=postgres
146156This runs the NestJS app locally while using Docker for the database only.
147157
148158#### Step 1: Start Database Services
159+
149160``` bash
150161npm run docker:up:db
151162```
152163
153164This command:
165+
154166- Starts PostgreSQL container
155167- Starts pgAdmin container
156168- Uses configurations from ` .env.docker `
157169
158170#### Step 2: Wait for Database to Initialize
171+
159172Wait about 10-15 seconds for PostgreSQL to fully start.
160173
161174#### Step 3: Run Database Migrations
175+
162176``` bash
163177npm run migration:run
164178```
165179
166180#### Step 4: (Optional) Seed the Database
181+
167182``` bash
168183npm run seed
169184```
170185
171186#### Step 5: Start the Development Server
187+
172188``` bash
173189npm run start:dev
174190```
175191
176192The application will be available at:
193+
177194- ** API** : ` http://localhost:3535 `
178195- ** Swagger Docs** : ` http://localhost:3535/api-docs `
179196- ** pgAdmin** : ` http://localhost:5051 `
@@ -196,6 +213,7 @@ docker exec -it <container-name> npm run seed
196213## 🗄 Database Management
197214
198215### Accessing pgAdmin
216+
1992171 . Open browser: ` http://localhost:5051 `
2002182 . Login with credentials from ` .env.docker ` :
201219 - Email: ` admin@admin.com `
@@ -210,21 +228,25 @@ docker exec -it <container-name> npm run seed
210228### Managing Migrations
211229
212230#### Generate a New Migration
231+
213232``` bash
214233npm run migration:generate -- MigrationName
215234```
216235
217236#### Run Pending Migrations
237+
218238``` bash
219239npm run migration:run
220240```
221241
222242#### Revert Last Migration
243+
223244``` bash
224245npm run migration:revert
225246```
226247
227248### Seeding Data
249+
228250``` bash
229251npm run seed
230252```
@@ -234,32 +256,37 @@ npm run seed
234256## 📜 Available Scripts
235257
236258### Development
259+
237260``` bash
238261npm run start:dev # Start development server with hot-reload
239262npm run start:debug # Start with debugging enabled
240263npm run build # Build the project for production
241264```
242265
243266### Production
267+
244268``` bash
245269npm run start:prod # Run production build
246270npm run start # Alternative production start
247271```
248272
249273### Code Quality
274+
250275``` bash
251276npm run lint # Lint and auto-fix TypeScript files
252277npm run format # Format code with Prettier
253278```
254279
255280### Docker
281+
256282``` bash
257283npm run docker:up:db # Start database services (PostgreSQL + pgAdmin)
258284npm run docker:down # Stop and remove all containers
259285npm run docker:logs # View container logs
260286```
261287
262288### Database
289+
263290``` bash
264291npm run migration:generate # Generate new migration
265292npm run migration:run # Run pending migrations
@@ -272,6 +299,7 @@ npm run seed # Seed database with initial data
272299## 🐛 Troubleshooting
273300
274301### Port Already in Use
302+
275303If you see "port already in use" errors:
276304
277305``` bash
@@ -285,19 +313,23 @@ kill -9 <PID>
285313Or change the port in your ` .env ` file.
286314
287315### Database Connection Failed
316+
2883171 . Ensure Docker containers are running:
318+
289319``` bash
290320docker ps
291321```
292322
2933232 . Check if PostgreSQL is ready:
324+
294325``` bash
295326docker logs < postgres-container-name>
296327```
297328
2983293 . Verify database credentials match in both ` .env ` and ` .env.docker `
299330
300331### Migration Errors
332+
301333If migrations fail:
302334
303335``` bash
@@ -313,6 +345,7 @@ npm run migration:run
313345```
314346
315347### Docker Build Issues
348+
316349Clear Docker cache and rebuild:
317350
318351``` bash
@@ -321,6 +354,7 @@ npm run docker:up:db
321354```
322355
323356### Permission Denied (Linux/Mac)
357+
324358``` bash
325359sudo chown -R $USER :$USER .
326360```
@@ -363,4 +397,4 @@ sudo chown -R $USER:$USER .
363397
364398** Happy Coding! 🎉**
365399
366- For issues or questions, please open an issue in the repository or contact the development team.
400+ For issues or questions, please open an issue in the repository or contact the development team.
0 commit comments