Installation

This guide covers all installation methods for Faction, from the recommended Docker Compose setup to building from source.

Prerequisites

Important: MongoDB 8.0 (used by Faction) requires a CPU with AVX instruction set support. This may cause issues in certain virtualized environments.

Before installing Faction, ensure your system meets these requirements:

Required

Docker and Docker Compose (for containerized deployment)
Java JDK 11 (for building from source)
Maven (for building from source)
CPU with AVX support - Required for MongoDB 8.0

Docker Compose Installation (Recommended)

The fastest and most reliable way to deploy Faction is using Docker Compose.

Step 1: Clone the Repository

git clone https://github.com/factionsecurity/faction.git
cd faction

Step 2: Review Configuration

The docker-compose.yml file includes default configuration:

services:
  faction-mongo:
    image: mongo:8.0
    ports:
      - "27017:27017"
    volumes:
      - '~/.faction/data:/data/db'
    environment:
      - MONGO_INITDB_ROOT_USERNAME=faction_mongo_user
      - MONGO_INITDB_ROOT_PASSWORD=faction_mongo_pass
      
  tomcat-service:
    build:
      context: .
      dockerfile: Dockerfile
      target: base_app
    environment:
      - 'FACTION_REPORT_STORAGE=local'
      - 'FACTION_MONGO_HOST=faction-mongo'
      - 'FACTION_MONGO_DATABASE=faction'
      - 'FACTION_MONGO_USER=faction_mongo_user'
      - 'FACTION_MONGO_PASSWORD=faction_mongo_pass'
      - 'FACTION_SECRET_KEY=faction_encryption_key'
      - 'FACTION_OAUTH_CALLBACK=http://localhost:8080'
      - 'FACTION_APPSTORE_ENABLED=true'
    ports:
      - "8080:8080"
    depends_on:
      - faction-mongo

Step 3: Launch Faction

docker-compose up --build

The first build will download dependencies and compile the WAR file. This may take 5-10 minutes depending on your system.

Step 4: Access Faction

Once containers are running, access Faction at:

http://127.0.0.1:8080

Environment Variables

Faction uses environment variables for configuration. These can be set in docker-compose.yml or as system environment variables.

Core Configuration

Variable	Description	Default
`FACTION_MONGO_HOST`	MongoDB hostname	`faction-mongo`
`FACTION_MONGO_DATABASE`	MongoDB database name	`faction`
`FACTION_MONGO_USER`	MongoDB username	`faction_mongo_user`
`FACTION_MONGO_PASSWORD`	MongoDB password	`faction_mongo_pass`
`FACTION_SECRET_KEY`	Encryption key for sensitive data	`faction_encryption_key`

Security: Change FACTION_SECRET_KEY and MongoDB credentials before deploying to production!

Storage Configuration

Variable	Description	Default
`FACTION_REPORT_STORAGE`	Storage backend: `local` or `s3`	`local`

OAuth/SAML Configuration

Variable	Description	Required
`FACTION_OAUTH_CALLBACK`	OAuth callback URL	Yes (if using OAuth/SAML)
`FACTION_APPSTORE_ENABLED`	Enable App Store extensions	`true`

SMTP Configuration (Optional)

Configure SMTP for email notifications:

Variable	Description
`FACTION_SMTP_SERVER`	SMTP server hostname
`FACTION_SMTP_PORT`	SMTP server port
`FACTION_SMTP_USER`	SMTP username
`FACTION_SMTP_PASSWORD`	SMTP password
`FACTION_SMTP_FROM_ADDRESS`	From email address

SMTP settings can also be configured through the web interface at Settings → Email Configuration.

Building from Source

For development or customization, you can build Faction from source.

Install Prerequisites

Ensure you have:

Java JDK 11
Maven 3.6+
Git

# Verify installations
java -version
mvn -version

Clone Repository

git clone https://github.com/factionsecurity/faction.git
cd faction

Build with Maven

mvn clean package

This will:

Compile Java sources from src/
Run tests from test/
Package into target/faction.war

The build process uses dependencies defined in pom.xml, including Struts 6.7.0, MongoDB drivers, and docx4j for report generation.

Deploy WAR File

Deploy the generated WAR file to Tomcat 9:

# Copy to Tomcat webapps
cp target/faction.war /usr/local/tomcat/webapps/ROOT.war

# Start Tomcat
/usr/local/tomcat/bin/catalina.sh run

Data Persistence

By default, Docker Compose stores MongoDB data in:

~/.faction/data

This ensures your assessments, findings, and configurations persist across container restarts.

Backup Recommendations

Backup MongoDB Data

# Create backup
docker exec faction-mongo mongodump \
  --username=faction_mongo_user \
  --password=faction_mongo_pass \
  --out=/backup

# Copy from container
docker cp faction-mongo:/backup ./faction-backup-$(date +%Y%m%d)

Restore from Backup

# Copy backup to container
docker cp ./faction-backup-20260305 faction-mongo:/restore

# Restore
docker exec faction-mongo mongorestore \
  --username=faction_mongo_user \
  --password=faction_mongo_pass \
  /restore

Troubleshooting

MongoDB AVX Issues

Problem: MongoDB 8.0 requires CPU AVX support, which may not be available in:

Oracle VirtualBox VMs
Some Kubernetes configurations
Older CPUs

