# Installation Guide

Get started with Vaultace SecureFlow in minutes. This guide covers installation, initial setup, and verification steps.

## Prerequisites

Before installing Vaultace SecureFlow, ensure you have:

- **Node.js 18+** (recommended: latest LTS)
- **Git** for version control
- **Operating System**: Windows, macOS, or Linux
- **Network Access**: For downloading dependencies and accessing APIs

## Installation Options

### Option 1: NPM Installation (Recommended)

```bash
# Install globally
npm install -g vaultace-cli

# Verify installation
vaultace --version
```

### Option 2: Build from Source

```bash
# Clone the repository
git clone https://github.com/vaultace/vaultace-cli.git
cd vaultace-cli

# Install dependencies
npm install

# Build the project
npm run build

# Link locally
npm link
```

### Option 3: Docker Container

```bash
# Pull the official image
docker pull vaultace/cli:latest

# Run with volume mount for persistence
docker run -v ~/.vaultace:/root/.vaultace vaultace/cli:latest workflow list
```

## Initial Setup

### 1. Authentication Setup

First, authenticate with the Vaultace platform:

```bash
# Login to your Vaultace account
vaultace auth login

# Or configure API key
vaultace config set api-key YOUR_API_KEY
```

### 2. Workspace Configuration

Configure your workspace settings:

```bash
# Set default configuration
vaultace config set workspace production
vaultace config set region us-east-1

# Configure encryption (optional)
vaultace config set encryption-enabled true
vaultace config set privacy-mode false
```

### 3. Initialize Workflow Environment

```bash
# Initialize SecureFlow
vaultace workflow init

# This creates:
# ~/.vaultace/workflows/        - Workflow storage
# ~/.vaultace/workflows/state/  - Encrypted state
# ~/.vaultace/secureflow.key    - Encryption key
```

## Verification

Verify your installation with these commands:

### System Check

```bash
# Run system diagnostics
vaultace config check

# Expected output:
✅ Authentication: Connected
✅ API Access: Available
✅ Encryption: Enabled
✅ Storage: Initialized
✅ Permissions: Valid
```

### Test Workflow Creation

```bash
# List available templates
vaultace workflow templates

# Create a test workflow
vaultace workflow create --template vulnerability_scan_test

# Expected output:
✅ Workflow created: wf_vulnerability_scan_test_1641234567890
Template: vulnerability_scan_test
Name: Test Vulnerability Scan
Steps: 3
Run with: vaultace workflow run wf_vulnerability_scan_test_1641234567890
```

### Test Workflow Execution

```bash
# Run the test workflow
vaultace workflow run wf_vulnerability_scan_test_1641234567890

# Monitor execution
vaultace workflow monitor <execution-id>
```

## Configuration Options

### Global Settings

Edit `~/.vaultace/config.json`:

```json
{
  "apiUrl": "https://api.vaultace.co",
  "workspace": "production",
  "region": "us-east-1",
  "logLevel": "info",
  "encryption": {
    "enabled": true,
    "algorithm": "aes-256-gcm"
  },
  "workflows": {
    "retentionDays": 30,
    "maxConcurrentExecutions": 10,
    "enableAuditLog": true,
    "privacyMode": false
  }
}
```

### Environment Variables

Common environment variables:

```bash
# API Configuration
export VAULTACE_API_URL=https://api.vaultace.co
export VAULTACE_API_KEY=your_api_key

# Logging
export VAULTACE_LOG_LEVEL=debug
export VAULTACE_VERBOSE=true

# Workflow Settings
export VAULTACE_ENCRYPTION_KEY=path/to/key
export VAULTACE_PRIVACY_MODE=true
export VAULTACE_MAX_CONCURRENT=5
```

## Security Setup

### Encryption Key Management

SecureFlow automatically generates encryption keys, but you can manage them manually:

```bash
# Generate new encryption key
vaultace workflow key generate

# Rotate existing key
vaultace workflow key rotate

# Backup encryption key (store securely!)
cp ~/.vaultace/secureflow.key ~/backup/secureflow-backup.key
```

