Docs / Start

Getting started

From clone to first scan in five steps. Docker Compose is the recommended path; a local (non-Docker) setup is below for development.

Prerequisites

Docker + Docker Compose on the target machine
git available on PATH
A GitHub Personal Access Token with repo or read:org scope (optional — required for private repos)

1 · Clone and configure

git clone https://github.com/YOUR_USERNAME/perryscope.git
cd perryscope
cp backend/.env.example backend/.env
# set GITHUB_TOKEN, PERISCOPE_API_KEY, PERISCOPE_SECRET_KEY

Generate the two keys:

python3 -c "import secrets; print(secrets.token_urlsafe(32))"   # PERISCOPE_API_KEY
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"   # PERISCOPE_SECRET_KEY

2 · Build and run

Deploying to a remote server? Update the frontend build args in docker-compose.yml first (VITE_API_BASE_URL, VITE_WS_BASE_URL).

docker compose up -d --build
docker compose ps        # check status
docker compose logs -f   # follow logs

UI → :3001API → :8001Swagger → :8001/docs

3 · Run your first scan

curl -X POST http://localhost:8001/scan/github/org \
  -H "Content-Type: application/json" \
  -d '{"org": "your-github-org"}'

Open the dashboard to watch findings arrive live over WebSocket. Reports (.txt) persist in the periscope-reports Docker volume across restarts.

Local development (without Docker)

# backend
cd backend && pip install -e .
uvicorn radar_scanner.main:app --reload --port 8000

# frontend
cd frontend && npm install
cp .env.example .env    # VITE_API_BASE_URL=http://localhost:8000
npm run dev             # → http://localhost:5173

# tests
cd backend && pytest tests/ -v

Source: README.md · backend/README.md

← Documentation Configuration →