Self-hosting

Self-hosting Triplit

To enable sync, you need to run a Triplit server. The server is a Node.js application that talks to various Triplit clients over WebSockets and HTTP.

You have several options for running the server:

Docker

Each release of the server is published as a Docker image (opens in a new tab). You can deploy the server to a cloud provider like fly.io (opens in a new tab), DigitalOcean (opens in a new tab), or AWS. You'll also want to setup a volume to persist the database.

One-click deploy

Triplit is integrated with Railway (opens in a new tab), a cloud provider that supports one-click deploys. Read about how to deploy a Triplit server using Railway in our Triplit Cloud guide.

We plan on adding support for more cloud providers in the future. If you have a favorite cloud provider that you'd like to see integrated with Triplit, let us know by joining our Discord (opens in a new tab).

Building a custom server

The server is published as an NPM package, and you can install it by running:

npm install @triplit/server

The server also contains the remote Triplit database, which will persist data synced from your clients. The server supports different storage adapters, such as SQLite. Using the createServer function, you can create and configure a new server instance:

run.js
import { createServer } from '@triplit/server';
 
const port = +(process.env.PORT || 8080);
 
const startServer = createServer({
  storage: 'sqlite',
  verboseLogs: true,
});
 
const dbServer = startServer(port);
 
console.log('running on port', port);
process.on('SIGINT', function () {
  dbServer.close(() => {
    console.log('Shutting down server... ');
    process.exit();
  });
});

You can now deploy the server to a cloud provider that supports Git deploys, like Vercel (opens in a new tab), Netlify (opens in a new tab), or Render (opens in a new tab).

Storage

Triplit is designed to support any storage that can implement a key value store. You may specify the storage adapter you want to use by setting the storage option. Triplit provides some default configurations of our storage adapters, which you can use by setting the storage option to the appropriate string value for the adapter. These include:

⚠️

In-memory storage adapters are not durable and are not recommended for production use.

Typically this will use your LOCAL_DATABASE_URL environment variable so you'll want to make sure that's set.

You can also pass in an instance of an adapter or a function that returns an instance of an adapter.

function createAdapter() {
  return new MyCustomAdapter();
}
 
const startServer = createServer({
  storage: createAdapter,
});

Secrets

There are a few secrets that you need to provide to the server to enable certain features. If you are planning on using the Triplit Dashboard, you will need to set PROJECT_ID and JWT_SECRET to specific values associated with your project. Read the Triplit Cloud guide for more information.

PROJECT_ID

The server uses a PROJECT_ID to identify your project. You can set the PROJECT_ID environment variable to a unique identifier for your project. If you would like to connect to the Triplit Dashboard, this value should be the unique identifier for your project. You can find this value in the dashboard in your project's settings.

JWT_SECRET

The server uses JWT tokens to authenticate clients, and you need to provide a secret to sign and verify these tokens. You can set the secret by setting the JWT_SECRET environment variable. Triplit supports both symmetric (HS256) and asymmetric (RS256) encryption algorithms for JWTs. You will need to generate client tokens signed with the appropriate algorithm. With the PROJECT_ID and JWT_SECRET set, you can also use the triplit dev CLI to generate these tokens for you.

PROJECT_ID=your-project-id JWT_SECRET=your-secret triplit dev

You can also do it with the jsonwebtoken package (e.g. if you wanted to use asymmetric encryption) :

import jwt from 'jsonwebtoken';
 
const anonKey = jwt.sign(
  {
    'x-triplit-token-type': 'anon',
    'x-triplit-project-id': process.env.PROJECT_ID,
  },
  process.env.PUBLIC_KEY,
  { algorithm: 'RS256' }
);
 
const serviceKey = jwt.sign(
  {
    'x-triplit-token-type': 'secret',
    'x-triplit-project-id': process.env.PROJECT_ID,
  },
  process.env.PUBLIC_KEY,
  { algorithm: 'RS256' }
);

For more complicated authentication schemes, refer to our authentication guide.

LOCAL_DATABASE_URL (required for durable storage)

An absolute path on the server's file system to a directory where the server will store any database files. This is required for durable storage options: file, leveldb, lmdb, and sqlite.

EXTERNAL_JWT_SECRET (optional)

If you want your server to support JWTs signed by a second issuer, you can also set EXTERNAL_JWT_SECRET to that signing secret (or public key). The server will only authenticate signatures with this secret if the JWT has the x-triplit-token-type claim set to external. Any JWT that does not have this claim set will be authenticated with JWT_SECRET.

CLAIMS_PATH (optional)

If you are using custom JWTs with nested Triplit-related claims, you can set the CLAIMS_PATH environment variable. The server will read the Triplit claims at the path specified by CLAIMS_PATH. The JWT should also have the x-triplit-token-type claim set to external. Read the authentication guide for more information.

SENTRY_DSN (optional)

If you want to log errors to Sentry, you can set the SENTRY_DSN environment variable. The server will automatically log errors to Sentry.

VERBOSE_LOGS (optional)

If you want to log all incoming and outgoing messages and requests, you can set the VERBOSE_LOGS environment variable. This can be useful for debugging.

Triplit ConsoleLocal development