295e03feb4
All checks were successful
Build and Push App Image / build-and-push (push) Successful in 1m20s
152 lines
2.8 KiB
Markdown
152 lines
2.8 KiB
Markdown
# Quick Start
|
|
|
|
This guide covers the fastest way to run Notely and the current local-development workflow.
|
|
|
|
## Option 1: Docker Compose
|
|
|
|
From the repository root:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
docker compose up -d --build
|
|
```
|
|
|
|
Open:
|
|
|
|
- App UI: `http://localhost`
|
|
- Backend health endpoint: `http://localhost:8080/health`
|
|
- MongoDB: `localhost:27017`
|
|
- Redis: `localhost:6379`
|
|
|
|
Compose starts four services:
|
|
|
|
- `mongodb`
|
|
- `redis`
|
|
- `notely`
|
|
- `nginx`
|
|
|
|
## Option 2: Local Development
|
|
|
|
### 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
|
|
cp .env.example .env
|
|
go mod download
|
|
go run ./cmd/server/main.go
|
|
```
|
|
|
|
The backend listens on `http://localhost:8080` by default.
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
cd frontend
|
|
cp .env.example .env
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
The Vite dev server listens on `http://localhost:5173` and proxies `/api` to `http://localhost:8080`.
|
|
|
|
## Day-To-Day Commands
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
cd backend
|
|
go test ./...
|
|
go test -v ./tests/unit/...
|
|
go test -v ./tests/integration/...
|
|
```
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
cd frontend
|
|
npm run build
|
|
npm run lint
|
|
npm run test
|
|
```
|
|
|
|
## First Run Checklist
|
|
|
|
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.
|
|
|
|
## Useful Endpoints
|
|
|
|
Authentication:
|
|
|
|
- `POST /api/v1/auth/register`
|
|
- `POST /api/v1/auth/login`
|
|
- `POST /api/v1/auth/refresh`
|
|
- `GET /api/v1/auth/me`
|
|
|
|
Spaces:
|
|
|
|
- `GET /api/v1/spaces`
|
|
- `POST /api/v1/spaces`
|
|
- `PUT /api/v1/spaces/{spaceId}`
|
|
- `DELETE /api/v1/spaces/{spaceId}`
|
|
|
|
Notes:
|
|
|
|
- `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`
|
|
|
|
Public access:
|
|
|
|
- `GET /api/v1/public/spaces`
|
|
- `GET /api/v1/public/spaces/{spaceId}/notes`
|
|
|
|
## Troubleshooting
|
|
|
|
### Backend cannot connect to MongoDB
|
|
|
|
Check `MONGODB_URI` in your selected env file and make sure MongoDB is reachable.
|
|
|
|
### Backend cannot connect to Redis
|
|
|
|
Check `REDIS_ADDR`, `REDIS_PASSWORD`, and `REDIS_DB`. For local defaults, Redis should usually be reachable at `localhost:6379`.
|
|
|
|
### The browser cannot reach the API in local dev
|
|
|
|
Check:
|
|
|
|
- backend is running on port `8080`
|
|
- frontend and API are reachable through the same host/origin
|
|
- Vite proxy settings in `frontend/vite.config.js`
|
|
|
|
### OAuth callback redirects to the wrong URL
|
|
|
|
Check `FRONTEND_URL` in your selected env file.
|
|
|
|
### Permission-denied behavior is unclear
|
|
|
|
Read `PERMISSIONS.md` and then inspect the relevant backend service in `backend/internal/application/services/`.
|
|
|
|
## Related Docs
|
|
|
|
- `README.md`
|
|
- `ENV_SETUP.md`
|
|
- `PERMISSIONS.md`
|