# 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 `VITE_API_BASE_URL`
- 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`