notely/QUICKSTART.md

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:

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:

docker compose up -d mongodb redis

Backend

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

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

cd backend
go test ./...
go test -v ./tests/unit/...
go test -v ./tests/integration/...

Frontend

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