Installation Guide

Game Framework can be deployed on your own infrastructure using Docker, Kubernetes, or directly on virtual machines. This guide covers all deployment options.

Prerequisites

Before installing Game Framework, ensure you have:

Docker 20.10+ and Docker Compose 2.0+ (for Docker deployment)
Kubernetes 1.24+ (for Kubernetes deployment)
PostgreSQL 14+ (managed or self-hosted)
MinIO or S3-compatible storage
Redis 6.0+ (optional but recommended)
Domain name with SSL certificate

System Requirements

Minimum requirements for production deployment:

CPU: 2 cores (4+ recommended)
RAM: 4 GB (8+ GB recommended)
Storage: 20 GB + storage for packages
Network: 100 Mbps (1 Gbps recommended)

Quick Start with Docker

The fastest way to get Game Framework running is with Docker Compose.

Clone the Repository

git clone https://github.com/yourusername/game-framework-backend
cd game-framework-backend

Configure Environment

Create a .env file with your configuration:

cp config.local.yaml.example config/config.local.yaml

Edit config/config.local.yaml:

server:
  host: 0.0.0.0
  port: 8080
  base_url: https://registry.yourcompany.com

database:
  host: postgres
  port: 5432
  database: game
  username: postgres
  password: your_secure_password

storage:
  type: minio
  endpoint: minio:9000
  access_key: minioadmin
  secret_key: your_secure_minio_password
  bucket: packages
  use_ssl: false

redis:
  host: redis
  port: 6379
  password: ""
  db: 0

auth:
  jwt_secret: your_secure_jwt_secret_here_min_32_chars
  token_expiry: 24h

Start Services

# Start all services
make docker-up

# Or use docker compose directly
docker-compose up -d

This starts:

Game Framework API (port 8080)
PostgreSQL (port 5432)
MinIO (port 9000, console: 9001)
Redis (port 6379)

Run Database Migrations

# Run migrations
make migrate-up

# Or using docker
docker-compose exec api ./bin/game migrate up

Verify Installation

Check that all services are running:

# Check service health
curl http://localhost:8080/health

# Expected response
{
  "status": "healthy",
  "version": "0.1.0",
  "database": "connected",
  "storage": "connected",
  "redis": "connected"
}

🎉 Game Framework is now running! Access the API at http://localhost:8080

Docker Production Deployment

For production, use environment variables and secrets management:

# docker-compose.prod.yml
version: '3.8'

services:
  api:
    image: gameframework/registry:latest
    restart: always
    ports:
      - "8080:8080"
    environment:
      - GF_SERVER_BASE_URL=https://registry.yourcompany.com
      - GF_DATABASE_HOST=postgres
      - GF_DATABASE_PASSWORD_FILE=/run/secrets/db_password
      - GF_STORAGE_ACCESS_KEY_FILE=/run/secrets/minio_access_key
      - GF_STORAGE_SECRET_KEY_FILE=/run/secrets/minio_secret_key
      - GF_AUTH_JWT_SECRET_FILE=/run/secrets/jwt_secret
    secrets:
      - db_password
      - minio_access_key
      - minio_secret_key
      - jwt_secret
    depends_on:
      - postgres
      - minio
      - redis
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  postgres:
    image: postgres:16-alpine
    restart: always
    environment:
      - POSTGRES_DB=game
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD_FILE=/run/secrets/db_password
    secrets:
      - db_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  minio:
    image: minio/minio:latest
    restart: always
    command: server /data --console-address ":9001"
    environment:
      - MINIO_ROOT_USER_FILE=/run/secrets/minio_access_key
      - MINIO_ROOT_PASSWORD_FILE=/run/secrets/minio_secret_key
    secrets:
      - minio_access_key
      - minio_secret_key
    volumes:
      - minio_data:/data
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 10s
      retries: 3

  redis:
    image: redis:7-alpine
    restart: always
    command: redis-server --requirepass $REDIS_PASSWORD
    environment:
      - REDIS_PASSWORD_FILE=/run/secrets/redis_password
    secrets:
      - redis_password
    volumes:
      - redis_data:/data

secrets:
  db_password:
    external: true
  minio_access_key:
    external: true
  minio_secret_key:
    external: true
  jwt_secret:
    external: true
  redis_password:
    external: true

volumes:
  postgres_data:
  minio_data:
  redis_data:

Deploy:

# Create secrets
echo "your_db_password" | docker secret create db_password -
echo "your_minio_key" | docker secret create minio_access_key -
echo "your_minio_secret" | docker secret create minio_secret_key -
echo "your_jwt_secret" | docker secret create jwt_secret -
echo "your_redis_password" | docker secret create redis_password -

# Deploy
docker-compose -f docker-compose.prod.yml up -d

# Initialize swarm
docker swarm init

# Create secrets
echo "your_db_password" | docker secret create db_password -
echo "your_minio_key" | docker secret create minio_access_key -
echo "your_minio_secret" | docker secret create minio_secret_key -
echo "your_jwt_secret" | docker secret create jwt_secret -

# Deploy stack
docker stack deploy -c docker-compose.prod.yml gameframework

# Check services
docker stack services gameframework

# Scale API service
docker service scale gameframework_api=3

All configuration can be provided via environment variables:

# Server Configuration
GF_SERVER_HOST=0.0.0.0
GF_SERVER_PORT=8080
GF_SERVER_BASE_URL=https://registry.yourcompany.com

