HostXtra/notely
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Updated admin panel providers list & modal

Browse Source
This commit is contained in:
domrichardson
2026-03-26 16:27:14 +00:00
parent 9cf71ab4a0
commit 005a8f4cf0
40 changed files with 2391 additions and 1051 deletions
Download Patch File Download Diff File Expand all files Collapse all files

323
QUICKSTART.md
View File

@@ -1,304 +1,151 @@
# 🚀 Quick Start Guide
# Quick Start
## Prerequisites
This guide covers the fastest way to run Notely and the current local-development workflow.
- Docker and Docker Compose (recommended for quickest setup)
- OR: Go 1.21+, Node.js 18+, MongoDB 7.0+
## Option 1: Docker Compose
## Option 1: Docker Compose (Recommended - 1 Command)
From the repository root:
```bash
# Clone/navigate to project
cd noteapp
# Start everything
docker-compose up
# Wait for services to initialize (~30 seconds)
# Then open: http://localhost
cp .env.example .env
docker compose up -d --build
```
**Services running**:
Open:
- Notely: http://localhost:8080
- MongoDB: localhost:27017
- Nginx Reverse Proxy: http://localhost:80
- App UI: `http://localhost`
- Backend health endpoint: `http://localhost:8080/health`
- MongoDB: `localhost:27017`
- Redis: `localhost:6379`
**Test user (after startup)**:
Compose starts four services:
- Register a new account at http://localhost/register
- Login and create a Space
- Add Categories and Notes
- `mongodb`
- `redis`
- `notely`
- `nginx`
## Option 2: Local Development
### Backend Setup
### Prerequisites
- Go 1.25+
- Node.js 18+
- MongoDB
- Redis
If you do not already have MongoDB and Redis running locally, you can start just those services with Docker Compose:
```bash
docker compose up -d mongodb redis
```
### Backend
```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
The backend listens on `http://localhost:8080` by default.
### Frontend
```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
The Vite dev server listens on `http://localhost:5173` and proxies `/api` to `http://localhost:8080`.
### Backend Tests
## Day-To-Day Commands
### Backend
```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 ./...
go test -v ./tests/unit/...
go test -v ./tests/integration/...
```
### Frontend Tests
### Frontend
```bash
cd frontend
# Run tests
npm run build
npm run lint
npm run test
# Watch mode
npm run test:watch
# Coverage
npm run test:coverage
```
## 📝 Key API Endpoints
## First Run Checklist
### Authentication
1. Register a user or set `DEFAULT_ADMIN_*` values in your env file before startup.
2. Sign in.
3. Create a space.
4. Create categories and notes.
5. Use the top search bar to verify note search.
```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"
}'
## Useful Endpoints
# Login
curl -X POST http://localhost:8080/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePassword123"
}'
Authentication:
# Response contains: access_token, refresh_token, user data
```
- `POST /api/v1/auth/register`
- `POST /api/v1/auth/login`
- `POST /api/v1/auth/refresh`
- `GET /api/v1/auth/me`
### Create Space
Spaces:
```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
}'
```
- `GET /api/v1/spaces`
- `POST /api/v1/spaces`
- `PUT /api/v1/spaces/{spaceId}`
- `DELETE /api/v1/spaces/{spaceId}`
### Create Note
Notes:
```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
}'
```
- `GET /api/v1/spaces/{spaceId}/notes`
- `POST /api/v1/spaces/{spaceId}/notes`
- `GET /api/v1/spaces/{spaceId}/notes/search?q=<query>`
- `POST /api/v1/spaces/{spaceId}/notes/{noteId}/unlock`
### Search Notes
Public access:
```bash
curl "http://localhost:8080/api/v1/spaces/{spaceId}/notes/search?q=important" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
- `GET /api/v1/public/spaces`
- `GET /api/v1/public/spaces/{spaceId}/notes`
## 🔍 Troubleshooting
## Troubleshooting
### MongoDB Connection Error
### Backend cannot connect to MongoDB
```
Error: Failed to connect to database
Check `MONGODB_URI` in your selected env file and make sure MongoDB is reachable.
Solution:
docker run -d -p 27017:27017 \
-e MONGO_INITDB_ROOT_USERNAME=admin \
-e MONGO_INITDB_ROOT_PASSWORD=password \
mongo:7.0-alpine
```
### Backend cannot connect to Redis
### Port Already in Use
Check `REDIS_ADDR`, `REDIS_PASSWORD`, and `REDIS_DB`. For local defaults, Redis should usually be reachable at `localhost:6379`.
```bash
# Find process on port 8080
lsof -i :8080
### The browser cannot reach the API in local dev
# Kill it
kill -9 <PID>
Check:
# Or use different port
PORT=8081 go run ./cmd/server/main.go
```
- backend is running on port `8080`
- frontend `VITE_API_BASE_URL`
- Vite proxy settings in `frontend/vite.config.js`
### CORS Errors
### OAuth callback redirects to the wrong URL
Make sure frontend and backend URLs match in:
Check `FRONTEND_URL` in your selected env file.
- Frontend: `VITE_API_BASE_URL` in `.env`
- Backend: `CORS_ALLOWED_ORIGINS` in `.env`
### Permission-denied behavior is unclear
### MongoDB Auth Failed
Read `PERMISSIONS.md` and then inspect the relevant backend service in `backend/internal/application/services/`.
If using Docker Compose:
## Related Docs
- 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! 🎉**
- `README.md`
- `ENV_SETUP.md`
- `PERMISSIONS.md`