Installation

This guide walks you through installing Alien Giraffe and getting it ready to manage secure access to your data sources.

System Requirements

Minimum Requirements:

• CPU: 2 cores
• RAM: 4 GB
• Storage: 20 GB
• Operating System: Linux, macOS, or Windows with WSL2

Recommended for Production:

• CPU: 4+ cores
• RAM: 8+ GB
• Storage: 50+ GB SSD
• Operating System: Linux (Ubuntu 20.04+, RHEL 8+, Debian 11+)

Dependencies:

• Python 3.9+ (for Python installation)
• Docker 20.10+ (for container installation)
• Kubernetes 1.24+ (for Kubernetes deployment)

Installation Methods

Choose the installation method that best fits your environment:

Option 1: Python Package (Quick Start)

Best for development, testing, and small deployments.

Install via pip:

# Install Alien Giraffe
pip install alien-giraffe

# Verify installation
a10e --version

Install from source:

# Clone the repository
git clone https://github.com/aliengiraffe/alien-giraffe.git
cd alien-giraffe

# Install in development mode
pip install -e .

# Verify installation
a10e --version

Create initial configuration:

# Generate default configuration
a10e init

# This creates:
# ~/.a10e/config.toml       - Main configuration
# ~/.a10e/policies/         - Policy directory (YAML/JSON)
# ~/.a10e/credentials/      - Credential storage (encrypted)

Option 2: Docker (Recommended)

Best for consistent deployments and easier dependency management.

Pull and run the official image:

# Pull the latest image
docker pull aliengiraffe/alien-giraffe:latest

# Create a configuration directory
mkdir -p ~/.a10e

# Generate default configuration
docker run --rm -v ~/.a10e:/config \
  aliengiraffe/alien-giraffe:latest init

# Run Alien Giraffe
docker run -d \
  --name alien-giraffe \
  -p 8080:8080 \
  -v ~/.a10e:/config \
  aliengiraffe/alien-giraffe:latest

Using Docker Compose:

Create a docker-compose.yaml file:

version: '3.8'

services:
  alien-giraffe:
    image: aliengiraffe/alien-giraffe:latest
    container_name: alien-giraffe
    ports:
      - "8080:8080"
    volumes:
      - ./config:/config
      - ./policies:/policies
    environment:
      - A10E_CONFIG=/config/config.toml
      - A10E_LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Start the service:

# Start Alien Giraffe
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

Option 3: Kubernetes (Production)

Best for production deployments requiring high availability and scalability.

Prerequisites:

• Kubernetes cluster (1.24+)
• Helm 3.8+
• kubectl configured to access your cluster

Add the Helm repository:

# Add the Alien Giraffe Helm repository
helm repo add alien-giraffe https://helm.aliengiraffe.com

# Update your local Helm chart repository cache
helm repo update

Create a values file:

Create values.yaml with your configuration:

replicaCount: 3

image:
  repository: aliengiraffe/alien-giraffe
  tag: latest
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 8080

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: a10e.company.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: a10e-tls
      hosts:
        - a10e.company.com

resources:
  requests:
    memory: "2Gi"
    cpu: "1"
  limits:
    memory: "4Gi"
    cpu: "2"

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

Deploy using Helm:

# Create namespace
kubectl create namespace alien-giraffe

# Install Alien Giraffe
helm install alien-giraffe alien-giraffe/alien-giraffe \
  --namespace alien-giraffe \
  --values values.yaml

# Check deployment status
kubectl get pods -n alien-giraffe

# View logs
kubectl logs -n alien-giraffe -l app.kubernetes.io/name=alien-giraffe

See the full Kubernetes deployment guide for advanced configuration options.

Initial Configuration

After installation, configure Alien Giraffe with your basic settings.

Configuration File Structure

The main configuration file (config.toml) contains:

# API Server Configuration
[server]
host = "0.0.0.0"
port = 8080

[server.tls]
enabled = false
cert = "/path/to/cert.pem"
key = "/path/to/key.pem"

# Logging Configuration
[logging]
level = "info"
format = "json"
output = "stdout"

# Authentication
[authentication.jwt]
secret = "${JWT_SECRET}"
expiration = "8h"

# Policy Configuration
[policies]
directory = "/policies"
autoReload = true
reloadInterval = "60s"

# Audit Logging
[audit]
enabled = true
destination = "file"
path = "/var/log/a10e/audit.log"

[audit.rotation]
maxSize = "100MB"
maxAge = "90d"
maxBackups = 10

Environment Variables

Configure sensitive values using environment variables:

# Required
export A10E_JWT_SECRET="your-secret-key-here"

