Skip to main content

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