Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Improve Local Setup Documentation: Add Clear Steps for API Keys & Python Virtual Environment

Aperta
  • Qualcosa non va?
#178 3 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

@vinayak302004 ci sta già lavorando.

Dal 3/12/2025.

  • #215 di @vinayak302004 — aperta

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
55/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Ferma
Stack tecnologico
fastapi, postgresql, python, supabase
Ambito
backend, database, documentation

Direzione di ricerca

Leggi prima le istruzioni attuali per la configurazione in README.md e backend/.env.example, quindi documenta nel README i passaggi per la chiave API locale, le credenziali Supabase PostgreSQL e l’ambiente virtuale Python. Aggiorna l’esempio dell’ambiente con le variabili e i commenti elencati e verifica che le istruzioni coprano il percorso di configurazione richiesto per i nuovi collaboratori.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Is this related to an existing part of the documentation?
  • Yes, it is related to an existing section
What needs to be updated?

Title: Improve Local Setup Documentation: Add Clear Steps for API Keys & Python Virtual Environment

Describe the Problem

The current README.md provides basic setup instructions (cloning, installing dependencies, running servers), but critical onboarding steps are missing or incomplete, making it difficult for new contributors (especially beginners) to run the project locally.

Missing or Unclear Parts

  1. API Key Setup (GEMINI_API_KEY, YOUTUBE_API_KEY, GROQ_API_KEY)

    • The .env.example lists these keys, but there are no instructions on how to obtain them.
    • No links, steps, or free-tier details — users get stuck at the .env stage.

  2. Supabase Database Credentials (host, password, etc.)

    • While Supabase URL and anon key are mentioned, the PostgreSQL connection string breakdown (host, password, port, etc.) is not explained.
    • Users don’t know where to find these in the Supabase dashboard.

  3. Python Virtual Environment (venv) for FastAPI Backend

    • The README says pip install -r requirements.txt, but does not recommend or explain using a virtual environment.
    • This leads to dependency conflicts, especially on shared machines or with multiple Python projects.

These gaps increase friction for first-time contributors and reduce project accessibility.

Suggested Solution

Add a new “Local Development Setup” section to README.md with clear, step-by-step instructions and a properly formatted table for API keys.

1. API Keys Table (place under “Environment Variables” or a new heading)
Create a `.env` file in `backend/app/` (copy from `.env.example`). Fill the values below:

| Variable               | Service                     | How to Obtain |
|------------------------|-----------------------------|---------------|
| `GROQ_API_KEY`         | [Groq](https://console.groq.com) | 1. Go to [console.groq.com](https://console.groq.com)<br>2. Sign up / log in<br>3. **API Keys → Create API Key**<br>4. Copy the key (`gsk_…`) |
| `GEMINI_API_KEY`       | [Google AI Studio](https://aistudio.google.com) | 1. Visit [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey)<br>2. Sign in with Google<br>3. **Create API key**<br>4. Copy the key |
| `YOUTUBE_API_KEY`      | [Google Cloud Console](https://console.cloud.google.com) | 1. Go to [console.cloud.google.com](https://console.cloud.google.com)<br>2. Create a new project (e.g., “InPact-YouTube”)<br>3. Enable **YouTube Data API v3**<br>4. **Credentials → Create Credentials → API key** |
| `SUPABASE_URL` & `SUPABASE_KEY` | [Supabase](https://supabase.com) | 1. Go to [supabase.com/dashboard](https://supabase.com/dashboard)<br>2. Create a new project<br>3. **Settings → API** → copy **Project URL** and **anon public** key |
| `host`, `password`     | Supabase PostgreSQL        | In Supabase: **Settings → Database** → copy **Host** and the **Database password** you set during project creation |

Note: All services have free tiers sufficient for local development.

2. Python Virtual Environment (Recommended)

To avoid dependency conflicts:

# In project root or backend/
python -m venv venv

# Activate
# Windows:
venv\Scripts\activate
# macOS / Linux:
source venv/bin/activate

# Install backend deps (with venv active)
pip install -r backend/requirements.txt

Note : Always activate the venv before running uvicorn

3. Update .env.example (Optional but Helpful)

Ensure backend/.env.example includes all required keys with comments:

# Supabase DB
user=postgres
password=YOUR_DB_PASSWORD
host=YOUR_PROJECT.supabase.co
port=5432
dbname=postgres

# API Keys
GROQ_API_KEY=your_groq_key_here
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key
GEMINI_API_KEY=your-gemini-key
YOUTUBE_API_KEY=your-youtube-key

Additional Context

  • Date & Time: November 16, 2025, 10:01 AM IST
  • Location: India (IN)
  • Fork: SunilBaghel002/InPactAI
  • OS Tested: Windows 11 (also verified on Ubuntu 24.04 via WSL)
  • Contributor: First-time open-source contributor — eager to improve onboarding for the global community!
  • Motivation: I spent ~45 minutes just figuring out API keys and venv setup. Clear docs would have saved me (and others) hours.

Impact

Before After
New contributors get stuck at .env → give up Setup time drops from ~1 hour → ~10 minutes
Dependency conflicts break local runs Isolated venv = zero conflicts
No guidance on free-tier limits Confidence that free tiers are enough for dev
High barrier for non-US/English users Step-by-step + India-localized time = inclusive

Result:

  • More pull requests from beginners (especially from India & APAC timezones)
  • Faster project growth
  • Lower maintainer support load (fewer “how do I get X key?” issues)

Happy to open a PR with these exact changes — just let me know!

Relevant Documentation Link (if any)

No response

Record
  • I agree to follow this project's Code of Conduct
  • I want to work on this update
Lingua principale
TypeScript
Stelle
101
Fork
145
Merge medio
32m
PR unite (30g)
2

Preparare l'ambiente

  • Nessun Dockerfile né file Docker Compose
  • Ha un modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di AOSSIE-Org/InPactAI

Tutte le issue di AOSSIE-Org/InPactAI

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.