Installation Guide

This guide will walk you through installing Tarefa AI on your local machine for development.

System Requirements

Before you begin, ensure your system meets these requirements:

Node.js

Version 20 or higher

Docker

For PostgreSQL database

npm/pnpm

Package manager

Git

For version control

Step 1: Clone the Repository

git clone https://github.com/your-username/tarefa-ai.git
cd tarefa-ai

Step 2: Install Dependencies

Using npm:

npm install

Using pnpm (recommended):

pnpm install

Note

The installation may take 2-3 minutes depending on your internet connection.

Step 3: Set Up Environment Variables

Copy the example environment file:

cp .env.example .env.local

Open .env.local and configure the following:

Required Variables

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5433/claude_scheduler"
 
# Encryption Key (generate with: openssl rand -hex 32)
ENCRYPTION_KEY="your-64-character-hex-key"
 
# OpenRouter AI API
OPENROUTER_API_KEY="sk-or-v1-your-key"
NEXT_PUBLIC_OPENROUTER_API_KEY="sk-or-v1-your-key"

Optional Variables (for advanced features)

# Email Notifications (Resend)
RESEND_API_KEY="re_your-key"
 
# WhatsApp (Evolution API)
EVOLUTION_API_URL="https://your-server.com"
EVOLUTION_API_KEY="your-api-key"
EVOLUTION_INSTANCE="instance-name"
 
# Notion Integration
NOTION_API_KEY="ntn_your-key"
 
# Figma Integration
FIGMA_ACCESS_TOKEN="figd_your-token"

Warning

Never commit your .env.local file to version control. It contains sensitive credentials.

Step 4: Generate Encryption Key

Generate a secure encryption key for API key storage:

openssl rand -hex 32

Copy the output and paste it as ENCRYPTION_KEY in your .env.local file.

Step 5: Start PostgreSQL Database

Start the PostgreSQL database using Docker Compose:

docker-compose up -d

Verify the database is running:

docker-compose ps

You should see the postgres container running.

Tip

To view database logs: docker-compose logs -f postgres

Step 6: Run Database Migrations

Apply the database schema:

npm run db:push

Apply the admin panel migration:

npx tsx scripts/apply-admin-migration.ts

Success

You should see confirmation messages indicating successful table creation.

Step 7: Seed Initial Data (Optional)

Populate the database with demo data:

npm run db:seed

This creates:

Demo user account
Sample scheduled tasks
Test API credentials

Step 8: Start Development Server

Start both the Next.js app and the scheduler worker:

npm run dev:full

Or start them separately:

# Terminal 1: Next.js app
npm run dev
 
# Terminal 2: Scheduler worker
npm run scheduler

Success

The application is now running at http://localhost:3000

Step 9: Access the Application

Open your browser and navigate to:

Dashboard: http://localhost:3000/dashboard
Admin Panel: http://localhost:3000/admin
API Health Check: http://localhost:3000/api/health

Default Admin Credentials

Email: satoshimemes79@gmail.com
Password: (use your local auth password)

Verify Installation

Run these commands to ensure everything is working:

# Check TypeScript compilation
npm run type-check
 
# Run linter
npm run lint
 
# Run tests
npm test
 
# Test build
npm run build

Database Management Tools

Drizzle Studio

Drizzle Studio provides a GUI for database management:

npm run db:studio

Opens at http://localhost:4983

PostgreSQL CLI

Connect to the database directly:

docker-compose exec postgres psql -U postgres -d claude_scheduler

Troubleshooting

Port 3000 already in use

# Find and kill process on port 3000
lsof -ti:3000 | xargs kill -9

Docker connection refused

# Restart Docker containers
docker-compose down
docker-compose up -d

Database migration errors

# Reset database (WARNING: deletes all data)
docker-compose down -v
docker-compose up -d
npm run db:push

Module not found errors

# Clear cache and reinstall
rm -rf node_modules .next
npm install

Next Steps

Now that you have Tarefa AI installed, you can:

Configure API Keys

Set up OpenRouter and notification services

Learn more

Create First Task

Learn how to create and schedule AI tasks

Learn more

Explore Features

Discover all platform capabilities

Learn more

Deploy to Production

Deploy your instance to Vercel

Learn more

Development Workflow

Recommended workflow for development:

Start database: docker-compose up -d
Run dev server: npm run dev:full
Make changes (hot reload enabled)
Test changes locally
Run linter: npm run lint
Commit changes

Additional Resources

Continue to Configuration →