# Wallarm Deployment System

A comprehensive solution for deploying Wallarm filtering nodes on virtual machines or bare metal servers. This system provides automated deployment, preflight checks, and management of Wallarm security nodes with support for multiple instances on the same server.

## Features

- **Automated Preflight Checks** - Validates system readiness, network connectivity, and resource availability
- **Smart Artifact Management** - GitLab-first approach with local fallback support
- **Multiple Node Support** - Deploy multiple Wallarm instances on the same VM with unique port configurations
- **Interactive Configuration** - User-friendly prompts for cloud region, ports, tokens, and upstream applications
- **Comprehensive Validation** - Network tests, port availability checks, and deployment verification
- **Persistence & Management** - Automatic service creation, start scripts, and health monitoring
- **Clean Uninstallation** - Safe removal of containers, images, and configuration files

## Prerequisites

### System Requirements
- **Operating System**: Linux (Ubuntu 20.04+, CentOS/RHEL 8+, Debian 11+)
- **Architecture**: x86_64 (amd64)
- **Memory**: Minimum 2GB RAM (4GB recommended for production)
- **Storage**: Minimum 10GB free disk space
- **Network**: Outbound connectivity to Wallarm cloud endpoints

### Software Dependencies
- **Bash**: Version 4.0+ (included with most Linux distributions)
- **curl**: For downloading artifacts and connectivity testing
- **sudo**: For Docker installation and system configuration
- **systemd** or **sysvinit**: For service management

## Quick Start

### 1. Download the Scripts

```bash
# Download the preflight check script
curl -sL "https://git.sechpoint.app/customer-engineering/wallarm/-/raw/main/wallarm-ct-check.sh" > wallarm-ct-check.sh
chmod +x wallarm-ct-check.sh

# Download the deployment script
curl -sL "https://git.sechpoint.app/customer-engineering/wallarm/-/raw/main/wallarm-ct-deploy.sh" > wallarm-ct-deploy.sh
chmod +x wallarm-ct-deploy.sh

# Download the uninstall script (optional)
curl -sL "https://git.sechpoint.app/customer-engineering/wallarm/-/raw/main/wallarm-ct-uninstall.sh" > wallarm-ct-uninstall.sh
chmod +x wallarm-ct-uninstall.sh
```

### 2. Run Preflight Check

```bash
./wallarm-ct-check.sh
```

The preflight check will:
- Verify system compatibility (OS, architecture, init system)
- Test network connectivity to Wallarm cloud endpoints
- Check for existing Docker installations
- Validate resource availability
- Generate a `.env` file with results

### 3. Deploy Wallarm Node

```bash
./wallarm-ct-deploy.sh
```

The deployment script will:
1. Read preflight check results
2. Prompt for configuration (ports, upstream application, Wallarm token)
3. Install Docker if not present
4. Download and load Wallarm Docker image
5. Configure and start the Wallarm container
6. Verify deployment with health checks

## Detailed Usage

### Workflow Overview

1. **Preflight Check** → **Deployment** → **Verification** → **Management**

### Configuration Requirements

