Installation
This page helps you choose how to install Alien Giraffe. Every deployment type documented here is preconfigured to run in data mode — the Data Enclave profile that exposes data requests, the catalog, request templates, and Explorer, with no AI Controls/MCP surfaces enabled.
Alien Giraffe is shipped as a binary service (the env-manager binary). Its only stateful control-plane dependency is PostgreSQL. As an operator, you choose the containerized environment it uses to orchestrate data enclaves on top of: Docker for simpler deployments, or Kubernetes for platform-managed environments.
Choose A Deployment Type
Section titled “Choose A Deployment Type”| Type | Best for | Guide |
|---|---|---|
| Docker Compose | Local development, evaluation, small single-host deployments | Install With Docker Compose |
| Kubernetes + Helm | Production deployments needing HA and platform-managed scaling | Install With Kubernetes And Helm |
| CLI-managed bundle (offline install) | Air-gapped hosts, or when you want to verify every file before it touches a server | Standalone Bundle Install |
| Fully manual bundle install | The CLI can’t run on the target host, or you’re troubleshooting a bundle install | Manual Bundle Install |
The last two both install the same self-contained “bundle” release (connector + bundled PostgreSQL + dashboard, with or without the env-enzo image depending on profile) via a signed release from Alien Giraffe’s release bucket, without needing this repository at all — use them for appliance-style or offline hosts. The first two run directly from this repository’s source and container images.
Each deployment type’s page is self-contained (prerequisites, install steps, verification, and upgrades). This page covers what’s shared across all of them: system requirements, the a10e.toml configuration reference, and what comes next.
For the RHEL version, use a10e install --channel connector-data-rhel as root. See Install the RHEL version for prerequisites, initial configuration, and the offline install command.
The a10e CLI needs Docker. If your RHEL host runs Podman only, or has no a10e CLI, skip the CLI and follow Manual Bundle Install end to end, including Using Podman instead of Docker and the Podman variant of the systemd unit in step 8.
System Requirements
Section titled “System Requirements”Minimum:
- 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 22.04+, Debian 12+)
Dependencies:
- Docker 20.10+ (Compose installs)
- Kubernetes 1.24+ and Helm 3.8+ (Kubernetes installs)
Configuration Reference
Section titled “Configuration Reference”Configuration file structure
Section titled “Configuration file structure”The primary platform configuration file is a10e.toml. connector resolves configuration in this order:
- Built-in defaults
a10e.toml- An operator config overlay at
/etc/a10e/config.toml, checked unconditionally on every start — see Persistent Platform Configuration for discovery rules, merge behavior, and a settings reference - Environment variables
- CLI flags
That means a10e.toml should define the baseline configuration for the deployment, while the overlay, environment variables, and flags remain available for overrides — the overlay is the persistent option when you want a change to survive without editing a10e.toml itself or relying on process-level environment variables.
The real fields, from a10e.toml.example:
env = "local"port = 8080
[db]dsn = "postgres://a10e_user:a10e_password@localhost:5432/a10e_db?sslmode=disable"max_open_conns = 25max_idle_conns = 25max_idle_time = "15m"
[cors]allowed_origins = ["http://localhost:3000", "http://localhost:8080"]
[expiry]default = "12h"max = "12h"
[deployment]driver = "docker"image_pull_policy = "Always"docker_network = "a10e-environments"
[enzo]image = "env-enzo:latest"dashboard_api_key = ""ecr_token = ""keystore_path = "./test-keystore.jks"keystore_password = "changeit"
[auth]provider = "local"jwt_secret = "change-me"auth0_domain = ""auth0_audience = ""auth0_bypass = false
[ai]provider = "ollama"model = "gemma3:1b"api_key = ""ollama_server_addr = ""generation_timeout = "10m"
[tunnels]default_provider = "cloudflare"edge_base_url = ""cloudflare_image = "cloudflare/cloudflared:latest"ngrok_image = "ngrok/ngrok:latest"
[health]probe_interval = "30m"
[fluentd]enabled = falseimage = "fluent/fluentd:v1.16-debian"
[fluentd.postgres]enabled = falsehost = "localhost"port = 5432database = "env_logs"user = "fluentd"password = ""
[fluentd.slack]enabled = falsewebhook_url = ""channel = "#env-logs"log_levels = "error,warn"
[fluentd.s3]enabled = falsebucket = ""region = "us-east-1"prefix = "logs/"flush_interval = "60s"access_key_id = ""secret_key = ""session_token = ""The major sections are:
- root fields such as
envandport [db]for PostgreSQL connection settings[cors]and[expiry]for API request behavior[deployment]for the container runtime model[enzo]for theenv-enzoruntime that powers enclave requests[auth]for authentication settings — see Identity Integration[ai]for AI provider configuration used by the catalog scanner’s summaries — see Catalog Scanning[tunnels]for public data-tunnel configuration — see Tunnel Architecture[health]for background health-probe intervals[fluentd]and its[fluentd.postgres]/[fluentd.slack]/[fluentd.s3]sub-tables for audit log streaming — see Auditing with FluentD
You can point the binary at an explicit file when needed:
env-manager serve -config /etc/a10e/a10e.tomlenv-manager catalog scan -config /etc/a10e/a10e.tomlenv-manager cleanup run -config /etc/a10e/a10e.tomlEnvironment variables
Section titled “Environment variables”Use environment variables for sensitive values or deployment-specific overrides:
# Requiredexport A10E_JWT_SECRET="your-secret-key-here"export A10E_DB_DSN="postgres://a10e:change-me@postgres:5432/a10e?sslmode=disable"
# Optionalexport AI_PROVIDER="ollama"export A10E_CONFIG_PATH="/etc/a10e/a10e.toml"These values override the matching settings from a10e.toml and from the config overlay described above. Note that -config / A10E_CONFIG_PATH only select which file is treated as the shipped baseline — they don’t redirect the overlay lookup, which stays independent; see Persistent Platform Configuration → Discovery if you point -config at a path under /etc/a10e/ yourself.
Generate a JWT secret
Section titled “Generate a JWT secret”openssl rand -hex 32export A10E_JWT_SECRET="generated-secret-here"Configure the AI provider
Section titled “Configure the AI provider”The catalog scanner can use an AI provider to generate schema/dataset summaries. The current provider surface in connector is:
ollamaopenaianthropicgoogleaivertexai
Runtime configuration is controlled with these environment variables:
AI_PROVIDERAI_MODELAI_API_KEYAI_OLLAMA_SERVER_ADDRGOOGLE_CLOUD_PROJECT/GOOGLE_CLOUD_LOCATION(orGOOGLE_CLOUD_REGION)GOOGLE_APPLICATION_CREDENTIALS
AI_MODEL should always be set explicitly. AI_API_KEY is required for the openai, anthropic, and googleai cloud providers. AI_OLLAMA_SERVER_ADDR is only used when AI_PROVIDER=ollama. GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, and GOOGLE_APPLICATION_CREDENTIALS apply only when AI_PROVIDER=vertexai. You can also run entirely without AI — follow the non-AI release-binary scan workflow, which also covers database/secret setup and diagnostic capture.
Local provider with Ollama:
export AI_PROVIDER="ollama"export AI_MODEL="gemma3:1b"export AI_OLLAMA_SERVER_ADDR="http://host.docker.internal:11434"If Alien Giraffe is running outside Docker, use the Ollama server address reachable from that host, such as http://localhost:11434.
Cloud provider with OpenAI:
export AI_PROVIDER="openai"export AI_MODEL="gpt-4.1"export AI_API_KEY="your-openai-api-key"Cloud provider with Anthropic:
export AI_PROVIDER="anthropic"export AI_MODEL="claude-3-5-sonnet-latest"export AI_API_KEY="your-anthropic-api-key"Cloud provider with Gemini (configured through the googleai provider value):
export AI_PROVIDER="googleai"export AI_MODEL="gemini-2.5-flash"export AI_API_KEY="your-google-ai-api-key"Cloud provider with Vertex AI:
export AI_PROVIDER="vertexai"export AI_MODEL="gemini-2.5-flash"export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"export GOOGLE_CLOUD_LOCATION="us-central1"export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"Vertex AI authenticates through Google’s Application Default Credentials rather than AI_API_KEY — point GOOGLE_APPLICATION_CREDENTIALS at a service account key file, or omit it entirely when running on GCP infrastructure (GKE, Cloud Run, Compute Engine) with a workload identity or attached service account already granted the Vertex AI User role. GOOGLE_CLOUD_LOCATION can also be supplied as GOOGLE_CLOUD_REGION.
Verify Alien Giraffe Is Running
Section titled “Verify Alien Giraffe Is Running”Whichever deployment type you chose, the API’s health endpoint is the common check:
curl http://localhost:8080/v1/healthcheck# {"success":true,"message":"Service is healthy"}For a fuller, ongoing health-check setup (including the bundled-PostgreSQL probe and a ready-to-run monitoring script), see Operations: Health Checks & Backups.
Next Steps
Section titled “Next Steps”- Configure Data Sources — connect to PostgreSQL, S3, or other data sources
- Catalog Scanning — discover schemas and datasets
- Create a Data Access Request from a Template — the end-to-end request flow
- Approve and Manage Requests — the admin review flow
- Users and Roles — set up RBAC
For additional help:
- Components Overview — understand core concepts
- API Reference — explore the API