Self-hosting SuperTokens

See how you can run SuperTokens in your own infrastructure.

Overview

One of the main features of SuperTokens is that you can run it using your own resources. This way you have full control over the authentication data and you can scale based on your needs.

Before you start

To deploy the Core Service you must configure two things: the actual API and the database.

The core service can be deployed using a Docker image or directly inside your VM.
The supported database is PostgreSQL. The minimum required version is 13.0.

info

SuperTokens Core has dropped MySQL and MongoDB support with the 11.0.0 release. If you want to reference the old documentation, please open this page.

Steps

1. Install SuperTokens core

With docker

docker run -p 3567:3567 -d registry.supertokens.io/supertokens/supertokens-postgresql@latest

To see all the environment variables available, please see the README file.
The above command starts the container with an in-memory database. This means you do not need to connect it to PostgreSQL to test out SuperTokens.

Without docker

1. Download SuperTokens

1Visit the open source download page.

2Click on the "Binary" tab.

3Choose your database.

4Download the SuperTokens zip file for your OS.

Once downloaded, remove the zip, and you see a folder named supertokens.

2. Install SuperTokens

# sudo is required so that the supertokens 
# command can be added to your PATH variable.

cd supertokens
sudo ./install

important

After installing, you can delete the downloaded folder as you no longer need it.

Make any changes to the configuration in the config.yaml file in the installation directory, as specified in the output of the supertokens --help command.

3. Start the core service

Running the following command starts the service.

supertokens start [--host=...] [--port=...]

The above command starts the container with an in-memory database.
To see all available options please run supertokens start --help

Tip

To stop the service, run the following command:

supertokens stop

2. Test that the service is running

Open a browser and visit http://localhost:3567/hello. If you see a page that says Hello back, then the container started successfully!

If you are having issues with starting the docker image, please feel free to reach out over email or via Discord.

tip

The /hello route checks whether the database connection is correctly set up and only returns a 200 status code if there is no issue.

If you are using Kubernetes or docker swarm, this endpoint is perfect for doing readiness and liveness probes.

3. Connect the backend SDK with SuperTokens

The default port for SuperTokens is 3567. You can change this by binding a different port in the docker run command. For example, docker run -p 8080:3567 runs SuperTokens on port 8080 on your machine.
The connection info goes in the supertokens object in the init function on your backend:

import supertokens from "supertokens-node";

supertokens.init({
    supertokens: {
        connectionURI: "http://localhost:3567",
        apiKey: "someKey" // OR can be undefined
    },
    appInfo: {
        apiDomain: "...",
        appName: "...",
        websiteDomain: "..."
    },
    recipeList: []
});

Security

No API key exists by default. Check the API keys documentation to see how to add one.

4. Set up the database

4.1 Create a database Optional

CREATE DATABASE supertokens;

You can skip this step if you want SuperTokens to write to your own database. In this case, you need to provide your database's name as shown in the step below.

4.2 Connect SuperTokens to your database

With docker

caution

Host being localhost / 127.0.0.1 does not work in a docker image. Instead, please provide the database's local / public host name or IP address.

You also need to make the database listen on all the IPs of the local machine. Edit the postgresql.conf configuration file and set the value of listen_addresses to 0.0.0.0.

caution

It is important to use the postgresql:// scheme designator in the PostgreSQL Connection URI. Using postgres:// will lead to a startup error.

docker run \
    -p 3567:3567 \
    // highlight-next-line
    -e POSTGRESQL_CONNECTION_URI="postgresql://username:pass@host/dbName" \
    -d registry.supertokens.io/supertokens/supertokens-postgresql

# OR

docker run \
    -p 3567:3567 \
    // highlight-start
    -e POSTGRESQL_USER="username" \
    -e POSTGRESQL_PASSWORD="password" \
	-e POSTGRESQL_HOST="host" \
	-e POSTGRESQL_PORT="5432" \
    -e POSTGRESQL_DATABASE_NAME="supertokens" \
    // highlight-end
    -d registry.supertokens.io/supertokens/supertokens-postgresql

tip

You can also provide the table schema by setting the POSTGRESQL_TABLE_SCHEMA option.

Without docker

# You need to add the following to the config.yaml file.
# The file path can be found by running the "supertokens --help" command

postgresql_connection_uri: "postgresql://username:pass@host/dbName"

# OR

postgresql_user: "username"

postgresql_password: "password"

postgresql_host: "host"

postgresql_port: "5432"

postgresql_database_name: "supertokens"

You can also provide the table schema by setting the postgresql_table_schema option.

info

The required tables should create automatically if the database user has table creation permission. If not, you can create them manually using the following snippet.

4.3 Test the connection

To test, start SuperTokens and run the following query in your database

SELECT * FROM key_value;

If you see at least one row, it means that the connection has been successfully completed!

4.4 Rename database tables Optional

caution

If you already have tables created by SuperTokens, and then you rename them, SuperTokens creates new tables. Please be sure to migrate the data from the existing one to the new one.

You can add a prefix to all table names that SuperTokens manages. This way, all will be renamed in a way that has no clashes with your tables.

For example, two tables created by SuperTokens have the names emailpassword_users and thirdparty_users. If you add a prefix to them (something like "my_prefix"), then the tables become my_prefix_emailpassword_users and my_prefix_thirdparty_users.

docker run \
    -p 3567:3567 \
    // highlight-next-line
    -e POSTGRESQL_TABLE_NAMES_PREFIX="my_prefix" \ 
    -d registry.supertokens.io/supertokens/supertokens-postgresql

5. Add license keys

To access some features in your self-hosted service you must use license keys. You can sign up on SuperTokens to receive one.

Once you have the license key you need to manually add it to your SuperTokens Core Instance. To do this you have to call the Core API with the following request:

Add License Key
curl --location --request PUT <CORE_API_ENDPOINT>/ee/license \
     --header 'Content-Type: application/json' \
     --header 'api-key: <YOUR_API_KEY>' \
     --data-raw '{ "licenseKey": "<YOUR_LICENSE_KEY>" }'

References

Docker compose file

version: '3'

services:
  # Note: If you are assigning a custom name to your db service on the line below, make sure it does not contain underscores
  db:
    image: 'postgres:latest'
    environment:
      POSTGRES_USER: supertokens_user 
      POSTGRES_PASSWORD: somePassword 
      POSTGRES_DB: supertokens
    ports:
      - 5432:5432
    networks:
      - app_network
    restart: unless-stopped
    healthcheck:
      test: ['CMD', 'pg_isready', '-U', 'supertokens_user', '-d', 'supertokens']
      interval: 5s
      timeout: 5s
      retries: 5

  supertokens:
    image: registry.supertokens.io/supertokens/supertokens-postgresql@latest
    depends_on:
      db:
        condition: service_healthy
    ports:
      - 3567:3567
    environment:
      POSTGRESQL_CONNECTION_URI: "postgresql://supertokens_user:somePassword@db:5432/supertokens"
    networks:
      - app_network
    restart: unless-stopped
    healthcheck:
      test: >
        bash -c 'exec 3<>/dev/tcp/127.0.0.1/3567 && echo -e "GET /hello HTTP/1.1\r\nhost: 127.0.0.1:3567\r\nConnection: close\r\n\r\n" >&3 && cat <&3 | grep "Hello"'
      interval: 10s
      timeout: 5s
      retries: 5

networks:
  app_network:
    driver: bridge

important

If you are running the backend process that integrates with the backend SDK as part of the docker compose file as well, make sure to use http://supertokens:3567 as the connection URI instead of http://localhost:3567.

Helm charts for Kubernetes

For PostgreSQL image

Overview​

Before you start​

Steps​

1. Install SuperTokens core​

With docker​

Without docker​

1. Download SuperTokens​

2. Install SuperTokens​

3. Start the core service​

2. Test that the service is running​

3. Connect the backend SDK with SuperTokens​

4. Set up the database​

4.1 Create a database Optional​

4.2 Connect SuperTokens to your database​

With docker​

Without docker​

Database tables

4.3 Test the connection​

4.4 Rename database tables Optional​

5. Add license keys​

References​

Docker compose file​

Helm charts for Kubernetes​

Overview

Before you start

Steps

1. Install SuperTokens core

With docker

Without docker

1. Download SuperTokens

2. Install SuperTokens

3. Start the core service

2. Test that the service is running

3. Connect the backend SDK with SuperTokens

4. Set up the database

4.1 Create a database Optional

4.2 Connect SuperTokens to your database

With docker

Without docker

4.3 Test the connection

4.4 Rename database tables Optional

5. Add license keys

References

Docker compose file

Helm charts for Kubernetes