Complete Guide: Installing Shuffle SOAR on Ubuntu Server 22.04.5 with Docker

What is Shuffle?

Shuffle is an open-source Security Orchestration, Automation, and Response (SOAR) platform that helps security teams automate their workflows, integrate security tools, and respond to incidents faster. It provides a visual workflow editor, extensive app integrations, and a flexible automation engine.

Why Use Shuffle?

• Open Source & Free — No licensing costs, fully self-hosted
• Visual Workflow Builder — Drag-and-drop automation without coding
• 200+ Pre-built Apps — Integrations with popular security tools (TheHive, MISP, VirusTotal, Slack, etc.)
• Active Community — Regular updates and community support
• API-First Design — Easy to extend and customize

Step-by-Step Installation

Step 1: Update System Packages

Always start with a fully updated system:

sudo apt update && sudo apt upgrade -y
sudo apt autoremove -y

Step 2: Configure Docker Permissions

Add your user to the Docker group to run commands without sudo:

sudo usermod -aG docker $USER
newgrp docker

Verify Docker installation:

docker --version
docker compose version

Step 3: Configure System for OpenSearch

OpenSearch (the database) requires specific kernel settings:

Disable swap memory:

sudo swapoff -a

# Make permanent by commenting swap in fstab
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

Set memory mapping limit (CRITICAL):

sudo sysctl -w vm.max_map_count=262144

# Make permanent
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

Verify the setting:

sysctl vm.max_map_count
# Output should be: vm.max_map_count = 262144

Step 4: Clone Shuffle Repository

# Clone from GitHub
git clone https://github.com/frikky/Shuffle.git

# Navigate to Shuffle directory
cd Shuffle

# Verify the directory structure
ls -la

Step 5: Prepare Database Directory

OpenSearch runs as a non-root user (UID 1000) inside the container:

# Create database directory
mkdir -p shuffle-database

# Set correct ownership
sudo chown -R 1000:1000 shuffle-database

# Set proper permissions
chmod 755 shuffle-database

Step 6: Configure Admin Credentials

nano .env

Add the following content (customize your password):

# Admin Account Configuration
SHUFFLE_DEFAULT_USERNAME=admin
SHUFFLE_DEFAULT_PASSWORD=YourStrongPassword123!

Step 7: Launch Shuffle

Start all services:

docker compose up -d

Monitor the startup process (recommended):

docker compose logs -f

Step 8: Verify All Services Are Running

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Expected output:

NAMES                 STATUS          PORTS
shuffle-frontend      Up 2 minutes    0.0.0.0:3001->80/tcp
shuffle-backend       Up 2 minutes    5001/tcp
shuffle-orborus       Up 2 minutes    
shuffle-opensearch    Up 2 minutes    9200/tcp, 9300/tcp
shuffle-proxy         Up 2 minutes    443/tcp, 80/tcp

All containers should show “Up” status.

Step 9: Access Shuffle Web Interface

Open your web browser and navigate to:

http://[YOUR_SERVER_IP]:3001

Login with:

• Username: admin (or what you set in .env)
• Password: YourStrongPassword123! (or what you set)

Post-Installation Configuration

Verify API Connectivity

# Check backend health
curl http://localhost:5001/api/v1/health

# Expected response: {"status":"ok"}

Troubleshooting Common Issues

Issue 1: Cannot Log In — No Default User Created

Root cause: The .env file was not created or is missing credentials.

Solution:

cd ~/Shuffle
docker compose down

# Create or edit .env file
echo "SHUFFLE_DEFAULT_USERNAME=admin" >> .env
echo "SHUFFLE_DEFAULT_PASSWORD=YourNewPassword123!" >> .env

# Restart Shuffle
docker compose up -d

# Wait 2 minutes for initialization
sleep 120

# Try logging in again

Verification: Check that the environment variables are loaded:

docker exec shuffle-backend env | grep SHUFFLE_DEFAULT

Issue 2: OpenSearch Fails to Start — Memory Mapping Error

Root cause: Linux kernel parameter not set correctly.

Solution:

# Set parameter immediately
sudo sysctl -w vm.max_map_count=262144

# Make permanent
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

# Verify setting
sysctl vm.max_map_count

# Restart OpenSearch
docker compose restart shuffle-opensearch

# Check if it's running
docker compose logs shuffle-opensearch --tail=20

Issue 3: Backend Cannot Connect to OpenSearch

Root cause: OpenSearch takes 30–60 seconds to fully initialize, especially on first run.

Solution:

This is normal during first startup. Wait 2–3 minutes. If it persists:

# Check if OpenSearch is healthy
docker ps | grep opensearch

# Check OpenSearch logs for errors
docker compose logs shuffle-opensearch | tail -50

# Test OpenSearch connectivity from backend container
docker exec shuffle-backend curl -k https://shuffle-opensearch:9200

# If still failing, restart all services
docker compose down
docker compose up -d

Issue 4: Port 3001 Already in Use

Root cause: Another service is using port 3001.

Solution 1: Change Shuffle’s port

cd ~/Shuffle

# Edit .env file
nano .env

# Add or modify:
FRONTEND_PORT=8080

# Restart Shuffle
docker compose down
docker compose up -d

# Access at: http://your-server-ip:8080

Solution 2: Find and stop the conflicting service

# Find what's using port 3001
sudo lsof -i :3001
sudo netstat -tulpn | grep 3001

# Stop the conflicting service (example for nginx)
sudo systemctl stop nginx

Issue 5: Permission Denied for Database Directory

Root cause: The shuffle-database directory has incorrect ownership.

Solution:

cd ~/Shuffle

# Stop OpenSearch
docker compose stop shuffle-opensearch

# Fix ownership (OpenSearch runs as UID 1000)
sudo chown -R 1000:1000 shuffle-database

# Set correct permissions
chmod 755 shuffle-database

# Restart OpenSearch
docker compose start shuffle-opensearch

# Verify it's running
docker compose logs shuffle-opensearch --tail=20

Conclusion

You have successfully installed Shuffle SOAR on Ubuntu Server 22.04.5. The platform is now ready for:

• Creating automated security workflows
• Integrating with your existing security tools
• Responding to incidents faster

Next Steps

1. Explore the Workflow Editor — Start with simple automation
2. Install Apps — Browse the App Marketplace for integrations
3. Create API Keys — For programmatic access
4. Invite Team Members — Add users in Settings
5. Read Official Documentation — https://shuffle.dev/docs

Support Resources

• Documentation: https://shuffle.dev/docs
• GitHub: https://github.com/frikky/Shuffle
• Discord Community: https://discord.gg/shuffle
• Issue Tracker: https://github.com/frikky/Shuffle/issues