Which UI do you use?

Custom UI

Pre built UI

With Docker

Running the docker image 🚀

MySQL

docker run -p 3567:3567 -d registry.supertokens.io/supertokens/supertokens-mysql:

• To see all the env variables available, please see the README file.
• The above command will start the container with an in-memory database. This means you do not need to connect it to MySQL to test out SuperTokens.
• When you are ready to connect it to your database, please visit the Database setup section

PostgreSQL

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

• To see all the env variables available, please see the README file.
• The above command will start the container with an in-memory database. This means you do not need to connect it to PostgreSQL to test out SuperTokens.
• When you are ready to connect it to your database, please visit the Database setup section

MongoDB

docker run -p 3567:3567 -d registry.supertokens.io/supertokens/supertokens-mongodb

• To see all the env variables available, please see the README file.
• The above command will start the container with an in-memory database. This means you do not need to connect it to MongoDB to test out SuperTokens.
• When you are ready to connect it to your database, please visit the Database setup section

caution

We do not offer login functionality with MongDB yet. We only offer session management.

Testing 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 was started successfully!

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

tip

The /hello route checks whether the database connection is set up correctly and will only return 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.

Connecting 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 will run SuperTokens on port 8080 on your machine.
• The connection info will go in the supertokens object in the init function on your backend:

NodeJS

Important

For other backend frameworks, you can follow our guide on how to spin up a separate server configured with the SuperTokens backend SDK to authenticate requests and issue session tokens.

GoLang

import supertokens from "supertokens-node";

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

Python

import "github.com/supertokens/supertokens-golang/supertokens"

func main() {
    supertokens.Init(supertokens.TypeInput{
        Supertokens: &supertokens.ConnectionInfo{
            ConnectionURI: "http://localhost:3567",
            APIKey:        "someKey",
        },
    })
}

Other Frameworks

from supertokens_python import init, InputAppInfo, SupertokensConfig

init(
    app_info=InputAppInfo(api_domain="...", app_name="...", website_domain="..."),
    supertokens_config=SupertokensConfig(
        connection_uri='http://localhost:3567',
        api_key='someKey'
    ),
    framework='...', 
    recipe_list=[
      #...
   ]
)

Security

There is no API key by default. Visit the "Auth flow customization" -> "SuperTokens core settings" -> "Adding API Keys" section to see how to add one.

Docker compose file

MySQL

version: '3'

services:
  db:
    image: mysql:latest
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_USER: supertokens_user
      MYSQL_PASSWORD: somePassword
      MYSQL_DATABASE: supertokens
    ports:
      - 3306:3306
    networks:
      - app_network
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "mysqladmin", "ping", "-h", "localhost" ]
      timeout: 20s
      retries: 10

  supertokens:
    image: registry.supertokens.io/supertokens/supertokens-mysql:
    depends_on:
      db:
        condition: service_healthy
    ports:
      - 3567:3567
    environment:
      MYSQL_CONNECTION_URI: mysql://supertokens_user:somePassword@db:3306/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

PostgreSQL

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

MongoDB

We are working on adding this section.

important

If you are running the backend process that integrates with our 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 MySQL image

• For PostgreSQL image