### Access Control

Configure user permissions:

```bash
# Set up role-based access
vaultace auth role create security-analyst
vaultace auth role assign security-analyst --permissions workflow:read,workflow:execute

# Configure API key scoping
vaultace auth api-key create --scope workflow:* --expires 90d
```

### Audit Configuration

Enable comprehensive audit logging:

```bash
# Enable audit logging
vaultace config set audit-enabled true
vaultace config set audit-level full

# Configure log retention
vaultace config set audit-retention-days 365

# Set up log forwarding (optional)
vaultace config set audit-siem-url https://your-siem.company.com/api/logs
```

## Network Configuration

### Proxy Setup

If using a corporate proxy:

```bash
# HTTP/HTTPS proxy
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# Or configure in CLI
vaultace config set proxy-url http://proxy.company.com:8080
vaultace config set proxy-auth username:password
```

### Firewall Rules

Ensure these outbound connections are allowed:

- **API Access**: `*.vaultace.co:443` (HTTPS)
- **Updates**: `registry.npmjs.org:443` (HTTPS)
- **Telemetry**: `telemetry.vaultace.co:443` (HTTPS, optional)

## Platform-Specific Setup

### Windows

```powershell
# Install via Chocolatey
choco install vaultace-cli

# Or use PowerShell
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
iwr https://install.vaultace.com/windows | iex
```

### macOS

```bash
# Install via Homebrew
brew tap vaultace/cli
brew install vaultace-cli

# Or use installation script
curl -fsSL https://install.vaultace.com/macos | bash
```

### Linux

```bash
# Ubuntu/Debian
wget -qO- https://packages.vaultace.com/key | gpg --dearmor > vaultace.gpg
sudo install -o root -g root -m 644 vaultace.gpg /etc/apt/trusted.gpg.d/
echo "deb https://packages.vaultace.com/apt stable main" | sudo tee /etc/apt/sources.list.d/vaultace.list
sudo apt update && sudo apt install vaultace-cli

# RHEL/CentOS/Fedora
sudo dnf config-manager --add-repo https://packages.vaultace.com/rpm/vaultace.repo
sudo dnf install vaultace-cli
```

## Troubleshooting

### Common Issues

**Installation fails with permission errors:**
```bash
# Use npm with --unsafe-perm flag
npm install -g vaultace-cli --unsafe-perm

# Or use a Node version manager
nvm use 18
npm install -g vaultace-cli
```

**Authentication failures:**
```bash
# Clear cached credentials
vaultace auth logout
vaultace auth clear-cache

# Re-authenticate
vaultace auth login --force
```

**Workflow initialization fails:**
```bash
# Check permissions
ls -la ~/.vaultace/

# Reinitialize
rm -rf ~/.vaultace/workflows/
vaultace workflow init --force
```

### Debug Mode

Enable verbose logging for troubleshooting:

```bash
# Global debug mode
export VAULTACE_DEBUG=true
export VAULTACE_LOG_LEVEL=debug

# Or per-command
vaultace workflow list --verbose --debug
```

### Support

If you encounter issues:

1. **Check logs**: `~/.vaultace/cli.log`
2. **Run diagnostics**: `vaultace config check --verbose`
3. **Community**: [GitHub Issues](https://github.com/vaultace/vaultace-cli/issues)
4. **Documentation**: [Troubleshooting Guide](../guides/troubleshooting.md)

## Next Steps

Now that SecureFlow is installed:

1. **[Create Your First Workflow](./first-workflow.md)** - Build a simple security workflow
2. **[Explore Templates](../templates/README.md)** - Browse pre-built security workflows
3. **[Learn Core Concepts](../concepts/README.md)** - Understand SecureFlow architecture
4. **[Configure Monitoring](../guides/monitoring.md)** - Set up observability

---

**Quick Commands Reference:**
```bash
vaultace --help                    # Show all commands
vaultace workflow templates        # List templates
vaultace workflow create           # Create workflow
vaultace workflow list             # List workflows
vaultace config check              # Verify setup
```