# Database Configuration
GF_DATABASE_HOST=postgres.internal
GF_DATABASE_PORT=5432
GF_DATABASE_NAME=game
GF_DATABASE_USERNAME=postgres
GF_DATABASE_PASSWORD=secure_password

# Storage Configuration
GF_STORAGE_TYPE=s3
GF_STORAGE_ENDPOINT=s3.amazonaws.com
GF_STORAGE_REGION=us-east-1
GF_STORAGE_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
GF_STORAGE_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
GF_STORAGE_BUCKET=game-packages

# Redis Configuration
GF_REDIS_HOST=redis.internal
GF_REDIS_PORT=6379
GF_REDIS_PASSWORD=redis_password

# Auth Configuration
GF_AUTH_JWT_SECRET=your_jwt_secret_min_32_characters
GF_AUTH_TOKEN_EXPIRY=24h

Kubernetes Deployment

For production-grade deployments, use Kubernetes with Helm.

Add Helm Repository

helm repo add gameframework https://charts.gameframework.dev
helm repo update

Create Values File

Create values.yaml:

# values.yaml
replicaCount: 3

image:
  repository: gameframework/registry
  tag: "0.1.0"
  pullPolicy: IfNotPresent

service:
  type: LoadBalancer
  port: 80
  targetPort: 8080

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: registry.yourcompany.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: registry-tls
      hosts:
        - registry.yourcompany.com

config:
  server:
    baseUrl: https://registry.yourcompany.com
  
  database:
    host: postgres-postgresql
    port: 5432
    database: game
    existingSecret: game-postgres-secret
    secretKeys:
      username: username
      password: password
  
  storage:
    type: s3
    endpoint: s3.amazonaws.com
    region: us-east-1
    bucket: game-packages
    existingSecret: game-storage-secret
    secretKeys:
      accessKey: access-key
      secretKey: secret-key
  
  redis:
    host: redis-master
    port: 6379
    existingSecret: game-redis-secret
    secretKey: password

postgresql:
  enabled: true
  auth:
    database: game
    existingSecret: game-postgres-secret

redis:
  enabled: true
  auth:
    existingSecret: game-redis-secret

resources:
  limits:
    cpu: 2000m
    memory: 4Gi
  requests:
    cpu: 500m
    memory: 1Gi

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80
  targetMemoryUtilizationPercentage: 80

Create Secrets

# Create namespace
kubectl create namespace gameframework

# Create database secret
kubectl create secret generic game-postgres-secret \
  --from-literal=username=postgres \
  --from-literal=password=your_secure_password \
  -n gameframework

# Create storage secret (for S3)
kubectl create secret generic game-storage-secret \
  --from-literal=access-key=YOUR_ACCESS_KEY \
  --from-literal=secret-key=YOUR_SECRET_KEY \
  -n gameframework

# Create Redis secret
kubectl create secret generic game-redis-secret \
  --from-literal=password=your_redis_password \
  -n gameframework

# Create JWT secret
kubectl create secret generic game-jwt-secret \
  --from-literal=secret=your_jwt_secret_min_32_chars \
  -n gameframework

Install with Helm

helm install gameframework gameframework/game-registry \
  -f values.yaml \
  -n gameframework

Verify Deployment

# Check pods
kubectl get pods -n gameframework

# Check services
kubectl get svc -n gameframework

# Check ingress
kubectl get ingress -n gameframework

# View logs
kubectl logs -f -l app=gameframework -n gameframework

Cloud Provider Deployments

AWS Deployment

Deploy on AWS using ECS, EKS, or EC2 with RDS, S3, and ElastiCache

GCP Deployment

Deploy on GCP using GKE, Cloud Run, or Compute Engine with Cloud SQL and Cloud Storage

Azure Deployment

Deploy on Azure using AKS, Container Instances, or VMs with Azure Database and Blob Storage

See Cloud Provider Deployment Guide for detailed instructions.

SSL/TLS Configuration

For production, always use HTTPS with valid SSL certificates.

Using Let's Encrypt

# Install cert-manager
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

# Create ClusterIssuer
cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: admin@yourcompany.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx
EOF

Using Custom Certificates

# Create TLS secret
kubectl create secret tls registry-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key \
  -n gameframework

Post-Installation Steps

After installation, complete these steps:

Create First Admin User

# Using the API
curl -X POST https://registry.yourcompany.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@yourcompany.com",
    "password": "secure_password",
    "name": "Admin User"
  }'

Create Your First Workspace

# Get auth token
TOKEN=$(curl -X POST https://registry.yourcompany.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@yourcompany.com","password":"secure_password"}' \
  | jq -r '.token')

# Create workspace
curl -X POST https://registry.yourcompany.com/v1/workspaces \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-company",
    "display_name": "My Company"
  }'

Configure Flutter CLI

See Configuring Flutter CLI for detailed instructions.

# Add registry to pub credentials
flutter pub global activate game_cli
game auth login https://registry.yourcompany.com

Next Steps

Quick Start

Publish your first package

Configure Flutter

Set up Flutter CLI to use your registry

Operations Guide

Monitor and maintain your deployment

Troubleshooting

Having issues? Check our troubleshooting guide or contact support.

Common Issues

Database Connection Failed

# Check database connectivity
docker-compose exec api pg_isready -h postgres -U postgres

# View database logs
docker-compose logs postgres

Storage Not Accessible

# Check MinIO/S3 connectivity
docker-compose exec api curl -I http://minio:9000/minio/health/live

# View storage logs
docker-compose logs minio

API Not Starting

# View API logs
docker-compose logs api

# Check configuration
docker-compose exec api ./bin/game config validate