# Optional
export A10E_LOG_LEVEL="info"
export A10E_CONFIG="/path/to/config.toml"
export A10E_POLICIES_DIR="/path/to/policies"

Generate JWT Secret

Create a secure JWT secret for session management:

# Generate a secure random secret
openssl rand -base64 32

# Set it as an environment variable
export A10E_JWT_SECRET="generated-secret-here"

Verification

Verify that Alien Giraffe is running correctly:

Check Service Health

# For local/Docker installation
curl http://localhost:8080/health

# Expected response:
# {"status":"healthy","version":"1.0.0"}

Check API Connectivity

# Test the API endpoint
curl http://localhost:8080/api/v1/status

# Expected response:
# {
#   "status": "running",
#   "version": "1.0.0",
#   "components": {
#     "policies": "loaded",
#     "sources": "0 configured",
#     "authentication": "ready"
#   }
# }

Using the CLI

# Check CLI connectivity
a10e status

# Expected output:
# Alien Giraffe Status
# ━━━━━━━━━━━━━━━━━━━━
# Version:     1.0.0
# Status:      Running
# Policies:    0 loaded
# Sources:     0 configured
# Users:       1 (admin)

Post-Installation Steps

Create Admin User

# Create the first admin user
a10e user create admin \
  --email admin@company.com \
  --role admin \
  --password

# You'll be prompted to enter a password

Set Up TLS (Production)

For production deployments, enable TLS:

config.toml

[server.tls]
enabled = true
cert = "/etc/a10e/tls/tls.crt"
key = "/etc/a10e/tls/tls.key"
minVersion = "1.2"

Generate or obtain TLS certificates:

# Self-signed certificate (for testing only)
openssl req -x509 -newkey rsa:4096 \
  -keyout tls.key \
  -out tls.crt \
  -days 365 \
  -nodes \
  -subj "/CN=a10e.company.com"

# For production, use certificates from Let's Encrypt or your CA

Configure Backup Storage

Set up backup storage for audit logs and configuration:

config.toml

[backup]
enabled = true
schedule = "0 2 * * *"  # Daily at 2 AM
retention = "90d"

[backup.destination]
type = "s3"
bucket = "a10e-backups"
region = "us-west-2"

Upgrade

Upgrading Python Installation

# Upgrade to latest version
pip install --upgrade alien-giraffe

# Verify new version
a10e --version

Upgrading Docker Installation

# Pull the latest image
docker pull aliengiraffe/alien-giraffe:latest

# Stop and remove old container
docker stop alien-giraffe
docker rm alien-giraffe

# Start new container
docker run -d \
  --name alien-giraffe \
  -p 8080:8080 \
  -v ~/.a10e:/config \
  aliengiraffe/alien-giraffe:latest

Upgrading Kubernetes Deployment

# Update Helm repository
helm repo update

# Upgrade to latest version
helm upgrade alien-giraffe alien-giraffe/alien-giraffe \
  --namespace alien-giraffe \
  --values values.yaml

Troubleshooting

Installation Issues

Problem: pip install fails with dependency errors

# Solution: Upgrade pip and setuptools
pip install --upgrade pip setuptools

# Try installation again
pip install alien-giraffe

Problem: Docker container fails to start

# Check logs
docker logs alien-giraffe

# Common issues:
# - Port 8080 already in use: Change port mapping
# - Configuration file errors: Validate config.toml
# - Permission issues: Check volume mount permissions

Problem: Kubernetes pods in CrashLoopBackOff

# Check pod logs
kubectl logs -n alien-giraffe -l app.kubernetes.io/name=alien-giraffe

# Check pod events
kubectl describe pod -n alien-giraffe <pod-name>

# Common issues:
# - Missing secrets: Create required Kubernetes secrets
# - Resource limits: Adjust resource requests/limits
# - Configuration errors: Validate Helm values

Health Check Failures

# Check if service is listening
netstat -tlnp | grep 8080

# Test with verbose curl
curl -v http://localhost:8080/health

# Check firewall rules
sudo iptables -L -n | grep 8080

Permission Issues

# For Linux/macOS installations
# Ensure correct ownership of configuration directory
sudo chown -R $(whoami):$(whoami) ~/.a10e
chmod 700 ~/.a10e
chmod 600 ~/.a10e/config.toml

Next Steps

Now that Alien Giraffe is installed, continue with:

1. Configure Your First Data Source - Connect to PostgreSQL, S3, or other data sources
2. Create Your First Policy - Define access rules for your data
3. Set Up Identity Integration - Connect your identity provider
4. Configure Monitoring - Set up audit logging and monitoring

For additional help:

• Components Overview - Understand core concepts
• API Reference - Explore the API
• GitHub Issues - Report problems or request features