[Feature Request]: Add Browser-Based Onboarding Wizard to Replace Manual .env Configuration

[divyanshim27]

Summary

Arachnode requires users to manually copy .env.example to .env and fill in up to 9 environment variables before the system runs correctly. For new contributors or first-time users, this is a significant friction point — especially variables like OLLAMA_BASE_URL, GMAIL_APP_PASSWORD, and JOBSEEKER_STACK which are non-obvious and poorly explained inline. The system currently has no guided setup experience. Adding a first-run onboarding wizard accessible at http://localhost:8080/setup would dramatically reduce the time-to-first-successful-crawl.

Problem

• The CONTRIBUTING.md and README.md describe manual .env editing as the setup path, with no validation that the values are correct until a runtime error occurs.
• Common first-run failures: missing GMAIL_APP_PASSWORD, wrong OLLAMA_BASE_URL format (especially on Windows where host.docker.internal differs), empty JOBSEEKER_ROLE causing spiders to return zero results.
• The Makefile provides make reset but no make setup — there is no guided initialization path.
• New GSSoC contributors who want to test the system locally often give up at the configuration stage.

Impact

• Higher contributor dropout rate at the setup stage.
• Repeated setup-related issues filed that drain maintainer time.
• The onboarding friction prevents meaningful dogfooding of the tool.

Proposed Solution

I would like to implement a first-run setup wizard served by the gateway:

Detection logic:

# gateway/main.py
import os

@app.get("/")
async def root():
    if not os.path.exists(".env") or not os.getenv("POSTGRES_USER"):
        return RedirectResponse("/setup")
    return FileResponse("dashboard.html")

Setup wizard — gateway/setup.html:

Step 1 — Job Preferences:

<label>Job Role (e.g., Backend Engineer)</label>
<input id="role" placeholder="Backend Engineer" />
<label>Tech Stack (comma-separated, e.g., Python,FastAPI)</label>
<input id="stack" placeholder="Python,FastAPI,PostgreSQL" />

Step 2 — Email Configuration:

<label>Gmail Address (optional — for sending applications)</label>
<input id="gmail" type="email" />
<label>Gmail App Password</label>
<input id="gmail_pass" type="password" />
<a href="https://support.google.com/accounts/answer/185833" target="_blank">
  How to generate an App Password →
</a>

Step 3 — Ollama (optional):

<input id="ollama_url" value="http://host.docker.internal:11434" />
<button onclick="testOllama()">Test Connection</button>
<span id="ollama_status"></span>

Step 4 — Write .env file:

# gateway/routes/setup.py
@app.post("/api/setup/save")
async def save_config(config: SetupConfig):
    env_content = f"""
POSTGRES_USER=jobuser
POSTGRES_PASSWORD=jobpass
POSTGRES_DB=jobsdb
JOBSEEKER_ROLE={config.role}
JOBSEEKER_STACK={config.stack}
GMAIL_ADDRESS={config.gmail or ''}
GMAIL_APP_PASSWORD={config.gmail_pass or ''}
OLLAMA_BASE_URL={config.ollama_url}
"""
    with open(".env", "w") as f:
        f.write(env_content.strip())
    return {"status": "saved", "redirect": "/"}

Deliverables

• gateway/setup.html — 4-step wizard with inline help text and validation.
• gateway/routes/setup.py — config save route + Ollama connectivity test endpoint.
• First-run detection in gateway/main.py.
• Makefile target: make setup that opens http://localhost:8080/setup in the browser.
• Documentation update in README.md and CONTRIBUTING.md replacing manual .env instructions with "run make setup".

Labels: enhancement, developer-experience, onboarding, good first issue, GSSoC 2026

Could you assign this issue to me?

[divyanshim27]

Hey @sharmavaibhav31,
Please assign to me under GSSoC 2026.
/claim /assign /claim-assignment

[anshul23102]

Hi @sharmavaibhav31, excellent UX feature! Adding a browser-based onboarding wizard to replace manual .env configuration would greatly improve the setup experience for new users.

Would it be possible to assign this to me? I'm prepared to build an interactive onboarding interface.

Looking forward to contributing! 🧙