Turborepo Remote Cache (TRRC)

To use a custom turborepo-remote-cache server instead of Vercel's, you must manually configure the connection. Note that turbo login and turbo link only work with Vercel's remote cache.

1. Create a configuration file

Create a .turbo/config.json file at the root of your repository and specify the apiurl:

{
  "apiurl": "http://cache.ducktors.dev"
}

2. Provide credentials

You must provide TURBO_TEAM and TURBO_TOKEN using one of the following three methods. Prefer using environment variables for security.

Method A: Environment Variables (Recommended)

Set TURBO_TEAM and TURBO_TOKEN as environment variables in your local shell or CI pipeline. These will override any values found in .turbo/config.json.

Method B: Config File

Add teamslug and token directly to .turbo/config.json.

Warning: Including the token in this file is less secure if you commit the file to version control.

{
  "apiurl": "http://cache.ducktors.dev",
  "teamslug": "ducktors",
  "token": "myGeneratedToken"
}

Method C: package.json Scripts (Not Recommended)

Pass --team and --token as flags to your turbo commands in package.json.

Warning: This is insecure as the token is committed to the repository.

{
  "scripts": {
    "build": "turbo run build --team=\"ducktors\" --token=\"myGeneratedToken\""
  }
}

This guide outlines how to deploy turborepo-remote-cache to Google Cloud using a Cloud Run service and a Cloud Storage bucket for persistence.

Step 1: Create a Cloud Storage Bucket

Create a bucket in the Cloud Storage console with these settings:

• Location type: Regional (closest to you).
• Storage class: Standard.
• Prevent public access: Enabled with Uniform access control.
• Data protection: Retention duration set to 0 days.
• Lifecycle rule (Recommended): Set a rule to automatically delete objects older than a few weeks to manage stale cache data.

Step 2: Deploy the Cloud Run Service

Deploy a new service in the Cloud Run console using the following configuration:

• Container Image: ducktors/turborepo-remote-cache:latest
• Region: Your closest region.
• Authentication: Disable Use Cloud IAM to authenticate incoming requests.
• Billing: Select Request-based billing.
• Scaling:
  • Minimum instances: 0
  • Maximum instances: 1 (The service uses a shared bucket and has not been tested with multiple concurrent instances).
• Ingress: Select All.
• Networking: Enable Use HTTP/2 end-to-end.

Container Settings

• Port: 3000
• Volumes:
  • Add a volume of type Cloud Storage bucket using the bucket created in Step 1.
  • Mount the volume at path: /turbo-cache
• Environment Variables: | Variable | Value | |---|---| | STORAGE_PROVIDER | local | | STORAGE_PATH | /turbo-cache | | STORAGE_PATH_USE_TMP_FOLDER | false | | TURBO_TOKEN | your_secret_key (a strong, random secret) | | HTTP2 | true |

Step 3: Configure Turborepo

Copy the Cloud Run service URL (ending in .run.app). Use this URL and your TURBO_TOKEN to configure your Turborepo project as described in the Enable custom remote caching guide.

To use Google Cloud Storage, set STORAGE_PROVIDER=google-cloud-storage and provide a bucket name via STORAGE_PATH. You must grant the Storage Object Admin role to your service account for the target bucket.

Option 1: Using static Service Account credentials

Use this method by providing the details from your service account JSON key file directly in your environment variables.

Option 2: Using Application Default Credentials (ADC)

Leave the GCS_* environment variables empty to allow the SDK to discover credentials automatically (e.g., via IAM roles or local ADC setup).

# Option 1: Static Credentials
STORAGE_PROVIDER=google-cloud-storage
STORAGE_PATH=<name-of-the-bucket>
GCS_PROJECT_ID=<project_id>
GCS_CLIENT_EMAIL=<client_email>
GCS_PRIVATE_KEY=<private_key>

# Option 2: Application Default Credentials (ADC)
STORAGE_PROVIDER=google-cloud-storage
STORAGE_PATH=<name-of-the-bucket>
GCS_PROJECT_ID=
GCS_CLIENT_EMAIL=
GCS_PRIVATE_KEY=