first commit
This commit is contained in:
domrichardson
304
QUICKSTART.md
Normal file
304
QUICKSTART.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# 🚀 Quick Start Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker and Docker Compose (recommended for quickest setup)
|
||||
- OR: Go 1.21+, Node.js 18+, MongoDB 7.0+
|
||||
|
||||
## Option 1: Docker Compose (Recommended - 1 Command)
|
||||
|
||||
```bash
|
||||
# Clone/navigate to project
|
||||
cd noteapp
|
||||
|
||||
# Start everything
|
||||
docker-compose up
|
||||
|
||||
# Wait for services to initialize (~30 seconds)
|
||||
# Then open: http://localhost
|
||||
```
|
||||
|
||||
**Services running**:
|
||||
|
||||
- Notely: http://localhost:8080
|
||||
- MongoDB: localhost:27017
|
||||
- Nginx Reverse Proxy: http://localhost:80
|
||||
|
||||
**Test user (after startup)**:
|
||||
|
||||
- Register a new account at http://localhost/register
|
||||
- Login and create a Space
|
||||
- Add Categories and Notes
|
||||
|
||||
## Option 2: Local Development
|
||||
|
||||
### Backend Setup
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Copy environment file
|
||||
cp .env.example .env
|
||||
|
||||
# Install dependencies
|
||||
go mod download
|
||||
|
||||
# Ensure MongoDB is running
|
||||
# Docker: docker run -d -p 27017:27017 -e MONGO_INITDB_ROOT_USERNAME=admin \
|
||||
# -e MONGO_INITDB_ROOT_PASSWORD=password mongo:7.0-alpine
|
||||
|
||||
# Run backend
|
||||
go run ./cmd/server/main.go
|
||||
|
||||
# Logs should show: "Server starting on port 8080"
|
||||
```
|
||||
|
||||
### Frontend Setup
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Copy environment file
|
||||
cp .env.example .env
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Start dev server
|
||||
npm run dev
|
||||
|
||||
# Open: http://localhost:5173 in browser
|
||||
```
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### Backend Tests
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Run all tests
|
||||
go test ./...
|
||||
|
||||
# Run with verbose output
|
||||
go test -v ./...
|
||||
|
||||
# Run specific test
|
||||
go test -v -run TestRegisterUser ./tests/unit/...
|
||||
|
||||
# With coverage
|
||||
go test -cover ./...
|
||||
```
|
||||
|
||||
### Frontend Tests
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Run tests
|
||||
npm run test
|
||||
|
||||
# Watch mode
|
||||
npm run test:watch
|
||||
|
||||
# Coverage
|
||||
npm run test:coverage
|
||||
```
|
||||
|
||||
## 📝 Key API Endpoints
|
||||
|
||||
### Authentication
|
||||
|
||||
```bash
|
||||
# Register
|
||||
curl -X POST http://localhost:8080/api/v1/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"email": "user@example.com",
|
||||
"username": "myuser",
|
||||
"password": "SecurePassword123",
|
||||
"password_confirm": "SecurePassword123",
|
||||
"first_name": "John",
|
||||
"last_name": "Doe"
|
||||
}'
|
||||
|
||||
# Login
|
||||
curl -X POST http://localhost:8080/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"email": "user@example.com",
|
||||
"password": "SecurePassword123"
|
||||
}'
|
||||
|
||||
# Response contains: access_token, refresh_token, user data
|
||||
```
|
||||
|
||||
### Create Space
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/spaces \
|
||||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "My First Space",
|
||||
"description": "Notes for my project",
|
||||
"icon": "📚",
|
||||
"is_public": false
|
||||
}'
|
||||
```
|
||||
|
||||
### Create Note
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/spaces/{spaceId}/notes \
|
||||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"title": "My First Note",
|
||||
"content": "# Markdown Heading\n\nThis is a note",
|
||||
"tags": ["important", "work"],
|
||||
"category_id": null,
|
||||
"is_pinned": false,
|
||||
"is_favorite": true
|
||||
}'
|
||||
```
|
||||
|
||||
### Search Notes
|
||||
|
||||
```bash
|
||||
curl "http://localhost:8080/api/v1/spaces/{spaceId}/notes/search?q=important" \
|
||||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
||||
```
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### MongoDB Connection Error
|
||||
|
||||
```
|
||||
Error: Failed to connect to database
|
||||
|
||||
Solution:
|
||||
docker run -d -p 27017:27017 \
|
||||
-e MONGO_INITDB_ROOT_USERNAME=admin \
|
||||
-e MONGO_INITDB_ROOT_PASSWORD=password \
|
||||
mongo:7.0-alpine
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
```bash
|
||||
# Find process on port 8080
|
||||
lsof -i :8080
|
||||
|
||||
# Kill it
|
||||
kill -9 <PID>
|
||||
|
||||
# Or use different port
|
||||
PORT=8081 go run ./cmd/server/main.go
|
||||
```
|
||||
|
||||
### CORS Errors
|
||||
|
||||
Make sure frontend and backend URLs match in:
|
||||
|
||||
- Frontend: `VITE_API_BASE_URL` in `.env`
|
||||
- Backend: `CORS_ALLOWED_ORIGINS` in `.env`
|
||||
|
||||
### MongoDB Auth Failed
|
||||
|
||||
If using Docker Compose:
|
||||
|
||||
- Username: `admin`
|
||||
- Password: `password`
|
||||
- Connection string includes `?authSource=admin`
|
||||
|
||||
## 📚 Project Structure
|
||||
|
||||
```
|
||||
noteapp/
|
||||
├── backend/ # Go REST API
|
||||
│ ├── cmd/server/ # Entry point
|
||||
│ ├── internal/
|
||||
│ │ ├── domain/ # Business logic
|
||||
│ │ ├── application/ # Services & DTOs
|
||||
│ │ ├── infrastructure/ # DB, auth, security
|
||||
│ │ └── interfaces/ # HTTP handlers
|
||||
│ ├── tests/ # Test files
|
||||
│ ├── go.mod & go.sum # Dependencies
|
||||
│ └── README.md
|
||||
│
|
||||
├── frontend/ # Vue 3 SPA
|
||||
│ ├── src/
|
||||
│ │ ├── components/ # UI components
|
||||
│ │ ├── pages/ # Page components
|
||||
│ │ ├── stores/ # Pinia state
|
||||
│ │ ├── services/ # API client
|
||||
│ │ ├── router/ # Vue Router
|
||||
│ │ ├── assets/ # Styles & images
|
||||
│ │ └── main.js # Entry point
|
||||
│ ├── tests/ # Test files
|
||||
│ ├── package.json # Dependencies
|
||||
│ └── vite.config.js # Vite configuration
|
||||
│
|
||||
├── devops/
|
||||
│ ├── docker/
|
||||
│ │ ├── Dockerfile.backend
|
||||
│ │ ├── Dockerfile.frontend
|
||||
│ │ └── nginx.conf
|
||||
│ └── kubernetes/
|
||||
│ └── deployment.yaml
|
||||
│
|
||||
├── docker-compose.yml # Local development setup
|
||||
├── README.md # Project docs
|
||||
├── ARCHITECTURE.md # Architecture overview
|
||||
├── SECURITY.md # Security implementation
|
||||
└── ENV_SETUP.md # Environment configuration
|
||||
```
|
||||
|
||||
## 🎓 Learning Resources
|
||||
|
||||
### Understanding the Code
|
||||
|
||||
1. **Start here**: `ARCHITECTURE.md` - Clean architecture pattern
|
||||
2. **Then read**: Backend `domain/entities/*.go` - Core models
|
||||
3. **Next**: Backend `application/services/*.go` - Business logic
|
||||
4. **UI**: Frontend `src/stores/authStore.js` - State management
|
||||
5. **API**: Backend `interfaces/handlers/*.go` - HTTP layer
|
||||
|
||||
### Security Deep Dive
|
||||
|
||||
See `SECURITY.md` for:
|
||||
|
||||
- Password hashing (Argon2id)
|
||||
- JWT authentication
|
||||
- Authorization (RBAC)
|
||||
- Input validation
|
||||
- XSS prevention
|
||||
- CSRF protection
|
||||
|
||||
## 🚀 Next Steps
|
||||
|
||||
1. **Explore the UI**: Create spaces, notes, categories
|
||||
2. **Read the code**: Start with `index ARCHITECTURE.md`
|
||||
3. **Run tests**: `go test ./...` and `npm test`
|
||||
4. **Deploy**: Use `docker-compose.yml` or Kubernetes
|
||||
5. **Extend**: Add OAuth2, WebSockets, more features
|
||||
|
||||
## 💡 Quick Tips
|
||||
|
||||
- **Hot reload**: Changes auto-reload in dev mode
|
||||
- **Network tab**: Check API calls in browser DevTools
|
||||
- **Logs**: Docker: `docker-compose logs -f service-name`
|
||||
- **Database GUI**: MongoDB Compass (free tool to browse data)
|
||||
- **API testing**: Postman or `curl` commands
|
||||
|
||||
## 📞 Support
|
||||
|
||||
- Check logs: `docker-compose logs`
|
||||
- Review `SECURITY.md` for auth issues
|
||||
- Check `ENV_SETUP.md` for config problems
|
||||
- See `ARCHITECTURE.md` for code structure
|
||||
|
||||
---
|
||||
|
||||
**Now you're ready to explore and extend Notely! 🎉**
|
||||
Reference in New Issue
Block a user