Solutions:

VirtualBox Users:
- Enable AVX passthrough in VM settings
- Or use MongoDB 4.4 (change in docker-compose.yml) See: MongoDB VirtualBox Discussion
Kubernetes Users:
- Use node with AVX support
- Or downgrade MongoDB version See: MongoDB Kubernetes AVX Issue

Port Conflicts

If port 8080 is already in use:

# In docker-compose.yml, change:
ports:
  - "8081:8080"  # Use port 8081 instead

Then access Faction at http://127.0.0.1:8081

Memory Issues

If you encounter OutOfMemoryError:

Increase Tomcat Heap: Edit setenv.sh or set in docker-compose.yml:
```
environment:
  - CATALINA_OPTS=-Xms2g -Xmx4g
```
Monitor with JMX: The included setenv.sh enables JMX monitoring on port 9090:
```
# Connect with VisualVM or JConsole
jconsole localhost:9090
```

Container Logs

View logs for troubleshooting:

# Faction application logs
docker logs -f faction-tomcat-service-1

# MongoDB logs
docker logs -f faction-faction-mongo-1

# All services
docker-compose logs -f

Production Deployment

Security Hardening

Change Default Credentials

Update MongoDB credentials and secret key in docker-compose.yml:

environment:
  - MONGO_INITDB_ROOT_PASSWORD=<strong-random-password>
  - FACTION_SECRET_KEY=<secure-encryption-key>

Enable HTTPS

Use a reverse proxy (nginx, Apache) with SSL/TLS:

server {
  listen 443 ssl;
  server_name faction.example.com;
  
  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;
  
  location / {
    proxy_pass http://localhost:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

Restrict MongoDB Access

Remove MongoDB port exposure in docker-compose.yml:

# Remove or comment out:
# ports:
#   - "27017:27017"

Configure Firewall

Only expose HTTPS port (443) to external networks.

Performance Tuning

JVM Settings (setenv.sh):

# Adjust based on available RAM
export CATALINA_OPTS="-Xms4g -Xmx8g"
export CATALINA_OPTS="$CATALINA_OPTS -XX:+UseG1GC"
export CATALINA_OPTS="$CATALINA_OPTS -XX:+UseStringDeduplication"

Advanced Configuration

LDAP Integration

Configure LDAP authentication through the web interface: Settings → LDAP Configuration Required fields:

LDAP URL
Base DN
Bind DN
Search DN
Object Class

OAuth 2.0 / SAML Setup

Configure SSO through environment variables and web interface:

Set callback URL:

- FACTION_OAUTH_CALLBACK=https://faction.example.com

Configure in Settings → SSO Configuration:
- OAuth Client ID
- OAuth Client Secret
- Discovery URI (for OIDC)
- SAML Metadata URL (for SAML)

S3 Storage Backend

For distributed deployments, use S3 for report storage:

environment:
  - FACTION_REPORT_STORAGE=s3
  - AWS_ACCESS_KEY_ID=<your-key>
  - AWS_SECRET_ACCESS_KEY=<your-secret>
  - AWS_S3_BUCKET=faction-reports
  - AWS_REGION=us-east-1

Development Setup

For development with live reload:

# Use development compose file
docker-compose -f docker-compose-dev.yml up

# Build JavaScript assets
./buildJSAssets.sh

The development setup:

Mounts source code as volumes
Enables hot reload
Exposes debugging ports

Getting Help

Community Support

Join #project-faction on OWASP Slack

Report Issues

Submit bugs and feature requests on GitHub

Contributing

Read the contributing guidelines

Video Tutorials

Watch installation walkthroughs

Next: Once installed, follow the Quickstart Guide to create your first assessment.

Getting Started

Core Features

User Guides

Integrations

Extensions

​Installation

​Prerequisites

​Required

​Recommended

​Docker Compose Installation (Recommended)

​Step 1: Clone the Repository

​Step 2: Review Configuration

​Step 3: Launch Faction

​Step 4: Access Faction

​Environment Variables

​Core Configuration

​Storage Configuration

​OAuth/SAML Configuration

​SMTP Configuration (Optional)

​Building from Source

​Data Persistence

​Backup Recommendations

​Troubleshooting

​MongoDB AVX Issues

​Port Conflicts

​Memory Issues

​Container Logs

​Production Deployment

​Security Hardening

​Performance Tuning

​Advanced Configuration

​LDAP Integration

​OAuth 2.0 / SAML Setup

​S3 Storage Backend

​Development Setup

​Getting Help

Community Support

Report Issues

Contributing

Video Tutorials

Build docs developers (and LLMs) love

Installation

Prerequisites

Required

Recommended

Docker Compose Installation (Recommended)

Step 1: Clone the Repository

Step 2: Review Configuration

Step 3: Launch Faction

Step 4: Access Faction

Environment Variables

Core Configuration

Storage Configuration

OAuth/SAML Configuration

SMTP Configuration (Optional)

Building from Source

Data Persistence

Backup Recommendations

Troubleshooting

MongoDB AVX Issues

Port Conflicts

Memory Issues

Container Logs

Production Deployment

Security Hardening

Performance Tuning

Advanced Configuration

LDAP Integration

OAuth 2.0 / SAML Setup

S3 Storage Backend

Development Setup

Getting Help