Install and Configuration

CrystalLens • First Install & Admin Setup

This guide walks you through installing CrystalLens for the first time and creating your initial system administrator account.

Prerequisites

• Python 3.10+
• Git
• (Optional) Ollama if using local LLM: https://ollama.com
• (Optional) Apify account + token for scraping: https://apify.com
• (Optional) Google API key if using Gemini

1) Clone and enter the project

git clone https://github.com/SecFathy/CrystalLens.git
cd CrystalLens

2) Create a virtual environment and install dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3) Configure environment

Copy the sample env file and edit as needed.

cp .env.example .env

Key variables in .env:

• DATABASE_URL (optional for dev; SQLite is fine)
• SECRET_KEY (set to a strong random value in production)
• APIFY_API_TOKEN (required for scraping)
• OLLAMA_API_URL, OLLAMA_MODEL (for local LLM)
• GOOGLE_API_KEY (for Gemini)
• ANALYSIS_PROVIDER (ollama or gemini — can also be set in Settings)

4) Seed an initial admin user

You can seed an admin via interactive prompts or via environment variables.

Interactive (prompts for username, email, password):

python scripts/seed_admin.py

Non‑interactive (environment variables):

export ADMIN_USERNAME="admin"
export ADMIN_EMAIL="admin@example.com"
export ADMIN_PASSWORD="change-this-strong-password"
python scripts/seed_admin.py
# Unset after seeding if desired
unset ADMIN_USERNAME ADMIN_EMAIL ADMIN_PASSWORD

The admin will be created with role system_admin.

5) Run CrystalLens

python run.py
# Open http://127.0.0.1:5000 in your browser

6) Configure providers and settings

• Log in with the admin account you just created.
• Go to Settings (navbar) → Analysis Settings.
  • Choose Provider: Ollama (local) or Gemini (cloud).
  • If Gemini: enter GOOGLE_API_KEY and click "Test Gemini".
  • Optionally set Single vs. Staged mode, assessment dimensions, and per‑section overrides.

7) Add employees and accounts

• Add Employees → Add Social Accounts (Twitter/Facebook profile URLs)
• Start Scraping from the Employee page
• After scraping completes, Start AI Analysis

Troubleshooting

• If login fails or redirects back to login: ensure admin exists (rerun seed script).
• If scraping fails: verify APIFY_API_TOKEN and Apify actor availability.
• If Ollama analysis fails: ensure ollama serve is running and the model is pulled (check /api/tags).
• If Gemini analysis fails: ensure GOOGLE_API_KEY is correct and Provider is set to Gemini in Settings.
• Check System (navbar) → System Status for quick diagnostics.

Security Tips (Production)

• Use PostgreSQL with a strong DATABASE_URL and TLS via reverse proxy.
• Set a strong SECRET_KEY and secure cookie/session settings.
• Keep .env and secrets out of version control (already .gitignored).
• Restrict admin access and review AuditLog regularly.

What’s Next

• See the README for roadmap, architecture, and provider notes.
• Open issues or PRs with improvements.