Documentation

Installation Guide

Deploy TorScan in various environments with our comprehensive installation guide.

System Requirements

Minimum Requirements

4 CPU cores
8GB RAM
50GB storage
Docker 20.10+
Docker Compose 1.29+

Recommended for Production

8+ CPU cores
16GB+ RAM
100GB+ SSD storage
Ubuntu 20.04+ or RHEL 8+
Dedicated network connection

Docker Installation (Recommended)

1. Prerequisites

# Install Docker (Ubuntu/Debian)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Verify installation
docker --version
docker-compose --version

2. Clone and Configure

# Clone the repository
git clone https://github.com/perfecxion-ai/TorScan.git
cd TorScan

# Create environment configuration
cp .env.example .env

# Generate secure passwords
openssl rand -base64 32  # Use for SECRET_KEY
openssl rand -base64 32  # Use for MONGODB_PASSWORD
openssl rand -base64 32  # Use for ELASTICSEARCH_PASSWORD

3. Configure Environment

Edit the .env file with your secure values:

# Security Settings
SECRET_KEY=your-generated-secret-key
FLASK_DEBUG=False
FLASK_ENV=production

# Database Configuration
MONGODB_USERNAME=torscan
MONGODB_PASSWORD=your-secure-password
MONGODB_DATABASE=torscan_db

# Elasticsearch Configuration
ELASTICSEARCH_USERNAME=elastic
ELASTICSEARCH_PASSWORD=your-secure-password

# Tor Configuration
TOR_SOCKS_PORT=9050
TOR_CONTROL_PORT=9051
TOR_CONTROL_PASSWORD=your-control-password

# Redis Configuration
REDIS_PASSWORD=your-redis-password

# API Settings
API_RATE_LIMIT=100/hour
API_TIMEOUT=300

# Threat Intelligence (Optional)
MISP_URL=https://your-misp-instance.com
MISP_KEY=your-misp-api-key
OPENCTI_URL=https://your-opencti-instance.com
OPENCTI_TOKEN=your-opencti-token

4. Deploy TorScan

# Start all services
docker-compose up -d

# Verify services are running
docker-compose ps

# Check logs
docker-compose logs -f

# Initialize the database
docker-compose exec web python scripts/init_db.py

# Create admin user
docker-compose exec web python scripts/create_admin.py

Kubernetes Deployment

1. Helm Chart Installation

# Add Helm repository
helm repo add torscan https://charts.torscan.io
helm repo update

# Create namespace
kubectl create namespace torscan

# Create secrets
kubectl create secret generic torscan-secrets \
  --from-literal=secret-key=$(openssl rand -base64 32) \
  --from-literal=mongodb-password=$(openssl rand -base64 32) \
  --from-literal=elasticsearch-password=$(openssl rand -base64 32) \
  -n torscan

# Install TorScan
helm install torscan torscan/torscan \
  --namespace torscan \
  --values values-production.yaml

2. Production Values Configuration

# values-production.yaml
replicaCount:
  web: 3
  worker: 5
  scheduler: 1

resources:
  web:
    requests:
      memory: "2Gi"
      cpu: "1000m"
    limits:
      memory: "4Gi"
      cpu: "2000m"
  worker:
    requests:
      memory: "1Gi"
      cpu: "500m"
    limits:
      memory: "2Gi"
      cpu: "1000m"

persistence:
  enabled: true
  storageClass: "fast-ssd"
  size: "100Gi"

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: torscan.your-domain.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: torscan-tls
      hosts:
        - torscan.your-domain.com

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 80

monitoring:
  prometheus:
    enabled: true
  grafana:
    enabled: true

Manual Installation

Advanced Users Only

Manual installation requires extensive knowledge of system administration, networking, and security configurations.

1. Install Dependencies

# System packages
sudo apt-get update
sudo apt-get install -y \
  python3.9 python3-pip python3-venv \
  tor tor-geoipdb privoxy \
  mongodb-org elasticsearch redis-server \
  nginx certbot python3-certbot-nginx

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

2. Configure Tor

# /etc/tor/torrc
SocksPort 9050
ControlPort 9051
HashedControlPassword your_hashed_password
CookieAuthentication 1
MaxCircuitDirtiness 60
CircuitBuildTimeout 30
NewCircuitPeriod 30

# Generate hashed password
tor --hash-password your_password

# Restart Tor
sudo systemctl restart tor

3. Configure Services

# MongoDB
sudo systemctl start mongod
mongo admin --eval "db.createUser({
  user: 'torscan',
  pwd: 'your_password',
  roles: [{role: 'readWrite', db: 'torscan_db'}]
})"

# Elasticsearch
sudo systemctl start elasticsearch
curl -X PUT "localhost:9200/_security/user/torscan" \
  -H "Content-Type: application/json" \
  -d '{"password":"your_password","roles":["superuser"]}'

# Redis
sudo systemctl start redis-server
redis-cli CONFIG SET requirepass "your_password"

Post-Installation Setup

Security Hardening

Change all default passwords immediately
Enable firewall rules (allow only necessary ports)
Configure SSL/TLS certificates
Enable audit logging
Set up backup procedures

Initial Configuration

# Create initial admin user
docker-compose exec web python scripts/create_admin.py \
  --username admin \
  --email admin@your-domain.com \
  --password your-secure-password

# Import default patterns
docker-compose exec web python scripts/import_patterns.py \
  --file config/default_patterns.json

# Test Tor connectivity
docker-compose exec web python scripts/test_tor.py

# Verify all services
docker-compose exec web python scripts/health_check.py

Environment Variables Reference

Variable	Description	Default
SECRET_KEY	Flask secret key for sessions	Required
FLASK_ENV	Flask environment	production
MONGODB_URI	MongoDB connection string	mongodb://localhost:27017
ELASTICSEARCH_URL	Elasticsearch URL	http://localhost:9200
REDIS_URL	Redis connection URL	redis://localhost:6379
TOR_PROXY	Tor SOCKS proxy address	socks5://127.0.0.1:9050
MAX_WORKERS	Maximum concurrent crawl workers	10
LOG_LEVEL	Logging level	INFO

Troubleshooting Installation

Docker Permission Errors

# Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in, then verify
docker run hello-world

Port Conflicts

# Check ports in use
sudo netstat -tlnp | grep -E '5000|9200|27017|6379'

# Modify docker-compose.yml to use different ports
# Example: Change 5000:5000 to 5001:5000

Memory Issues

If containers are being killed due to memory limits:

Increase Docker memory allocation
Reduce worker count in configuration
Enable swap memory on host
Use resource limits in docker-compose.yml

Next Steps

Follow the Quick Start Guide →Explore the API Reference →Read Configuration Guides →