interval / server

Interval Server is the central node used to run applications developed with the Interval SDK.

Interval Server

Interval Server is the central node used to run applications developed with the Interval SDK.

🚧 Note: Previously Interval Server was only available as a closed-source cloud service. Now, it is possible to run an instance yourself. This is a new direction for the Interval project and the fully open-source/self-hosted Interval Server application is still in early phases of development. If you encounter an issues setting up an Interval Server instance, please let us know by opening an issue!

Pre-requisites

Required dependencies

Database

Interval Server requires a Postgres database to work. In the future, especially for local development, we may ease this requirement.

We have tested Interval Server with Postgres versions 11.x and 12.x. Newer versions should work, but we do not plan to support anything older than 11.x.

Node.js

Interval Server is a pure Node.js application. Node.js version 16 or higher is required to run Interval Server.

Optional dependencies

• Postmark is used for sending application emails. In the future we may introduce a vendor-agnostic path for sending emails. If a POSTMARK_API_KEY environment variable is not provided when running Interval server, emails will not be sent.
• WorkOS is used for SSO, directory sync, and Sign in with Google. If WORKOS_API_KEY,WORKOS_CLIENT_ID, and WORKOS_WEBHOOK_SECRET environment variables are not provided when running Interval Server, these functions will not be available.
• Slack can be used to send notifications via Interval's notify methods. If SLACK_CLIENT_ID and SLACK_CLIENT_SECRET environment variables are not provided when running Interval Server, notifications cannot be sent via Slack.
• S3 can be used to support file uploads via Interval's file input methods. If S3_KEY_ID,S3_KEY_SECRET,S3_BUCKET, and S3_REGION environment variables are not provided when running Interval Server, file uploads will not function properly.

Required environment variables

• APP_URL is the URL where your Interval Server instance is running. For example: http://localhost:3000 or https://example.com.
• DATABASE_URL is the Postgres connection string. It should follow the format postgresql://username:password@host:port/dbname.
• SECRET is a secret that you must provide for use in encrypting passwords. Any string is valid for this value, but you should use something secure!
• WSS_API_SECRET is a secret that you must provide. It is used internally by Interval Server for communication between Interval services. Any string is valid for this value, but you should use something secure!
• AUTH_COOKIE_SECRET is a secret that you must provide for use in encrypting session cookies. Any string at least 32 characters in length is valid for this value, but you should use something secure!

Ports

Interval Server runs services on ports 3000 and 3033. The main service runs on 3000.

Running Interval Server locally

For development, you may wish to run an instance of Interval Server locally.

1. npm i -g @interval/server
2. From the directory where you would like to run Interval Server, create a .env file like this:

DATABASE_URL=<YOUR DATABASE URL>
SECRET=<YOUR SECRET VALUE>
APP_URL=<YOUR APP URL>
AUTH_COOKIE_SECRET=<YOUR AUTH COOKIE SECRET>
WSS_API_SECRET=<YOUR WSS API SECRET>

Note: you don't need to use a .env file. As long as the required variables are set, you should be good to go.

3. If you have not already setup a database, run interval-server db-init to initialize one.
4. Run interval-server start to run interval-server.
5. 🎉 Visit http://localhost:3000 to access your Interval Server!

Running Interval Server in production

Running Interval Server in production is largely the same as running in development. For convenience, we've created a Docker image to make this even easier.

The Interval Server Docker image is: docker.io/alexarena/interval-server:latest.

Many services like Render make it trivial to deploy Docker images with just a few clicks.

Important things to know:

• You'll still need to provide all required environment variables when running the Interval Server Docker image.
• Hosting providers like Render will automatically discover the Interval Server service running on port 3000 and will expose this port for you, but if your hosting provider doesn't do this, you'll have to handle exposing this yourself.

Connecting to Interval Server from your app

Once your Interval Server instance is up and running, it's trivial to connect to it from your Interval apps. Just add an endpoint property pointing to your Interval Server instance to the Interval SDK's constructor. For example:

const interval = new Interval({
  apiKey: process.env.INTERVAL_KEY,
  endpoint: 'wss://<YOUR INTERVAL SERVER URL>/websocket', // Don't forget the /websocket path!
})

Note: if you're running Interval Server locally, this URL will use the insecure ws:// protocol, not the secure wss:// version used in production deployments.

Available interval-server commands

Once you run npm i -g @interval/server, the following commands are available:

interval-server start

Starts Interval Server. See above for information on running Interval Server locally or in production.

interval-server db-init

Creates and sets up an Postgres database for use with Interval Server.

psql must be installed for this command to work.

You must provide a DATABASE_URL environment variable of the form postgresql://username:password@host:port/dbname when running this command.

By default, the db-init command will attempt to create a database with the name provided in your DATABASE_URL environment variable. If you've already created the database and just need to apply create the appropriate tables etc., you can run interval-server db-init --skip-create to skip the database creation step.

Contributing

For our initial release, we're focused on making it easy to setup and run your own Interval Server instance. We'll make it easier to contribute (and document how you can) in the future, but for now we aren't actively soliciting new contributions.

server's Issues

Remove the need to separately run `db-init` for docker deployed environments

Right now, the db-init command uses the psql command line to run the initSql, along with running a prisma db push.
For environments where you want to deploy with docker, this means you separately have to:

• Locally download the server to run the command line tool
• (in the future) as Interval releases more updates, run either prisma db push or skip create to get the new updates.

I am suggesting that instead, it would make more sense to automatically run this on startup.

