turborepo-remote-cache: A TypeScript repository from dlehmhus

This project is an open-source implementation of the Turborepo custom remote cache server. If Vercel's official cache server isn't a viable option, this server is an alternative for self-hosted deployments. It supports several storage providers and deploys environments. Moreover, the project provides "deploy to " buttons for one-click deployments whenever possible.

Index

Supported Storage Providers
ENV VARS
Deployment Instructions
Enable custom remote caching in a Turborepo monorepo

Supported Storage Providers

ENV VARS

NODE_ENV: String. Optional. Possible values: development | production. Default value: production.
PORT: Number. Optional. Default value: 3000.
TURBO_TOKEN: String. Secret token used for the authentication. The value must be the same one provided for the token parameter of the build script. See Enable custom remote caching in a Turborepo monorepo for more info. This value should be private.
LOG_LEVEL: String. Optional. Default value: 'info'
STORAGE_PROVIDER: Optional. Possible values: local | s3. Default value: "local". Use this var to choose the storage provider.
STORAGE_PATH: String. Caching folder. If STORAGE_PROVIDER is set to s3, this will be the name of the bucket.

AWS Credentials and Region

AWS credentials and configuration are loaded as described in the AWS SDK documentation:

For example, you can set environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or create a file ~/.aws/credentials with AWS credentials.

Specify the region using the AWS_REGION environment variable, or in ~/.aws/config.

Enable custom remote caching in your Turborepo monorepo

To enable a custom remote caching server in your Turborepo monorepo, you must add a config file by hand. The turbo login command works only with the official Vercel server.

create .turbo folder at the root of your monorepo
create config.json file inside it, and add these properties:
- teamId: it could be any string that starts with "team_". This property will be used as a cache storage folder for the current repository. Ex. team_myteam
- apiUrl: address of a running turborepo-remote-cache server.

For example:

.turbo/config.json

{
  "teamId": "team_FcALQN9XEVbeJ1NjTQoS9Wup",
  "apiUrl": "http://localhost:3000"
}

Modify your Turborepo top-level build script, adding the --token= parameter. Note: The token value must be the same used for your TURBO_TOKEN env var. See ENV_VARS section for more info.

For example:

package.json

//...
  "build": "turbo run build --token=\"yourToken\"",
  "dev": "turbo run dev --parallel",
  "lint": "turbo run lint",
  "format": "prettier --write \"**/*.{ts,tsx,md}\""
//...

Enable remote caching in Docker

For some reason, the .turbo/config.json is not working in Docker containers. In order to enable remote caching in Docker, you need to pass the configuration via CLI arguments.

    "build": "turbo run build --team=\"team_awesome\" --token=\"turbotoken\" --api=\"https://your-caching.server.dev\"",

and add this to your Dockerfile before calling the turbo run build command:

ENV VERCEL_ARTIFACTS_TOKEN=turbotoken
ENV VERCEL_ARTIFACTS_OWNER=team_awesome

Deploy on Vercel

The server can be easily deployed as Vercel Function using the deploy button.

Note: Local storage isn't supported for this deployment method.

Deploy on Docker

You can find the image on the dockerhub.

create an .env file, containing all of the env vars you need. Check ENV_VARS for more info.

NODE_ENV=
PORT=
TURBO_TOKEN=
LOG_LEVEL=
STORAGE_PROVIDER=
STORAGE_PATH=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=
S3_ENDPOINT=

run the image using the .env file created on the step one.

docker run --env-file=.env -p 3000:3000 fox1t/turborepo-remote-cache

Deploy on DigitalOcean

The server can be easily deployed on DigitalOcean App Service.