Version 1.34.2 | Production Ready | Unreal Engine 5.5+
This comprehensive installation guide covers all methods of setting up the Supabase UE5 Plugin, including cloud service setup and self-hosted Docker deployment.
The Supabase UE5 Plugin provides seamless integration between Unreal Engine 5 and Supabase, supporting both cloud-hosted and self-hosted Supabase instances. This guide will walk you through:
Why Supabase Cloud?
Getting Started:
Create Supabase Account
Create New Project
Project Name: MyUE5Game
Database Password: [Generate secure password]
Region: [Select closest to your users]
Get Your Credentials
Project URL: https://your-project-id.supabase.coAnon/Public Key: eyJ... (for client-side operations)Service Role Key: eyJ... (for server-side operations)Advantages:
Requirements:
Clone Supabase Repository
git clone --depth 1 https://github.com/supabase/supabase
cd supabase/docker
Configure Environment
# Copy example environment file
cp .env.example .env
# Generate secure passwords
openssl rand -base64 32 # For JWT_SECRET
openssl rand -base64 32 # For POSTGRES_PASSWORD
Edit Configuration (.env file)
# Essential settings
STUDIO_DEFAULT_ORGANIZATION=Your Organization
STUDIO_DEFAULT_PROJECT=Your Project Name
# Security (CHANGE THESE!)
POSTGRES_PASSWORD=your-super-secure-password
JWT_SECRET=your-jwt-secret-from-step-2
ANON_KEY=your-generated-anon-key
SERVICE_ROLE_KEY=your-generated-service-key
# Optional: Custom domain
API_EXTERNAL_URL=http://localhost:8000
SUPABASE_PUBLIC_URL=http://localhost:8000
Start Services
# Start all services
docker compose up -d
# Check status
docker compose ps
Access Your Installation
http://localhost:3000http://localhost:8000localhost:5432Generate API Keys
# Install Supabase CLI
npm install -g supabase
# Generate keys
supabase gen keys --project-ref local
For production deployments, consider:
# docker-compose.production.yml
version: '3.8'
services:
studio:
environment:
- STUDIO_PG_META_URL=http://meta:8080
- PUBLIC_REST_URL=https://your-domain.com/rest/v1/
- PUBLIC_REALTIME_URL=wss://your-domain.com/realtime/v1/
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf
- ./ssl:/etc/nginx/ssl
1. Open Epic Games Launcher
2. Go to Unreal Engine → Marketplace
3. Search "Supabase Plugin by Seven Mountains Labs"
4. Click "Add to Project"
5. Select your UE5 project
Download Plugin
Install in Project
YourProject/
├── Plugins/
│ └── Supabase/ ← Extract here
│ ├── Supabase.uplugin
│ ├── Source/
│ └── Content/
Enable Plugin
# Clone into your project's Plugins folder
cd YourProject/Plugins
git clone https://github.com/seven-mountains-labs/supabase-ue5.git Supabase
# Generate project files
cd ../..
GenerateProjectFiles.bat # Windows
# or
./GenerateProjectFiles.sh # Mac/Linux
C++ Setup:
// In your GameInstance or main actor
void AMyGameInstance::BeginPlay()
{
Super::BeginPlay();
// Create connection object
USupabaseConnection* Connection = NewObject<USupabaseConnection>();
// Configure for Supabase Cloud
Connection->SupabaseServerUrl = TEXT("https://your-project.supabase.co");
Connection->SupabaseCredentials.AnonymousKey = TEXT("your-anon-key");
Connection->SupabaseCredentials.ServiceKey = TEXT("your-service-key");
Connection->ConnectionName = TEXT("Main");
// OR Configure for Self-Hosted
Connection->SupabaseServerUrl = TEXT("http://localhost:8000");
Connection->SupabaseCredentials.AnonymousKey = TEXT("your-local-anon-key");
Connection->SupabaseCredentials.ServiceKey = TEXT("your-local-service-key");
// Initialize
USupabaseManager::InitializeSupabase(this, Connection);
}
Blueprint Setup:
C++ Test:
void AMyGameInstance::TestSupabaseConnection()
{
if (USupabaseManager::IsConnected(this))
{
UE_LOG(LogTemp, Log, TEXT("✅ Supabase connected successfully!"));
// Test query
UAsyncQuery* QueryTask = UAsyncQuery::AsyncQuery(
this,
TEXT("users"), // table name
TEXT("*"), // columns
TArray<FQueryFilter>() // filters
);
QueryTask->OnSuccess.AddDynamic(this, &AMyGameInstance::OnTestQuerySuccess);
QueryTask->OnFailure.AddDynamic(this, &AMyGameInstance::OnTestQueryFailure);
QueryTask->Activate();
}
else
{
UE_LOG(LogTemp, Error, TEXT("❌ Supabase connection failed"));
}
}
In Supabase Studio (Cloud or Self-hosted):
-- Create a simple users table
CREATE TABLE users (
id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
email TEXT UNIQUE NOT NULL,
display_name TEXT,
avatar_url TEXT,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- Enable Row Level Security
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
-- Create policy for authenticated users
CREATE POLICY "Users can view own data" ON users
FOR SELECT USING (auth.uid() = id);
Development:
#if UE_BUILD_DEVELOPMENT
Connection->SupabaseServerUrl = TEXT("http://localhost:8000"); // Local Docker
#elif UE_BUILD_SHIPPING
Connection->SupabaseServerUrl = TEXT("https://your-prod.supabase.co"); // Production
#endif
Custom Connection Parameters:
Connection->RequestTimeout = 30.0f; // Request timeout in seconds
Connection->MaxRetryAttempts = 3; // Auto-retry failed requests
Connection->RealtimeHeartbeatInterval = 30.0f; // WebSocket keepalive
Connection->EnableLogging = true; // Detailed logging
Add to YourProject.Build.cs:
PublicDependencyModuleNames.AddRange(new string[] {
"Core",
"CoreUObject",
"Engine",
"Supabase" // Add this line
});
“Plugin not found” Error:
YourProject/Plugins/Supabase/Connection Timeout:
docker compose ps)Authentication Failures:
Self-Hosted Docker Issues:
# Check service logs
docker compose logs supabase-kong
docker compose logs supabase-auth
docker compose logs supabase-rest
# Restart services
docker compose restart
# Clean restart
docker compose down -v
docker compose up -d
Once installation is complete:
This installation guide is part of the comprehensive Supabase UE5 Plugin documentation. For the latest updates and detailed examples, visit our complete documentation.