Skip to main content

Installation Guide

System Requirements​

Minimum Requirements​

  • Operating System: Windows 10+, macOS 10.15+, Linux (Ubuntu 18.04+, CentOS 7+)
  • Memory: 4GB RAM minimum, 8GB recommended
  • Storage: 500MB for application, additional space for backups
  • Network: Internet connection for cloud storage backends
  • Terraform: Version 0.12 or higher

Supported Platforms​

PlatformArchitectureStatus
Windowsx64, ARM64✅ Stable
macOSIntel, Apple Silicon✅ Stable
Linuxx64, ARM64✅ Stable
DockerAll✅ Stable

Installation Methods​

Windows​

# Using PowerShell (Run as Administrator)
irm https://terraback.io/install.ps1 | iex

# Or using Chocolatey
choco install terraback

macOS​

# Using Homebrew
brew tap terraback/tap
brew install terraback

# Or using curl
curl -sSL https://terraback.io/install.sh | bash

Linux​

# Ubuntu/Debian
curl -sSL https://terraback.io/install.sh | bash

# Or using apt (after adding repository)
sudo add-apt-repository ppa:terraback/stable
sudo apt update
sudo apt install terraback

# RHEL/CentOS/Fedora
sudo yum install -y https://terraback.io/terraback-latest.rpm

# Arch Linux (AUR)
yay -S terraback

Manual Installation​

Step 1: Download Binary​

Visit https://terraback.io/download and download the appropriate binary for your platform.

Step 2: Extract Archive​

# Linux/macOS
tar -xzvf terraback_<version>_<platform>.tar.gz

# Windows (PowerShell)
Expand-Archive terraback_<version>_windows.zip -DestinationPath C:\Program Files\Terraback

Step 3: Add to PATH​

Linux/macOS​
# Move binary to standard location
sudo mv terraback /usr/local/bin/
sudo chmod +x /usr/local/bin/terraback

# Or add to PATH in ~/.bashrc or ~/.zshrc
export PATH=$PATH:/path/to/terraback
Windows​
# Add to system PATH
[Environment]::SetEnvironmentVariable(
    "Path",
    $env:Path + ";C:\Program Files\Terraback",
    [EnvironmentVariableTarget]::Machine
)

Docker Installation​

# Pull the official image
docker pull terraback/terraback:latest

# Run as a container
docker run -v $(pwd):/workspace terraback/terraback:latest

# Or use docker-compose
cat > docker-compose.yml << EOF
version: '3.8'
services:
  terraback:
    image: terraback/terraback:latest
    volumes:
      - ./:/workspace
      - ~/.aws:/root/.aws:ro
    environment:
      - TERRABACK_API_KEY=${TERRABACK_API_KEY}
EOF

docker-compose run terraback

Building from Source​

Prerequisites​

  • Go 1.19 or higher
  • Git
  • Make (optional)

Build Steps​

# Clone the repository
git clone https://github.com/terraback/terraback.git
cd terraback

# Build using Make
make build

# Or build directly with Go
go build -o terraback ./cmd/terraback

# Install globally
sudo make install
# or
sudo cp terraback /usr/local/bin/

Verification​

Check Installation​

# Verify installation
terraback --version

# Expected output
Terraback v1.5.0 (build: 2024.01.15)
Platform: darwin/arm64

Run Diagnostics​

# Check system compatibility
terraback doctor

# Output
✅ Terraform detected: v1.5.7
✅ Git detected: v2.42.0
✅ Network connectivity: OK
✅ Storage permissions: OK
✅ All systems operational

Initial Setup​

Step 1: Initialize Terraback​

# Initialize in current directory
terraback init

# Or specify a Terraform project
terraback init --project /path/to/terraform/project

Step 2: Authentication​

# For cloud storage (recommended)
terraback auth login

# For local storage
terraback config set storage.type local
terraback config set storage.path ~/.terraback/backups

Step 3: Verify Setup​

# Test configuration
terraback validate

# Perform test backup
terraback backup --dry-run

Configuration File​

Terraback creates a configuration file at:

  • Linux/macOS: ~/.terraback/config.yml
  • Windows: %APPDATA%\terraback\config.yml

Example configuration:

# .terraback/config.yml
version: 1
profile: default

storage:
  type: s3  # Options: s3, azure, gcp, local
  bucket: my-terraback-backups
  region: us-east-1
  encryption: true

backup:
  automatic: true
  interval: 3600  # seconds
  retention: 30   # days
  compression: true

monitoring:
  drift_detection: true
  alert_email: ops@example.com
  webhook_url: https://hooks.slack.com/...

terraform:
  binary_path: /usr/local/bin/terraform
  workspace: default
  parallelism: 10

Environment Variables​

Terraback supports configuration via environment variables:

# API Authentication
export TERRABACK_API_KEY="your-api-key"
export TERRABACK_API_URL="https://api.terraback.io"

# Storage Configuration
export TERRABACK_STORAGE_TYPE="s3"
export TERRABACK_STORAGE_BUCKET="my-backups"
export TERRABACK_STORAGE_REGION="us-east-1"

# AWS Credentials (if using S3)
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"

# Backup Settings
export TERRABACK_BACKUP_AUTO="true"
export TERRABACK_BACKUP_INTERVAL="3600"

Upgrading​

Automatic Updates​

# Check for updates
terraback update check

# Apply updates
terraback update apply

Manual Upgrade​

# Backup current configuration
terraback config export > config-backup.yml

# Install new version (use installation method above)

# Restore configuration
terraback config import config-backup.yml

Uninstallation​

Clean Uninstall​

# Export data before uninstalling
terraback export --all --output ./terraback-export

# Remove application
# macOS
brew uninstall terraback

# Linux
sudo apt remove terraback
# or
sudo yum remove terraback

# Windows (PowerShell as Admin)
choco uninstall terraback

# Remove configuration and data
rm -rf ~/.terraback

Platform-Specific Notes​

Windows​

  • Run PowerShell as Administrator for installation
  • Windows Defender may require exclusion for .terraback folder
  • Use forward slashes in paths or escape backslashes

macOS​

  • Grant Full Disk Access if prompted
  • Gatekeeper verification required on first run
  • Use sudo for system-wide installation

Linux​

  • SELinux may require policy adjustments
  • AppArmor profiles available for Ubuntu
  • Systemd service files included for automation

Troubleshooting Installation​

Common Issues​

Permission Denied​

# Fix permission issues
sudo chown -R $(whoami) ~/.terraback
chmod 755 ~/.terraback

Command Not Found​

# Verify PATH
echo $PATH

# Add to PATH manually
export PATH=$PATH:/usr/local/bin
source ~/.bashrc  # or ~/.zshrc

SSL Certificate Errors​

# Update certificates
# macOS
brew install ca-certificates

# Linux
sudo update-ca-certificates

Next Steps​

After successful installation:

  1. Read the Getting Started Guide
  2. Configure your first project
  3. Set up automated backups
  4. Join the Beta Program for early access features

Support​

If you encounter installation issues: