turborepo-remote-cache

turborepo-remote-cache copied to clipboard

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

• [x] Local filesystem
• [x] AWS S3
• [ ] Azure Blob Storage (WIP)
• [ ] Google Cloud Storage (WIP)
• [ ] Google Drive Blobs (WIP)

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:

• Setting Credentials
• Setting Configuration

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.

Deployment Environments

• Deploy on Vercel
• Deploy on Docker
• Deploy on DigitalOcean
• Remoteless with npx

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.

1. create .turbo folder at the root of your monorepo
2. 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"
}

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

1. 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=

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

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

Deploy "remoteless" with npx

If you have Node.js installed, you can run the server simply by typing

npx turborepo-remote-cache

Note: Same env vars rules apply as for other deployments.

Contribute to this project

1. clone this repository

   git clone [email protected]:fox1t/turborepo-remote-cache.git

2. cd turborepo-remote-cache

3. npm i

4. cp .env.example .env

5. put your env vars to the env file. See ENV_VARS section for more details.

6. npm run dev