Skip to main content

Development Setup

This guide helps you set up a local development environment for the SEO Platform.

Prerequisites​

  • Python 3.13+
  • Node.js 18+
  • PostgreSQL 15+
  • Docker (optional, recommended)

Quick Setup with Docker​

# Clone the repository
git clone https://github.com/sebastianebg/seo-platform.git
cd seo-platform

# Copy environment file
cp .env.example .env

# Start services
docker-compose up -d

Manual Setup​

Backend​

# Install dependencies
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Run migrations
alembic upgrade head

# Start the server
uvicorn app.main:app --reload

Frontend​

# Install dependencies
cd frontend
npm install

# Start development server
npm run dev

Verify Installation​

Visit http://localhost:5173 to access the frontend and http://localhost:8000/docs for the API documentation.

Verification Checklist​

  • Frontend loads at http://localhost:5173
  • Backend API docs load at http://localhost:8000/docs
  • Database connection works (login page loads without errors)
  • Can create a test user account

Environment Configuration​

Required Environment Variables​

Create a .env file in the project root:

# Database
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/seo_platform

# Security
SECRET_KEY=your-secret-key-change-in-production

# OpenAI (for classification)
OPENAI_API_KEY=sk-your-api-key

# Optional
BACKEND_CORS_ORIGINS=["http://localhost:5173"]

Frontend Environment​

Create frontend/.env:

VITE_API_URL=http://localhost:8000

Troubleshooting​

Database Connection Issues​

Error: "Connection refused" or "Could not connect to database"

  1. Ensure PostgreSQL is running:

    # Check status
    sudo systemctl status postgresql

    # Start if needed
    sudo systemctl start postgresql

  2. Verify connection settings:

    psql -h localhost -U postgres -d seo_platform

  3. Check DATABASE_URL in .env matches your PostgreSQL configuration

Error: "Database does not exist"

Create the database:

createdb seo_platform
# or via psql
psql -U postgres -c "CREATE DATABASE seo_platform;"

Python/Backend Issues​

Error: "Module not found"

Ensure virtual environment is activated:

source .venv/bin/activate
# or on Windows
.venv\Scripts\activate

Error: "Python version mismatch"

Install Python 3.13 using pyenv:

pyenv install 3.13
pyenv local 3.13

Migration errors

Reset and rerun migrations:

alembic downgrade base
alembic upgrade head

Node.js/Frontend Issues​

Error: "npm install fails"

Clear npm cache and retry:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Error: "Port 5173 already in use"

Kill the existing process:

# Find process
lsof -i :5173
# Kill it
kill -9 <PID>

Or use a different port:

npm run dev -- --port 3000

Docker Issues​

Error: "Container fails to start"

Check container logs:

docker-compose logs backend
docker-compose logs db

Rebuild containers:

docker-compose down -v
docker-compose up --build

Error: "Port already allocated"

Stop conflicting services or change ports in docker-compose.yml.

OpenAI API Issues​

Error: "Invalid API key"

  1. Verify your API key at platform.openai.com
  2. Check the key is correctly set in .env: 
    echo $OPENAI_API_KEY

Error: "Rate limit exceeded"

Wait and retry, or upgrade your OpenAI plan for higher limits.

Getting Help​

If you're still having issues:

  1. Check existing GitHub Issues
  2. Search the documentation for your error message
  3. Open a new issue with:
    • Error message and stack trace
    • Operating system and versions
    • Steps to reproduce

Next Steps​