200 lines
4.2 KiB
Markdown
200 lines
4.2 KiB
Markdown
# 🚀 Quick Start Guide - Retail POS Backend
|
|
|
|
## For Local Development (WITHOUT Redis)
|
|
|
|
### ✅ **You Only Need PostgreSQL!**
|
|
|
|
Redis is **completely optional**. The application will use in-memory caching if Redis is not available.
|
|
|
|
---
|
|
|
|
## 📋 Prerequisites
|
|
|
|
- **Node.js** 18+
|
|
- **PostgreSQL** 15+ (this is **required**)
|
|
- **npm** or **yarn**
|
|
|
|
---
|
|
|
|
## 🏃 Quick Start (3 steps)
|
|
|
|
### **Step 1: Create PostgreSQL Database**
|
|
|
|
```bash
|
|
# Make sure PostgreSQL is running, then create the database
|
|
createdb retail_pos
|
|
|
|
# Or using psql
|
|
psql postgres -c "CREATE DATABASE retail_pos;"
|
|
```
|
|
|
|
### **Step 2: Update .env File**
|
|
|
|
Edit `.env` and update **ONLY these database fields**:
|
|
|
|
```bash
|
|
DB_HOST=localhost
|
|
DB_PORT=5432
|
|
DB_USERNAME=your_postgres_username
|
|
DB_PASSWORD=your_postgres_password
|
|
DB_DATABASE=retail_pos
|
|
```
|
|
|
|
**You can ignore the Redis settings** - the app will work fine without it!
|
|
|
|
### **Step 3: Start the Application**
|
|
|
|
```bash
|
|
# Install dependencies (already done)
|
|
npm install
|
|
|
|
# Run database migrations to create tables
|
|
npm run migration:run
|
|
|
|
# (Optional) Seed sample data
|
|
npm run seed:run
|
|
|
|
# Start the development server
|
|
npm run start:dev
|
|
```
|
|
|
|
🎉 **Done!** Your API is now running at http://localhost:3000/api
|
|
|
|
---
|
|
|
|
## 📱 Access Points
|
|
|
|
Once the server is running:
|
|
|
|
- **API Base URL**: http://localhost:3000/api
|
|
- **Swagger Documentation**: http://localhost:3000/api/docs
|
|
- **Health Check**: http://localhost:3000/health
|
|
|
|
---
|
|
|
|
## 🔐 Default Login Credentials
|
|
|
|
After running `npm run seed:run`, you'll have these users:
|
|
|
|
| Role | Email | Password |
|
|
|------|-------|----------|
|
|
| **Admin** | admin@retailpos.com | Admin123! |
|
|
| **Manager** | manager@retailpos.com | Manager123! |
|
|
| **Cashier** | cashier@retailpos.com | Cashier123! |
|
|
|
|
---
|
|
|
|
## 🧪 Test Your Setup
|
|
|
|
### 1. **Check if server is running:**
|
|
```bash
|
|
curl http://localhost:3000/health
|
|
```
|
|
|
|
### 2. **Login to get JWT token:**
|
|
```bash
|
|
curl -X POST http://localhost:3000/api/auth/login \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"email": "admin@retailpos.com",
|
|
"password": "Admin123!"
|
|
}'
|
|
```
|
|
|
|
You'll get a response with an `access_token`. Copy it!
|
|
|
|
### 3. **Test an authenticated endpoint:**
|
|
```bash
|
|
curl http://localhost:3000/api/auth/profile \
|
|
-H "Authorization: Bearer YOUR_ACCESS_TOKEN_HERE"
|
|
```
|
|
|
|
### 4. **Or just use Swagger UI:**
|
|
Visit http://localhost:3000/api/docs and test all endpoints interactively!
|
|
|
|
---
|
|
|
|
## 🐳 Docker Option (Includes PostgreSQL)
|
|
|
|
If you prefer Docker and don't want to install PostgreSQL locally:
|
|
|
|
```bash
|
|
# Start only PostgreSQL (without Redis)
|
|
docker-compose up -d postgres
|
|
|
|
# Or start everything (PostgreSQL + Redis)
|
|
docker-compose up -d
|
|
```
|
|
|
|
Then follow steps 2-3 above.
|
|
|
|
---
|
|
|
|
## ❓ Common Issues
|
|
|
|
### **"Migration failed"**
|
|
- Make sure PostgreSQL is running
|
|
- Check your database credentials in `.env`
|
|
- Verify the database `retail_pos` exists
|
|
|
|
### **"Cannot connect to database"**
|
|
- Check if PostgreSQL is running: `psql -U postgres -c "SELECT 1;"`
|
|
- Verify `DB_HOST`, `DB_PORT`, `DB_USERNAME`, `DB_PASSWORD` in `.env`
|
|
|
|
### **Port 3000 already in use**
|
|
- Change `PORT=3001` in `.env` file
|
|
- Or stop the other service using port 3000
|
|
|
|
---
|
|
|
|
## 🎯 What About Redis?
|
|
|
|
**You don't need it for development!**
|
|
|
|
The app uses **in-memory caching** by default. Redis only provides:
|
|
- ✅ Persistent cache across server restarts
|
|
- ✅ Better performance for high-traffic production
|
|
|
|
To add Redis later (optional):
|
|
1. Install Redis: `brew install redis` (Mac) or `apt-get install redis` (Linux)
|
|
2. Start Redis: `redis-server`
|
|
3. The app will automatically use it (no code changes needed!)
|
|
|
|
---
|
|
|
|
## 📊 Database Commands
|
|
|
|
```bash
|
|
# Run migrations (create tables)
|
|
npm run migration:run
|
|
|
|
# Revert last migration
|
|
npm run migration:revert
|
|
|
|
# Seed database with sample data
|
|
npm run seed:run
|
|
|
|
# Generate new migration
|
|
npm run migration:generate -- src/database/migrations/MigrationName
|
|
|
|
# Create empty migration
|
|
npm run migration:create -- src/database/migrations/MigrationName
|
|
```
|
|
|
|
---
|
|
|
|
## 🛑 Stop the Server
|
|
|
|
Press `Ctrl + C` in the terminal where the server is running.
|
|
|
|
---
|
|
|
|
## 🎉 Next Steps
|
|
|
|
1. ✅ Test the API using Swagger UI
|
|
2. ✅ Connect your Flutter app to `http://localhost:3000/api`
|
|
3. ✅ Read `SETUP_COMPLETE.md` for detailed documentation
|
|
4. ✅ Customize categories and products via the API
|
|
|
|
**Happy coding!** 🚀
|