#### Wallarm Node Token
Before deployment, you need a Wallarm Node Token from the Wallarm Console:
- **Create Token**: Navigate to Wallarm Console → **Nodes** → **Create node**
- **Token Format**: Base64 encoded string (alphanumeric with `+`, `/`, `=`, `-`, `_`)
- **Documentation**: [Official Wallarm Documentation](https://docs.wallarm.com/admin-en/installation-docker-en/)

#### Header Configuration for Firewalls/Ingress Controllers
To ensure proper IP address detection and metadata forwarding, configure your firewall or ingress controller to include these headers:

```nginx
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
```

**Note**: The deployment script configures the first three headers automatically. You must manually add `X-Forwarded-Host: "$host"` to your existing firewall/ingress configuration.

### Multiple Node Deployment on Same VM

You can deploy multiple Wallarm nodes on the same virtual machine by:

1. **Unique Port Configuration**: Each instance must use unique ingress and monitoring ports
   - Default ingress port: 80 (configurable during deployment)
   - Monitoring port: ingress_port + 10 (auto-calculated)
   - Example: Instance 1 (80/90), Instance 2 (8080/8090), Instance 3 (8888/8898)

2. **Instance Naming**: Each deployment generates a unique instance name
   - Format: `wallarm-<hostname>-<date>-<random>`
   - Example: `wallarm-server1-20250324-ab3c`

3. **Isolated Configuration**: Each instance has its own:
   - Docker container with unique name
   - Configuration directory (`/opt/wallarm/<instance-name>/`)
   - Port binding and network namespace
   - Log files and start scripts

**Resource Considerations for Multiple Nodes**:
- Add 500MB RAM per additional Wallarm instance
- Each instance requires ~2GB disk space
- Consider CPU allocation (1 vCPU core per 2-3 instances for moderate traffic)

## Artifact Sources (Priority Order)

The system uses a smart fallback approach for artifact retrieval:

### 1. **Primary Source**: GitLab Repository
   - URL: `https://git.sechpoint.app/customer-engineering/wallarm`
   - Contains: Docker binaries and Wallarm images with SHA256 checksums
   - Benefits: Version control, access control, audit trail

### 2. **Secondary Source**: Local Directories
   - `./binaries/` - Docker static binaries (`docker-29.2.1.tgz`)
   - `./images/` - Wallarm Docker images (`wallarm-node-6.11.0-rc1.tar.gz`)
   - Benefits: Air-gapped environments, faster deployment

### 3. **Tertiary Source**: Current Directory
   - Any `docker-*.tgz` or `wallarm-node-*.tar.gz` files in script location
   - Benefits: Ad-hoc deployments, testing scenarios

### 4. **Fallback Source**: Internal Proxy Servers
   - Original infrastructure URLs (with embedded credentials)
   - Used only when other sources are unavailable

## Suggested Resources

### Hardware Recommendations

| Deployment Type | vCPUs | RAM  | Storage | Network | Recommended For |
|----------------|-------|------|---------|---------|-----------------|
| **Development** | 2     | 4GB  | 20GB    | 100Mbps | Testing, PoC environments |
| **Production**  | 4     | 8GB  | 40GB    | 1Gbps   | Moderate traffic (up to 100 RPS) |
| **Enterprise**  | 8+    | 16GB+| 100GB   | 10Gbps  | High traffic, multiple nodes |

### Cloud VM Recommendations
- **AWS**: t3.large (development), m5.xlarge (production), c5.2xlarge (enterprise)
- **Azure**: D2s v3 (development), D4s v3 (production), D8s v3 (enterprise)
- **GCP**: e2-standard-4 (development), n2-standard-8 (production), c2-standard-8 (enterprise)

### Bare Metal Considerations
- **CPU**: Intel Xeon Silver/Gold or AMD EPYC (minimum 4 physical cores)
- **Memory**: ECC RAM recommended for production environments
- **Storage**: SSD/NVMe for better I/O performance
- **Network**: Dual NIC for redundancy, 10Gbps recommended

## Script Reference

### `wallarm-ct-check.sh`
**Purpose**: System validation and preflight checks

**Key Functions**:
- OS compatibility verification (Ubuntu, CentOS, Debian)
- Network connectivity testing (US/EU cloud endpoints)
- Resource availability assessment
- Docker installation checking
- Environment file generation (`.env`)

**Usage**:
```bash
# Run check with default settings
./wallarm-ct-check.sh

# Enable debug output
DEBUG=1 ./wallarm-ct-check.sh

# Disable SSL certificate validation (for self-signed certs)
WALLARM_INSECURE_SSL=0 ./wallarm-ct-check.sh
```

### `wallarm-ct-deploy.sh`
**Purpose**: Wallarm node deployment and configuration

**Key Functions**:
- Interactive configuration wizard
- Docker engine installation (with VFS storage driver for LXC)
- Artifact download with checksum verification
- Wallarm container deployment
- Nginx configuration with proper headers
- Health check and deployment verification

**Usage**:
```bash
# Interactive deployment
./wallarm-ct-deploy.sh

# Deployment with pre-filled environment
WALLARM_TOKEN="your_token_here" ./wallarm-ct-deploy.sh

# Skip preflight check verification (not recommended)
SKIP_PREFLIGHT=1 ./wallarm-ct-deploy.sh
```

### `wallarm-ct-uninstall.sh`
**Purpose**: Safe removal of Wallarm nodes

**Key Functions**:
- Interactive confirmation with safety checks
- Container stopping and removal
- Image cleanup
- Configuration directory removal
- Optional Docker binary cleanup

**Usage**:
```bash
# Interactive uninstallation
./wallarm-ct-uninstall.sh

# Force removal without prompts (use with caution)
FORCE=1 ./wallarm-ct-uninstall.sh

# Remove Docker binaries (if no other containers exist)
REMOVE_DOCKER=1 ./wallarm-ct-uninstall.sh
```

## Troubleshooting

### Common Issues

#### 1. Preflight Check Fails
```bash
# Check detailed errors
cat .env

# Verify network connectivity manually
curl -I https://api.wallarm.com
curl -I https://us1.api.wallarm.com

# Check system compatibility
uname -m
cat /etc/os-release
```

#### 2. Deployment Fails - Port Conflicts
```bash
# Check for listening ports
sudo ss -tlnp | grep ':80\|:90\|:8080'

# Find process using port
sudo lsof -i :80

# Configure different ports during deployment
```

#### 3. Wallarm Token Issues
```bash
# Verify token format (should be base64)
echo "your_token" | base64 -d 2>/dev/null | base64

# Get new token from Wallarm Console
# https://docs.wallarm.com/admin-en/installation-docker-en/
```

#### 4. Docker Installation Problems
```bash
# Check Docker service status
sudo systemctl status docker

# Verify Docker group membership
groups $USER

# Test Docker without sudo
docker run --rm hello-world
```

#### 5. Header Configuration Warnings
Ensure your upstream firewall/load balancer includes:
- `X-Real-IP: "$remote_addr"`
- `X-Forwarded-For: "$proxy_add_x_forwarded_for"`
- `X-Forwarded-Proto: "$scheme"`
- `X-Forwarded-Host: "$host"`

### Log Files
- **Preflight Check**: `~/logs/wallarm-check.log`
- **Deployment**: `~/logs/wallarm-deployment.log`
- **Container Logs**: `/opt/wallarm/<instance-name>/container.log`
- **System Logs**: `/var/log/syslog` or `/var/log/messages`

## Security Considerations

### Network Security
- Use firewall rules to restrict access to monitoring ports (default: 90, 190, 290, etc.)
- Consider VPN or private networking for management interfaces
- Implement rate limiting for ingress ports

### Access Control
- Restrict `sudo` access to deployment scripts
- Use separate service accounts for Wallarm containers
- Implement proper secret management for Wallarm tokens

### Monitoring & Auditing
- Enable Docker logging driver with rotation
- Monitor container resource usage
- Regular security updates for Docker and host OS

## Maintenance

### Regular Tasks
1. **Log Rotation**: Configure logrotate for container logs
2. **Docker Updates**: Periodically update Docker engine
3. **Image Updates**: Check for new Wallarm node versions
4. **Backup**: Regular backup of configuration directories

### Version Updates
When updating Wallarm node version:
1. Pull new image from GitLab or official registry
2. Stop existing container
3. Deploy new container with updated image
4. Verify functionality before removing old container

## Disclaimer

**IMPORTANT LEGAL NOTICE**

This software is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall Sechpoint or its affiliates be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.

### No Responsibility Clause
- Sechpoint assumes no responsibility for any harm, damage, or loss caused by the use of this software
- Users are solely responsible for testing, validating, and securing their deployments
- This software may contain bugs, security vulnerabilities, or compatibility issues
- Use at your own risk and with appropriate professional oversight

### User Responsibilities
1. **Testing**: Thoroughly test in non-production environments before deployment
2. **Security**: Implement appropriate security controls and monitoring
3. **Backup**: Maintain regular backups of configurations and data
4. **Updates**: Keep the software and dependencies updated
5. **Compliance**: Ensure usage complies with all applicable laws and regulations

### Support
- This is an unsupported deployment tool
- No official support, maintenance, or updates are guaranteed
- Community contributions are welcome via GitLab repository

## Contributing

Contributions to improve the Wallarm deployment system are welcome:

1. Fork the repository on GitLab
2. Create a feature branch
3. Make changes with comprehensive testing
4. Submit a merge request with description

## License

Proprietary - See disclaimer section for usage terms.

## Contact & Support

- **Repository**: https://git.sechpoint.app/customer-engineering/wallarm
- **Issues**: Use GitLab issue tracker for bug reports
- **Documentation**: [Wallarm Official Documentation](https://docs.wallarm.com/)

---

*Last Updated: 2026-03-24*  
*Version: 1.2*  
*For use with Wallarm Node 6.11.0-rc1 and Docker 29.2.1*