Skip to main content
This guide covers local development setup and Docker deployment for Routine Optimizer.

​
Prerequisites

Before you begin, ensure you have the following installed:
SoftwareVersionRequiredNotes
Node.js20.x or higherYesRequired for Vite and development
npm10.x or higherYesPackage manager
Git2.x or higherYesVersion control
Docker24.x or higherOptionalFor containerized deployment
This project uses Node.js 20+ for modern JavaScript features and optimal Vite performance. Earlier versions may cause compatibility issues.

​
Quick Start (Local Development)

Get Routine Optimizer running on your local machine in minutes.
1

Clone the repository

git clone https://github.com/Haplee/estudio.git
cd estudio
2

Install dependencies

npm install
Installation typically takes 30-60 seconds depending on your internet connection.
3

Configure environment variables

Create a .env file in the root directory by copying the example:
cp .env.example .env
Edit .env with your configuration:
.env
# ===== SUPABASE (Required) =====
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=eyJxxxxxxxxxxxx
VITE_APP_URL=http://localhost:5173

# ===== AI COACH (Optional but recommended) =====
GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxx
PORT=3001

# ===== ENVIRONMENT =====
NODE_ENV=development
Never expose GROQ_API_KEY to the client! This key is only used server-side in the Vercel serverless function at /api/ai.ts.
See Environment Variables for detailed configuration.
4

Set up Supabase

  1. Create a project at supabase.com
  2. Navigate to SQL Editor in your Supabase dashboard
  3. Copy the entire content of supabase/schema.sql from the repository
  4. Execute the SQL script to create tables, types, and RLS policies
  5. Get your credentials from Project Settings → API:
    • Copy Project URL to VITE_SUPABASE_URL
    • Copy anon public key to VITE_SUPABASE_ANON_KEY
The schema includes Row Level Security (RLS) policies to protect user data automatically.
For detailed Supabase setup, see Supabase Setup Guide.
5

Set up Groq API (optional)

The AI Coach feature requires a Groq API key for Llama 3 inference:
  1. Create a free account at console.groq.com
  2. Navigate to API Keys and create a new key
  3. Add the key to your .env file as GROQ_API_KEY
Groq’s free tier provides fast inference with rate limits. The AI Coach will be disabled if no API key is provided.
6

Start the development server

npm run dev
The app will be available at http://localhost:5173
The dev server includes hot module replacement (HMR). Changes to your code will reflect instantly without page reload.
7

Verify the installation

  1. Open http://localhost:5173 in your browser
  2. You should see the login/register screen
  3. Create a test account
  4. Complete the onboarding flow
  5. Check that you can access the dashboard
If you encounter issues, see Troubleshooting below.

​
Docker Deployment

Run Routine Optimizer in a production-ready Docker container with Nginx.
Docker deployment is production-ready and includes multi-stage builds with optimized assets.

​
Using Docker Compose

1

Navigate to the project root

cd estudio
2

Build the production image

Pass your environment variables as build arguments:
docker-compose --profile prod build \
  --build-arg VITE_SUPABASE_URL=https://your-project.supabase.co \
  --build-arg VITE_SUPABASE_ANON_KEY=your_anon_key \
  --build-arg VITE_APP_URL=https://yourdomain.com
Important: Vite environment variables (prefixed with VITE_) must be passed at build time, not runtime. They are embedded into the JavaScript bundle.
3

Start the container

docker-compose --profile prod up -d
The app will be available at http://localhost:8080
4

View logs

docker-compose logs -f app-prod
5

Stop the container

docker-compose --profile prod down

​
Using the Management Script

Routine Optimizer includes helper scripts for Docker management: 
./scripts/manage.sh
The script provides an interactive menu:
  1. Launch Application - Build and start the container
  2. Stop Application - Stop and remove containers
  3. View Logs - Monitor container logs
  4. Clean Build - Remove all Docker artifacts and rebuild
  5. Exit
The management script automatically detects your environment variables from .env and passes them to Docker.

​
Dockerfile Architecture

The Dockerfile uses a multi-stage build for optimal image size:
Dockerfile
# Stage 1: Build the app
FROM node:20-alpine as build

WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY src ./src
COPY public ./public
COPY api ./api
COPY index.html tsconfig.* vite.config.ts postcss.config.js tailwind.config.js eslint.config.js ./

# Environment variables passed as build args
ARG VITE_SUPABASE_URL
ARG VITE_SUPABASE_ANON_KEY
ARG VITE_APP_URL
ENV VITE_SUPABASE_URL=$VITE_SUPABASE_URL
ENV VITE_SUPABASE_ANON_KEY=$VITE_SUPABASE_ANON_KEY
ENV VITE_APP_URL=$VITE_APP_URL

RUN npm run build

# Stage 2: Serve with Nginx
FROM nginxinc/nginx-unprivileged:alpine

COPY --from=build /app/dist /usr/share/nginx/html
COPY --chown=nginx:nginx deploy/docker/nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 8080

CMD ["nginx", "-g", "daemon off;"]

​
Available Scripts

The project includes several npm scripts for development and testing:
CommandDescription
npm run devStart development server with Vite and ngrok
npm run buildBuild for production
npm run previewPreview production build locally
npm run lintRun ESLint code analysis
npm testRun Vitest test suite
npm run shareShare local server via ngrok tunnel
Use npm run share to test the PWA on mobile devices during development. Ngrok creates a public URL for your local server.

​
Troubleshooting

Symptoms: Login fails, or you see “Unable to connect to database”Solutions:
  1. Verify VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY in your .env
  2. Ensure you’ve run the supabase/schema.sql script
  3. Check that your Supabase project is active
  4. Verify API access is enabled in Supabase settings
Symptoms: AI Coach shows error or doesn’t respondSolutions:
  1. Verify GROQ_API_KEY is set in your .env
  2. Check Groq API rate limits at console.groq.com
  3. Ensure the Vercel serverless function is deployed (for production)
  4. Check browser console for API errors
  5. Disable ad-blockers that may block API requests
Symptoms: Container runs but shows blank pageSolutions:
  1. Ensure you passed --build-arg for all VITE_* variables during build
  2. Rebuild the image from scratch: docker-compose build --no-cache
  3. Check browser console for JavaScript errors
  4. Verify nginx configuration in deploy/docker/nginx.conf
Symptoms: ERR_OSSL_EVP_UNSUPPORTED or similar OpenSSL errorsSolutions:
  1. Upgrade to Node.js 20.x or higher
  2. Use nvm to manage Node versions: 
    nvm install 20
nvm use 20
  3. Verify version: node --version
Symptoms: Timer completes but doesn’t play notification soundSolutions:
  1. Check that /public/notification.mp3 exists
  2. Verify audio is enabled in Settings → Study Preferences
  3. Ensure browser tab is not muted
  4. Interact with the page before starting (browsers block autoplay audio)
  5. Check browser audio permissions
Symptoms: Changes don’t appear after pushing to productionSolutions:
  1. Hard refresh: Ctrl + F5 (Windows) or Cmd + Shift + R (Mac)
  2. Go to Settings → Check for Updates in the app
  3. Unregister service worker in browser DevTools → Application → Service Workers
  4. Clear browser cache and reload
Symptoms: Google/GitHub login fails with redirect errorSolutions:
  1. Go to Supabase dashboard → Authentication → Providers
  2. Add your VITE_APP_URL to allowed redirect URLs
  3. For production, add your production domain
  4. Ensure URL includes protocol (https:// or http://)
Symptoms: Errors when creating calendar events or tasksSolutions:
  1. Ensure you ran the complete supabase/schema.sql script
  2. The script includes custom ENUM types that must be created
  3. Re-run the schema script in Supabase SQL Editor
  4. Check for SQL execution errors in Supabase logs

​
Next Steps

Environment Variables

Complete reference for all configuration options.

Supabase Setup

Detailed guide for database configuration and RLS policies.

Docker Deployment

Advanced Docker configuration and optimization.

Deploy to Vercel

Deploy to production with Vercel’s serverless platform.
For local development help, see the Architecture documentation or review the docs/ folder in the repository.

Build docs developers (and LLMs) love

Get started for freeTalk to us