notely/ENV_SETUP.md

Environment Setup

Notely uses three different environment-file locations depending on how you run the app.

1. Root .env

Use the root .env file when running docker compose from the repository root.

Start from:

cp .env.example .env

Variables Used By Docker Compose

Required or commonly used:

• MONGODB_URI
• BACKEND_PORT
• JWT_SECRET
• ENCRYPTION_KEY
• FRONTEND_URL
• VITE_API_BASE_URL
• DEFAULT_ADMIN_EMAIL
• DEFAULT_ADMIN_USERNAME
• DEFAULT_ADMIN_PASSWORD
• NGINX_HTTP_PORT
• NGINX_HTTPS_PORT

Optional backend runtime values that Docker Compose will also pass through if present:

• REDIS_ADDR
• REDIS_USER
• REDIS_PASSWORD
• REDIS_DB
• SESSION_TTL_HOURS

Current Defaults In The Checked-In Example

• MongoDB container: mongodb://admin:password@mongodb:27017/noteapp?authSource=admin
• Backend port: 8080
• Public frontend URL: http://localhost
• Browser API base URL for container builds: http://localhost

2. backend/.env

Use backend/.env for local backend development.

Start from:

cd backend
cp .env.example .env

Variables Currently Read By The Backend Runtime

Read in backend/cmd/server/main.go or other active handlers:

• MONGODB_URI
• JWT_SECRET
• ENCRYPTION_KEY
• PORT
• REDIS_ADDR
• REDIS_USER
• REDIS_PASSWORD
• REDIS_DB
• SESSION_TTL_HOURS
• DEFAULT_ADMIN_EMAIL
• DEFAULT_ADMIN_USERNAME
• DEFAULT_ADMIN_PASSWORD
• FRONTEND_URL

Variables Present In backend/.env.example But Not Currently Consumed By Runtime Code

These values exist in the example file, but the current code path does not read them yet:

• JWT_ISSUER
• ENV
• LOG_LEVEL
• CORS_ALLOWED_ORIGINS
• RATE_LIMIT_REQUESTS
• RATE_LIMIT_WINDOW

Backend Defaults If A Variable Is Missing

• MONGODB_URI: mongodb://localhost:27017
• JWT_SECRET: your-secret-key-change-in-production
• ENCRYPTION_KEY: 00000000000000000000000000000000
• PORT: 8080
• REDIS_ADDR: localhost:6379
• REDIS_DB: 0
• SESSION_TTL_HOURS: 168
• FRONTEND_URL: falls back to http://localhost:5173 for login redirects

3. frontend/.env

Use frontend/.env for local frontend development.

Start from:

cd frontend
cp .env.example .env

Frontend Variables In frontend/.env.example

• VITE_API_BASE_URL
• VITE_ENV
• VITE_ENABLE_ANALYTICS

Variables Currently Relevant To The Frontend App

• VITE_API_BASE_URL: used by the API client

The other example values are safe to keep, but the current checked-in frontend code does not actively consume them.

Secret Generation

Examples:

openssl rand -base64 32
openssl rand -hex 16
openssl rand -hex 32

Use generated values for:

• JWT_SECRET
• ENCRYPTION_KEY
• provider secrets or other sensitive credentials stored through admin settings

Compose Vs Local Development

Use the right env file for the right mode:

• root .env: Docker Compose
• backend/.env: local backend
• frontend/.env: local frontend

Do not assume values from one location are automatically shared with the others.

Important Notes

• Do not commit real secrets
• Keep ENCRYPTION_KEY at 32 characters for the current AES-256 usage
• If OAuth login is enabled, set FRONTEND_URL correctly so callback redirects go to the intended UI
• If Redis settings are omitted, the backend assumes a local Redis instance at localhost:6379