Deploy Facet AI

Deploy Facet AI on your own cloud infrastructure for production use

Overview

Deploying Facet AI on your own infrastructure gives you complete control over your fine-tuning platform, data, and costs. This guide covers deploying both the backend services and frontend application.

Production Deployment: This deployment is recommended for production use, enterprise customers, or when you need full control over your infrastructure.

Architecture

Facet AI consists of two main components:

Cloud Services

• Dataset preprocessing microservice
• Training orchestration microservice
• Training, inference, evaluation GPU workers
• Model export service
• API Gateway for unified access

Frontend Application

• Next.js web application
• User authentication and dashboard
• Model management interface
• Real-time training monitoring

Prerequisites

1. Google Cloud Platform Setup

   Create GCP Project

   1. Go to Google Cloud Console
   2. Create a new project or select an existing one
   3. Note your project ID for later use
   4. Enable billing on your project

   Some APIs require billing to be enabled. Make sure billing is active before deployment.

   Install Required Tools

   Install the required CLI tools. Use the official install guides for your OS when in doubt.

   # macOS (Homebrew)
   brew install terraform
   brew install --cask google-cloud-sdk
   
   # Debian/Ubuntu (apt)
   # See https://www.terraform.io/downloads and https://cloud.google.com/sdk/docs/install
   sudo apt-get update && sudo apt-get install -y terraform
   # Follow GCP docs to install the Cloud SDK for your distro
   

   Refer to the official docs for other platforms:

   • Terraform: https://www.terraform.io/downloads
   • Google Cloud CLI: https://cloud.google.com/sdk/docs/install
2. Authentication Setup

   1. Authenticate with Google Cloud:

      gcloud auth login
      gcloud auth application-default login
      

   2. Set your project:

      gcloud config set project YOUR_PROJECT_ID
      

   3. Verify you have the correct permissions (Owner or Editor role)

   Verify setup with: gcloud auth list and gcloud config get-value project

Our Terraform IaC includes both production and staging setups. The staging workspace is intended mainly for development and testing; see the staging section for details.

Deploy Backend Services

1. Clone and Setup

   1. Clone the cloud services repository:

      git clone https://github.com/gemma-facet/cloud-services
      cd cloud-services/infrastructure
      

   2. Copy and edit the configuration files for your environment:

      cp environments/staging.tfvars.example environments/staging.tfvars
      cp environments/production.tfvars.example environments/production.tfvars
      

   3. Edit terraform.tfvars or the appropriate *.tfvars with your project details:

      project_id = "your-project-id"
      region = "us-central1"
      
2. Initialize and Deploy

   Use our automated deployment script:

   make init ENV=production
   make full-deploy ENV=production
   make output ENV=production
   

   The make full-deploy command performs these steps automatically:

   1. Deploy core infrastructure (APIs, IAM, Artifact Registry, Storage, Firebase, networking)
   2. Build and push Docker images to Artifact Registry
   3. Deploy microservices and configure networking (Cloud Run and API Gateway)

   Expect the deployment to take ~15-30 minutes depending on region and project size. The process runs unattended in most cases.

Deploy Frontend Application

1. Clone Frontend Repository

   git clone https://github.com/gemma-facet/frontend-ui
   cd frontend-ui
   
2. Configure Environment Variables

   1. Copy the example environment file:

      cp .env.example .env
      

   2. Fill in the environment variables from your backend deployment:

      # From terraform output
      INFERENCE_SERVICE_URL=https://your-inference-service-url
      API_GATEWAY_URL=https://your-api-gateway-url
      
      # Also from terraform output
      NEXT_PUBLIC_FIREBASE_API_KEY=your-firebase-api-key
      NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project-id.firebaseapp.com
      NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
      NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com
      NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your-messaging-sender-id
      NEXT_PUBLIC_FIREBASE_APP_ID=your-firebase-app-id
      
3. Running the Frontend

   Run Locally

   We recommend using bun for development, but npm or yarn also work.

   npm run install
   npm run build
   npm run start
   

   Access the app at http://localhost:3000 in your browser.

   Deploy to Vercel

   # Install Vercel CLI
   npm i -g vercel
   
   # Deploy
   vercel deploy --prod
   

   Vercel provides automatic deployments from GitHub and excellent performance for Next.js applications.

Infrastructure Management

Available Commands

Deployment Commands

make init           # Initialize Terraform
make check          # Validate configuration
make full-deploy    # Complete deployment workflow
make deploy-core    # Deploy core infrastructure only
make deploy-services # Deploy microservices only

Management Commands

make plan           # Plan infrastructure changes
make output         # Show deployment outputs
make destroy        # Destroy all infrastructure
make help           # Show all available commands

Build Commands

make build          # Build all containers
make deploy         # Deploy infrastructure only

Staging

The staging workspace in the Terraform setup is mainly intended for development and testing. If you’d like a staging environment for your own development, follow the guide in our repo to set up a staging workspace in three commands: https://github.com/gemma-facet/cloud-services/tree/main/infrastructure

Running npm run dev in the frontend will automatically connect to the staging backend since we use Next.js environment variables to differentiate between staging and production. You can manually edit this by changing the .env file.

Infrastructure Components

Core Infrastructure

• Google Cloud APIs and IAM roles
• Artifact Registry for container images
• Service accounts and permissions

Storage Layer

• Google Cloud Storage buckets
• Firestore database for metadata
• Persistent disk volumes

Compute Services

• Cloud Run services for microservices
• Cloud Build for container building
• Cloud Scheduler for batch jobs

Networking

• API Gateway for unified access
• VPC and firewall rules
• Load balancing and SSL certificates

Troubleshooting

Deployment Issues

Terraform errors:

• Ensure you have Owner/Editor role on the GCP project
• Check that billing is enabled
• Verify all required APIs are enabled

Authentication errors:

• Run gcloud auth application-default login
• Set quota project: gcloud auth application-default set-quota-project YOUR_PROJECT_ID

Service Issues

Cloud Run services not starting:

• Check container logs in Cloud Console
• Verify environment variables are set correctly
• Ensure service account has proper permissions

Firebase authentication not working:

• Enable Google sign-in in Firebase Console
• Verify OAuth client configuration
• Check Firebase config in frontend environment variables

Resource Conflicts

Resources already exist:

# Import existing resources to Terraform
terraform import module.compute.google_cloud_run_v2_service.preprocessing_service \
  projects/YOUR_PROJECT_ID/locations/us-central1/services/preprocessing-service

Need help with deployment? Check our GitHub repository for the latest updates and open an issue if you encounter problems.