> ## Documentation Index
> Fetch the complete documentation index at: https://facetai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

## Architecture

Facet AI consists of two main components:

<CardGroup cols={2}>
  <Card title="Cloud Services" icon="server">
    * Dataset preprocessing microservice
    * Training orchestration microservice
    * Training, inference, evaluation GPU workers
    * Model export service
    * API Gateway for unified access
  </Card>

  <Card title="Frontend Application" icon="desktop">
    * Next.js web application
    * User authentication and dashboard
    * Model management interface
    * Real-time training monitoring
  </Card>
</CardGroup>

## Prerequisites

<Steps>
  <Step title="Google Cloud Platform Setup">
    <Tabs>
      <Tab title="Create GCP Project">
        1. Go to [Google Cloud Console](https://console.cloud.google.com)
        2. Create a new project or select an existing one
        3. Note your project ID for later use
        4. Enable billing on your project

        <Warning>
          Some APIs require billing to be enabled. Make sure billing is active before deployment.
        </Warning>
      </Tab>

      <Tab title="Install Required Tools">
        Install the required CLI tools. Use the official install guides for your OS when in doubt.

        ```bash theme={null}
        # 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](https://www.terraform.io/downloads)
        * Google Cloud CLI: [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install)
      </Tab>
    </Tabs>
  </Step>

  <Step title="Authentication Setup">
    1. Authenticate with Google Cloud:
       ```bash theme={null}
       gcloud auth login
       gcloud auth application-default login
       ```

    2. Set your project:
       ```bash theme={null}
       gcloud config set project YOUR_PROJECT_ID
       ```

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

    <Check>
      Verify setup with: `gcloud auth list` and `gcloud config get-value project`
    </Check>
  </Step>
</Steps>

<Note>
  Our Terraform IaC includes both production and staging setups. The staging workspace is intended mainly for development and testing; see the [staging section](#staging) for details.
</Note>

## Deploy Backend Services

<Steps>
  <Step title="Clone and Setup">
    1. Clone the cloud services repository:
       ```bash theme={null}
       git clone https://github.com/gemma-facet/cloud-services
       cd cloud-services/infrastructure
       ```

    2. Copy and edit the configuration files for your environment:
       ```bash theme={null}
       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:
       ```hcl theme={null}
       project_id = "your-project-id"
       region = "us-central1"
       ```
  </Step>

  <Step title="Initialize and Deploy">
    Use our automated deployment script:

    ```bash theme={null}
    make init ENV=production
    make full-deploy ENV=production
    make output ENV=production
    ```

    <Info>
      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)
    </Info>

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

  <Warning>
    Our IaC configures Firebase authentication (email/password) for you so the frontend can run out of the box. It does not enable Google OAuth by default. To add Google sign-in, go to Firebase Console → Authentication → Sign-in method and enable Google.
  </Warning>
</Steps>

## Deploy Frontend Application

<Steps>
  <Step title="Clone Frontend Repository">
    ```bash theme={null}
    git clone https://github.com/gemma-facet/frontend-ui
    cd frontend-ui
    ```
  </Step>

  <Step title="Configure Environment Variables">
    1. Copy the example environment file:
       ```bash theme={null}
       cp .env.example .env
       ```

    2. Fill in the environment variables from your backend deployment:
       ```bash theme={null}
       # 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
       ```
  </Step>

  <Step title="Running the Frontend">
    <Tabs>
      <Tab title="Run Locally">
        We recommend using `bun` for development, but `npm` or `yarn` also work.

        ```bash theme={null}
        npm run install
        npm run build
        npm run start
        ```

        <Tip>
          Access the app at `http://localhost:3000` in your browser.
        </Tip>
      </Tab>

      <Tab title="Deploy to Vercel">
        ```bash theme={null}
        # Install Vercel CLI
        npm i -g vercel

        # Deploy
        vercel deploy --prod
        ```

        <Tip>
          Vercel provides automatic deployments from GitHub and excellent performance for Next.js applications.
        </Tip>
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Infrastructure Management

### Available Commands

<AccordionGroup>
  <Accordion title="Deployment Commands">
    ```bash theme={null}
    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
    ```
  </Accordion>

  <Accordion title="Management Commands">
    ```bash theme={null}
    make plan           # Plan infrastructure changes
    make output         # Show deployment outputs
    make destroy        # Destroy all infrastructure
    make help           # Show all available commands
    ```
  </Accordion>

  <Accordion title="Build Commands">
    ```bash theme={null}
    make build          # Build all containers
    make deploy         # Deploy infrastructure only
    ```
  </Accordion>
</AccordionGroup>

### 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](https://github.com/gemma-facet/cloud-services/tree/main/infrastructure)

<Note>
  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.
</Note>

### Infrastructure Components

<CardGroup cols={2}>
  <Card title="Core Infrastructure" icon="building">
    * Google Cloud APIs and IAM roles
    * Artifact Registry for container images
    * Service accounts and permissions
  </Card>

  <Card title="Storage Layer" icon="database">
    * Google Cloud Storage buckets
    * Firestore database for metadata
    * Persistent disk volumes
  </Card>

  <Card title="Compute Services" icon="server">
    * Cloud Run services for microservices
    * Cloud Build for container building
    * Cloud Scheduler for batch jobs
  </Card>

  <Card title="Networking" icon="network-wired">
    * API Gateway for unified access
    * VPC and firewall rules
    * Load balancing and SSL certificates
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Resource Conflicts">
    **Resources already exist:**

    ```bash theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

<Note>
  **Need help with deployment?** Check our [GitHub repository](https://github.com/gemma-facet/cloud-services) for the latest updates and open an issue if you encounter problems.
</Note>