AuthFramework Precompiled Releases - Deployment Guide

🚀 Quick Installation

AuthFramework provides precompiled binaries for easy deployment without needing Rust installed.

One-Line Installation

Linux/macOS:

curl -sSL https://raw.githubusercontent.com/ciresnave/auth-framework/main/scripts/install.sh | bash

Windows PowerShell (Run as Administrator):

iwr -useb https://raw.githubusercontent.com/ciresnave/auth-framework/main/scripts/install.ps1 | iex

Docker (Recommended for Production)

# Using Docker Compose
docker compose up -d

# Or using Docker directly
docker pull ghcr.io/ciresnave/auth-framework:latest
docker run -p 8080:8080 ghcr.io/ciresnave/auth-framework:latest

📦 Platform Support

Precompiled Binaries Available

Platform	Architecture	Binary Package
Linux (GNU)	x86_64 (Intel/AMD)	`authframework-vX.X.X-x86_64-unknown-linux-gnu.tar.gz`
Linux (musl)	x86_64 (Intel/AMD)	`authframework-vX.X.X-x86_64-unknown-linux-musl.tar.gz`
Linux (GNU)	aarch64 (ARM64)	`authframework-vX.X.X-aarch64-unknown-linux-gnu.tar.gz`
macOS	x86_64 (Intel)	`authframework-vX.X.X-x86_64-apple-darwin.tar.gz`
macOS	aarch64 (Apple Silicon)	`authframework-vX.X.X-aarch64-apple-darwin.tar.gz`
Windows	x86_64 (Intel/AMD)	`authframework-vX.X.X-x86_64-pc-windows-msvc.zip`
Windows	aarch64 (ARM64)	`authframework-vX.X.X-aarch64-pc-windows-msvc.zip`

🔧 Manual Installation

1. Download Binaries

Visit the releases page and download the appropriate package for your platform.

2. Extract Archive

Linux/macOS:

tar xzf authframework-v*.tar.gz

Windows:

Expand-Archive authframework-v*.zip

3. Install Binaries

Linux/macOS:

sudo install -m 755 authframework-server /usr/local/bin/
sudo install -m 755 authframework-cli /usr/local/bin/

Windows:

# Copy to Program Files
Copy-Item authframework-*.exe "C:\Program Files\AuthFramework\"

# Add to PATH
$env:Path += ";C:\Program Files\AuthFramework"
[Environment]::SetEnvironmentVariable("Path", $env:Path, "Machine")

4. Verify Installation

authframework-server --version
authframework-cli --version

⚙️ Configuration

Quick Start Configuration

The installation script creates a sample configuration at:

Linux/macOS: ~/.config/authframework/config.toml
Windows: %USERPROFILE%\.config\authframework\config.toml

Minimal Configuration

[server]
host = "127.0.0.1"
port = 8080

[storage]
backend = "sqlite"
connection_string = "/path/to/data.db"

[security]
secret_key = "GENERATE_A_SECURE_KEY_HERE"

[jwt]
issuer = "authframework"
access_token_ttl = 3600
refresh_token_ttl = 2592000

Generate Secure Keys

Linux/macOS:

openssl rand -base64 32

Windows:

[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))

Environment Variables

You can also configure using environment variables:

export SERVER_HOST="0.0.0.0"
export SERVER_PORT="8080"
export STORAGE_BACKEND="postgres"
export DATABASE_URL="postgresql://user:pass@localhost/authframework"
export SECRET_KEY="your-secret-key"
export JWT_ISSUER="authframework"
export RUST_LOG="info"

🐳 Docker Deployment

Using Docker Compose (Recommended)

Clone or download the docker-compose.yml:

curl -O https://raw.githubusercontent.com/ciresnave/auth-framework/main/docker-compose.yml

Create environment file (.env):

cat > .env << EOF
# Database
DB_PASSWORD=your_secure_db_password

# Redis
REDIS_PASSWORD=your_secure_redis_password

# JWT
JWT_SECRET=your_super_secret_jwt_key

# Security
SECRET_KEY=$(openssl rand -base64 32)
EOF

Start services:

# Start core services
docker compose up -d

# Start with monitoring (Prometheus + Grafana)
docker compose --profile monitoring up -d

# Start with admin tools (pgAdmin)
docker compose --profile admin up -d

# Start everything
docker compose --profile monitoring --profile admin up -d

Check status:

docker compose ps
docker compose logs -f authframework

Using Docker Directly

# Pull image
docker pull ghcr.io/ciresnave/auth-framework:latest

# Run with SQLite (simplest)
docker run -d \
  --name authframework \
  -p 8080:8080 \
  -e STORAGE_BACKEND=sqlite \
  -e SECRET_KEY="$(openssl rand -base64 32)" \
  -v authframework-data:/app/data \
  ghcr.io/ciresnave/auth-framework:latest

# Run with PostgreSQL
docker run -d \
  --name authframework \
  -p 8080:8080 \
  -e STORAGE_BACKEND=postgres \
  -e DATABASE_URL="postgresql://user:pass@postgres:5432/authframework" \
  -e SECRET_KEY="$(openssl rand -base64 32)" \
  --network your-network \
  ghcr.io/ciresnave/auth-framework:latest

Docker Tags

latest - Latest stable release
vX.Y.Z - Specific version
vX.Y - Latest patch for minor version
vX - Latest minor version for major version

🎯 Running as a Service

Linux (systemd)

The installation script can create a systemd service. Manually:

Create service file:

sudo tee /etc/systemd/system/authframework.service > /dev/null << EOF
[Unit]
Description=AuthFramework Authentication Server
After=network.target

[Service]
Type=simple
User=${USER}
WorkingDirectory=${HOME}
ExecStart=/usr/local/bin/authframework-server --config ${HOME}/.config/authframework/config.toml
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable authframework
sudo systemctl start authframework
sudo systemctl status authframework

View logs:

sudo journalctl -u authframework -f

macOS (launchd)

Create plist file:

cat > ~/Library/LaunchAgents/com.authframework.server.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.authframework.server</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/authframework-server</string>
        <string>--config</string>
        <string>${HOME}/.config/authframework/config.toml</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>${HOME}/Library/Logs/authframework.log</string>
    <key>StandardErrorPath</key>
    <string>${HOME}/Library/Logs/authframework-error.log</string>
</dict>
</plist>
EOF

Load and start:

launchctl load ~/Library/LaunchAgents/com.authframework.server.plist
launchctl start com.authframework.server

Windows (Service)

The PowerShell installation script can install as a Windows Service. Manually:

# Create service
New-Service -Name "AuthFramework" `
            -BinaryPathName '"C:\Program Files\AuthFramework\authframework-server.exe" --config "C:\Users\YourUser\.config\authframework\config.toml"' `
            -DisplayName "AuthFramework Server" `
            -Description "AuthFramework Authentication Server" `
            -StartupType Automatic

# Start service
Start-Service -Name "AuthFramework"

# Check status
Get-Service -Name "AuthFramework"

🔒 Production Checklist

Before deploying to production:

Security

Generate strong SECRET_KEY using crypto-secure random
Use strong database passwords
Enable HTTPS (use reverse proxy like nginx/Caddy)
Configure CORS appropriately
Enable rate limiting
Review firewall rules
Set up fail2ban or similar

Configuration

Use PostgreSQL/MySQL (not SQLite) for production
Configure Redis for session storage
Set appropriate JWT token TTLs
Configure proper logging level
Set up log rotation
Configure backup strategy

Monitoring

Set up health check monitoring
Configure metrics collection (Prometheus)
Set up alerting (PagerDuty, etc.)
Configure log aggregation (ELK, Loki, etc.)
Set up uptime monitoring

High Availability

Deploy multiple instances behind load balancer
Use managed database (AWS RDS, Azure Database, etc.)
Use Redis cluster for session storage
Configure automatic failover
Set up database replication

📊 Monitoring and Observability

Health Endpoints

# Basic health check
curl http://localhost:8080/health

# Detailed health (includes dependencies)
curl http://localhost:8080/health/detailed

# Readiness check
curl http://localhost:8080/readiness

