Environment Variables

Overview

SPEAR uses environment variables for configuration, allowing flexible deployment across different environments. Variables can be set via .env files, system environment, or systemd service configuration.

Required Variables

SPEAR_ENCRYPTION_KEY

Required - AES encryption key for sensitive data.

SPEAR_ENCRYPTION_KEY=your32characterencryptionkey1234

Requirement	Details
Length	Must be exactly 16, 24, or 32 characters
Purpose	Encrypts API keys and sensitive data in the database
Recommendation	Use 32 characters for AES-256 encryption

Validation: The application validates key length on startup and will fail if invalid:

Encryption key must be 16, 24, or 32 characters long. Current length: X

Generate a secure key:

# Generate 32-character key (recommended)
openssl rand -base64 24

# Or using /dev/urandom
head -c 32 /dev/urandom | base64 | head -c 32

Application Settings

SPEAR_PORT

Application port for the HTTP server.

SPEAR_PORT=8090

Default	8090
Range	1-65535

SPEAR_VERSION

Software version identifier (typically set during build).

SPEAR_VERSION=1.0.0

OpenAI Configuration

All OpenAI variables are optional and enable AI-powered features like text generation and grammar checking.

OPENAI_API_KEY

API key for OpenAI services.

OPENAI_API_KEY=sk-...

Get your key at: https://platform.openai.com/api-keys

OPENAI_MODEL

Model selection for AI features.

OPENAI_MODEL=gpt-3.5-turbo

Default	gpt-3.5-turbo
Options	gpt-4, gpt-4-turbo, gpt-3.5-turbo

OPENAI_API_URL

Custom endpoint URL for OpenAI-compatible APIs (e.g., Azure OpenAI).

OPENAI_API_URL=https://api.openai.com/v1/chat/completions

Default	https://api.openai.com/v1/chat/completions

OPENAI_MAX_TOKENS

Maximum tokens for AI responses.

OPENAI_MAX_TOKENS=1000

Default	1000

OPENAI_TEMPERATURE

Controls creativity/randomness of AI responses.

OPENAI_TEMPERATURE=0.7

Default	0.7
Range	0.0 (focused) to 1.0 (creative)

Development Settings

These variables are used for development and testing environments.

SPEAR_ADMIN_EMAIL

Admin email for seeding development data.

SPEAR_ADMIN_EMAIL=admin@example.com

SPEAR_ADMIN_PASSWORD

Admin password for seeding development data.

SPEAR_ADMIN_PASSWORD=yourpassword

Build-Time Variables

These variables are required when building SPEAR from source.

UPDATER_PUBLIC_KEY

Required for building - Public key for update signature verification.

UPDATER_PUBLIC_KEY=<base64-encoded-public-key>

Extract from your private key:

go run scripts/extract-public-key.go <private_key_b64>

CGO_ENABLED

Set to 0 for static builds.

CGO_ENABLED=0

GOOS / GOARCH

Cross-compilation targets.

GOOS=linux
GOARCH=amd64

GOOS	GOARCH Options
linux	amd64, arm64, arm
windows	amd64, arm64
darwin	amd64, arm64

Configuration Methods

Method 1: .env File

Create a .env file in the project root:

# Copy example and edit
cp .env.example .env
nano .env

Example .env file:

# Required
SPEAR_ENCRYPTION_KEY=your32characterencryptionkey1234

# Application
SPEAR_PORT=8090

# OpenAI (optional)
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-3.5-turbo
OPENAI_MAX_TOKENS=1000
OPENAI_TEMPERATURE=0.7

Method 2: System Environment Variables

Export variables in your shell profile (~/.bashrc, ~/.zshrc):

export SPEAR_ENCRYPTION_KEY="your32characterencryptionkey1234"
export SPEAR_PORT=8090

Method 3: Systemd Service File

The deployment script automatically configures environment variables in the systemd service file at /etc/systemd/system/spear.service:

[Service]
Environment=SPEAR_ENCRYPTION_KEY=<your-key>
Environment=SPEAR_VERSION=<version>
Environment=SPEAR_PORT=<port>

To modify after deployment:

# Edit the service file
sudo systemctl edit spear

# Add overrides in the editor:
[Service]
Environment=OPENAI_API_KEY=sk-...

# Reload and restart
sudo systemctl daemon-reload
sudo systemctl restart spear

Complete Example

Here’s a complete .env file for production:

# =============================================================================
# Application Settings (Required)
# =============================================================================

# AES encryption key - MUST be 16, 24, or 32 characters
# Generate with: openssl rand -base64 24
SPEAR_ENCRYPTION_KEY=your32characterencryptionkey1234

# Application port
SPEAR_PORT=8090

# =============================================================================
# OpenAI API Configuration (Optional - for AI-powered features)
# =============================================================================

# OpenAI API Key
# Get your key at: https://platform.openai.com/api-keys
OPENAI_API_KEY=sk-...

# Model selection (optional, defaults to gpt-3.5-turbo)
# Options: gpt-4, gpt-4-turbo, gpt-3.5-turbo
OPENAI_MODEL=gpt-3.5-turbo

# Custom endpoint URL (optional, for Azure OpenAI or compatible APIs)
OPENAI_API_URL=https://api.openai.com/v1/chat/completions

# Max tokens (optional, defaults to 1000)
OPENAI_MAX_TOKENS=1000

# Temperature - Lower = more focused, Higher = more creative
# Range: 0.0 to 1.0 (optional, defaults to 0.7)
OPENAI_TEMPERATURE=0.7

Security Best Practices

Never Commit .env Files

Add to .gitignore:

.env
.env.local
.env.production

Use Strong Encryption Keys

Always use 32 characters for maximum security (AES-256):

# Generate secure key
openssl rand -base64 24

Restrict File Permissions

# Restrict .env file permissions
chmod 600 .env

# For systemd service overrides
sudo chmod 600 /etc/systemd/system/spear.service.d/*.conf

Rotate Keys Periodically

When rotating the encryption key:

1. Export encrypted data
2. Update the encryption key
3. Re-encrypt sensitive data
4. Restart the service

Environment-Specific Files

Use separate files for different environments:

.env              # Local development
.env.staging      # Staging environment
.env.production   # Production (never commit)

Validation

Verify your environment configuration:

# Check encryption key length
echo -n "$SPEAR_ENCRYPTION_KEY" | wc -c

# Verify OpenAI connectivity (if configured)
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# Check loaded environment in running service
sudo systemctl show spear --property=Environment

Troubleshooting

Encryption Key Errors

Error: Encryption key must be 16, 24, or 32 characters long

Solution: Check key length and regenerate if necessary:

# Check current length
echo -n "$SPEAR_ENCRYPTION_KEY" | wc -c

# Generate new 32-character key
export SPEAR_ENCRYPTION_KEY=$(openssl rand -base64 24)

OpenAI Connection Issues

Error: Failed to connect to OpenAI API

Solutions:

1. Verify API key is valid
2. Check network connectivity
3. Verify custom URL if using OPENAI_API_URL

Service Not Reading Environment Variables

Solution: Ensure variables are in the systemd service file:

# Check current service environment
sudo systemctl show spear --property=Environment

# Reload after changes
sudo systemctl daemon-reload
sudo systemctl restart spear