• The initSql is already safe to run multiple times as it's calling IF NOT EXISTS and CREATE OR REPLACE. (Making the use of IF NOT EXISTS..etc a requirement for future versions of the initSql is also a good idea for updates!)
• Runs prisma db push, because this can run migrations from the updated files - which will be inside the Docker image. This is safe to run even if there are no changes, at only a low cost of startup time.

And even better, drop the requirement of psql and use a NodeJs postgres driver to run the SQL.

This means that deploying interval to a docker environment (especially one where the Postgres instance isn't publicly exposed to the internet) would simply be running the image and providing a valid connection string. The image would take care then of updating the database and ensuring it's ready to go.

With the current setup, if you were to deploy the :latest image, and for some reason it was to re-create the container, and update the image and there were Prisma changes, you'd run into an error during runtime without any warning.

This would also mean that Interval would be super easy to deploy in "one click" on sites that will deploy a database along side it from a template, but also in Kubernetes - it's unlikely you want to publicly expose your database. Right now I'd have to mess around with having interval installed locally, port-forwarding my database to my local machine, running that, and then applying a deployment file

Interval will not function when using a reverse proxy that removes headers with underscores

Some HTTP reverse proxies (such as nginx) will strip headers that contain an underscore. This entirely breaks interval because of the use of __interval_organization_id.

Further reading / example: https://www.grouparoo.com/blog/dont-use-underscores-in-http-headers
https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls/?highlight=underscore#missing-disappearing-http-headers

To ensure interval works out of the box everywhere, I suggest changing this header to interval-organization-id

Supporting file uploads when running on AWS should allow us not to configure `S3_REGION`, `S3_KEY_ID`, and `S3_KEY_SECRET`

Hi there!

We're running Interval Server on AWS ECS and we're currently getting some issues while trying to set up file uploads. The server requires us to pass S3_REGION, S3_KEY_ID, and S3_KEY_SECRET, but that should not be necessary when running it on AWS, as one can leverage using the task IAM role in order to access S3.

Some references:

• https://docs.aws.amazon.com/sdkref/latest/guide/feature-container-credentials.html
• https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html#credentialProviderChain

Current workaround

Our current workaround for this is to patch the code and remove the part where it sets the credentials for S3:

server/src/server/utils/uploads.ts

Lines 38 to 41 in 6e94996

	credentials: {
	accessKeyId: env.S3_KEY_ID,
	secretAccessKey: env.S3_KEY_SECRET,
	},

After installing interval-server, we're sed-ing dist/src/server/utils/uploads.js:

sed -i -e '/credentials: {/{N;N;N;d;}' "/usr/local/lib/node_modules/@interval/server/dist/src/server/utils/uploads.js"

This simply removes setting the credentials, letting the SDK resolve the credentials dynamically.

Possible solution

Ideally, we should be able to specify only the S3_BUCKET environment variable, and let the other options (S3_REGION, S3_KEY_ID, and S3_KEY_SECRET) be optional. This way, if they're present in the environment, we can use them, otherwise, we let the SDK resolve the credentials dynamically.

Something like this should probably work, although I haven't tested with this code exactly:

diff --git a/src/server/utils/uploads.ts b/src/server/utils/uploads.ts
index e85e31c..0629555 100644
--- a/src/server/utils/uploads.ts
+++ b/src/server/utils/uploads.ts
@@ -1,5 +1,6 @@
 import {
   S3Client,
+  S3ClientConfig,
   PutObjectCommand,
   GetObjectCommand,
   DeleteObjectsCommand,
@@ -24,6 +25,24 @@ function isS3Available(env: any): env is {
   )
 }
 
+function getS3ClientConfig(env: any): S3ClientConfig {
+  const config: S3ClientConfig = {
+    region: env.S3_REGION,
+  }
+
+  if (
+    typeof env.S3_KEY_ID === 'string' &&
+    typeof env.S3_KEY_SECRET === 'string'
+  ) {
+    config.credentials = {
+      accessKeyId: env.S3_KEY_ID,
+      secretAccessKey: env.S3_KEY_SECRET,
+    }
+  }
+
+  return config
+}
+
 export const S3_UPLOADS_ENABLED = isS3Available(env)
 
 function getS3Client() {
@@ -33,13 +52,7 @@ function getS3Client() {
     )
   }
 
-  return new S3Client({
-    region: env.S3_REGION,
-    credentials: {
-      accessKeyId: env.S3_KEY_ID,
-      secretAccessKey: env.S3_KEY_SECRET,
-    },
-  })
+  return new S3Client(getS3ClientConfig(env))
 }
 
 export async function getIOPresignedUploadUrl(key: string): Promise<string> {

Connection to Interval closed (code 1006) issue

I'm having trouble setting up Interval locally. I'm having trouble collecting to the Websocket server. I've attached the logs from my application and the interval instance here.

[email protected] sender address prevents email/account confirmation

In order to create Organization API Keys the account email needs to be confirmed. As per the documentation, a Postmark API key is required in order to send the emails. However, after creating a Postmark account and setting the key to the POSTMARK_API_KEY env var, I get the below error.

While your account is pending approval, all recipient addresses must share the same domain as the 'From' address. The domain of the 'From' address is 'interval.com', but you are attempting to send email to the following domain(s): 'MYCOMPANY.com'

Obviously this is a limitation on Postmark, but even when if the account is approved, I don't think emails should come from an interval.com address. It would be better to pass this as another env variable. I'm happy to submit a PR but wanted to check if there is anything else that needs to be taken into account.

This seems to be the line in question setting the from address:

server/src/emails/sender.ts

Line 92 in 0369bde

const from = 'Interval <[email protected]>'