# Liveness check
curl http://localhost:8080/liveness

# Prometheus metrics
curl http://localhost:8080/metrics

Prometheus Configuration

Create monitoring/prometheus.yml:

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'authframework'
    static_configs:
      - targets: ['authframework:8080']
    metrics_path: '/metrics'

Grafana Dashboard

Import the AuthFramework dashboard (ID: TBD) or create custom dashboards monitoring:

Request rate and latency
Authentication success/failure rates
Token issuance rates
Database connection pool stats
Memory and CPU usage

🔄 Updates and Upgrades

Check for Updates

# Check current version
authframework-server --version

# Check latest release
curl -s https://api.github.com/repos/ciresnave/auth-framework/releases/latest | grep tag_name

Update Installation

Using install script:

# Linux/macOS
curl -sSL https://raw.githubusercontent.com/ciresnave/auth-framework/main/scripts/install.sh | bash

# Windows
iwr -useb https://raw.githubusercontent.com/ciresnave/auth-framework/main/scripts/install.ps1 | iex

Docker:

docker compose pull
docker compose up -d

Database Migrations

# Run migrations
authframework-cli migrate up

# Check migration status
authframework-cli migrate status

# Rollback if needed
authframework-cli migrate down

🐛 Troubleshooting

Common Issues

Port already in use:

# Find process using port 8080
lsof -i :8080  # Linux/macOS
netstat -ano | findstr :8080  # Windows

# Change port in config or environment
export SERVER_PORT=8081

Database connection failed:

# Check database is running
pg_isready -h localhost -p 5432

# Test connection
psql -h localhost -U auth_user -d authframework

# Check connection string format
DATABASE_URL=postgresql://user:pass@host:5432/database

Permission denied:

# Linux/macOS: Fix binary permissions
chmod +x /usr/local/bin/authframework-server

# Check file ownership
ls -l /usr/local/bin/authframework-*

Enable Debug Logging

export RUST_LOG=debug
authframework-server

Getting Help

📚 Documentation: https://github.com/ciresnave/auth-framework/tree/main/docs
🐛 Issues: https://github.com/ciresnave/auth-framework/issues
💬 Discussions: https://github.com/ciresnave/auth-framework/discussions

📝 Next Steps

After installation:

Configure for your environment - Edit config.toml
Initialize database - Run migrations if using PostgreSQL
Create admin user - Use authframework-cli
Test endpoints - Use curl or Postman
Integrate with your app - Use SDK or REST API
Set up monitoring - Configure health checks and metrics
Deploy to production - Follow production checklist

🎉 Success

You now have AuthFramework running! Access the API documentation at:

http://localhost:8080/docs (Swagger UI when the API server is running)
http://localhost:8080/api/openapi.json (OpenAPI JSON)

For SDK examples, see:

JavaScript/TypeScript: sdks/javascript/
Python: sdks/python/
Go: sdks/go/ (coming soon)
Java: sdks/java/ (coming soon)

FilesExpand file tree

DEPLOYMENT_GUIDE.md

Latest commit

History

DEPLOYMENT_GUIDE.md

File metadata and controls

AuthFramework Precompiled Releases - Deployment Guide

🚀 Quick Installation

One-Line Installation

Docker (Recommended for Production)

📦 Platform Support

Precompiled Binaries Available

🔧 Manual Installation

1. Download Binaries

2. Extract Archive

3. Install Binaries

4. Verify Installation

⚙️ Configuration

Quick Start Configuration

Minimal Configuration

Generate Secure Keys

Environment Variables

🐳 Docker Deployment

Using Docker Compose (Recommended)

Using Docker Directly

Docker Tags

🎯 Running as a Service

Linux (systemd)

macOS (launchd)

Windows (Service)

🔒 Production Checklist

Security

Configuration

Monitoring

High Availability

📊 Monitoring and Observability

Health Endpoints

Prometheus Configuration

Grafana Dashboard

🔄 Updates and Upgrades

Check for Updates

Update Installation

Database Migrations

🐛 Troubleshooting

Common Issues

Enable Debug Logging

Getting Help

📝 Next Steps

🎉 Success