This blog will take you through connecting the SuperTokens core service with a MySQL or a PostgreSQL database with and without Docker.
\n\n\nThis is only applicable if you are self-hosting the SuperTokens core service.
\n
There are several methods for how you might want to run SuperTokens along with a database. In this blog, we will cover:
\nPlease feel free to navigate to the correct section based on your setup. In each section, we will be linking to the SuperTokens documentation wherever applicable so that this blog is not very lengthy.
\n\n\nAll the sections below assume that you will be using a Linux based operating system. For Windows, the syntax for some of the steps might be different, but the overall steps that need to be performed will be the same.
\n
Install SuperTokens on your local machine by following the self-hosted, without docker, instructions in the SuperTokens’ documentation.
\nConnect to the MySQL server on your local machine and create a database for SuperTokens to write to:
\ncreate database supertokens;If you already have a database for your application and want SuperTokens to create tables in that, you can skip this step.
\nCreate a MySQL user that has full access to the database created in the previous step. This user will be used by SuperTokens to create and write to the database tables:
\nCREATE USER 'supertokens_user'@'localhost' IDENTIFIED BY 'somePassword';GRANT ALL ON supertokens.* TO 'supertokens_user'@'localhost';FLUSH PRIVILEGES;Notice that we only allow this user to work via 'localhost'. This would only work if the SuperTokens core is running locally as well. If you are running the core in a different location, then you would need to replace 'localhost' in the above with '%'.
Edit the SuperTokens config.yaml file (located in /usr/lib/supertokens/config.yaml) to add the following config:
mysql_connection_uri: \"mysql://supertokens_user:somePassword@localhost:3306/supertokens\"\n\nMake sure that you put in the right values for the user, password, database name and location of your MySQL instance in the above connection uri string.
\n
Run SuperTokens by running supertokens start on your terminal:
supertokens start\n\nLoading storage layer.\nLoading MySQL config.\n...\nStarted SuperTokens on localhost:3567 with PID: ...Verify that it is setup correctly by querying the core service:
\ncurl http://localhost:3567/helloIf you get back a Hello reply, the core setup is done!
For this setup to work, we must connect SuperTokens and MySQL via the host machine’s network. For this, we will have to expose the MySQL db to the local IP.
\nStart by pulling the SuperTokens docker image that is compatible with MySQL:
\ndocker pull registry.supertokens.io/supertokens/supertokens-mysqlExpose MySQL server to all network interfaces on your machine. To do this, edit the my.cnf file (MySQL config file) to include:
bind-address = 0.0.0.0Be sure to restart your MySQL server after saving the file.
\nConnect to the MySQL server on your local machine and create a database for SuperTokens to write to:
\ncreate database supertokens;If you already have a database for your application and want SuperTokens to create tables in that, you can skip this step.
\nCreate a MySQL user that has full access to the database created in the previous step. This user will be used by SuperTokens to create and write to the database tables:
\nCREATE USER 'supertokens_user'@'%' IDENTIFIED BY 'somePassword';GRANT ALL ON supertokens.* TO 'supertokens_user'@'%';FLUSH PRIVILEGES;Run the SuperTokens docker image with the env var specifying the MySQL connection URI:
\ndocker run \\\n -p 3567:3567 \\\n --network=host \\\n -e MYSQL_CONNECTION_URI=\"mysql://supertokens_user:somePassword@192.168.1.1:3306/supertokens\" \\\n -d registry.supertokens.io/supertokens/supertokens-mysql\n\nBe sure to replace
\n192.168.1.1with the correct IP of your system.
This will start the docker image in the background. You can find it by running:
\ndocker psIf you want to run it in the foreground, you can remove the -d option from the docker run command.
Verify that it is setup correctly by querying the core service:
\ncurl http://localhost:3567/helloIf you get back a Hello reply, the core setup is done!
Install SuperTokens on your local machine by following the self-hosted, without docker, instructions in the SuperTokens’ documentation.
\nStart the MySQL docker container:
\ndocker run \\\n -e MYSQL_ROOT_PASSWORD=root \\\n -e MYSQL_USER=supertokens_user \\\n -e MYSQL_PASSWORD=somePassword \\\n -e MYSQL_DATABASE=supertokens \\\n --network=host \\\n -p 3306:3306 \\\n -d mysqlThe above will start the mysql db with a new database called supertokens. SuperTokens core will store the data in this database. If instead, you want the data to be stored in an existing db, please provide that db’s name instead.
Edit the SuperTokens config.yaml file (located in /usr/lib/supertokens/config.yaml) to add the following config:
mysql_connection_uri: \"mysql://supertokens_user:somePassword@localhost:3306/supertokens\"\n\nMake sure that you put in the right values for the user, password, database name and location of your MySQL instance in the above connection uri string.
\n
Run SuperTokens by running supertokens start on your terminal:
supertokens start\n\nLoading storage layer.\nLoading MySQL config.\n...\nStarted SuperTokens on localhost:3567 with PID: ...Verify that it is setup correctly by querying the core service:
\ncurl http://localhost:3567/helloIf you get back a Hello reply, the core setup is done!
Start by pulling the SuperTokens docker image that is compatible with MySQL:
\ndocker pull registry.supertokens.io/supertokens/supertokens-mysqlStart the MySQL docker container:
\ndocker run \\\n -e MYSQL_ROOT_PASSWORD=root \\\n -e MYSQL_USER=supertokens_user \\\n -e MYSQL_PASSWORD=somePassword \\\n -e MYSQL_DATABASE=supertokens \\\n --network=host \\\n -p 3306:3306 \\\n -d mysqlThe above will start the mysql db with a new database called supertokens. SuperTokens core will store the data in this database. If instead, you want the data to be stored in an existing db, please provide that db’s name instead.
Run the SuperTokens docker image with the env var specifying the MySQL connection URI:
\ndocker run \\\n -p 3567:3567 \\\n --network=host \\\n -e MYSQL_CONNECTION_URI=\"mysql://supertokens_user:somePassword@192.168.1.1:3306/supertokens\" \\\n -d registry.supertokens.io/supertokens/supertokens-mysql\n\nBe sure to replace
\n192.168.1.1with the correct IP of your system.
This will start the docker image in the background. You can find it by running:
\ndocker psIf you want to run it in the foreground, you can remove the -d option from the docker run command.
Verify that it is setup correctly by querying the core service:
\ncurl http://localhost:3567/helloIf you get back a Hello reply, the core setup is done!
Use the following docker compose file. You can call it docker-compose.yaml
version: '3'\n\nservices:\n db:\n image: mysql:latest\n environment:\n MYSQL_ROOT_PASSWORD: root\n MYSQL_USER: supertokens_user\n MYSQL_PASSWORD: somePassword\n MYSQL_DATABASE: supertokens\n ports:\n - 3306:3306\n networks:\n - app_network\n restart: unless-stopped\n healthcheck:\n test: [ \"CMD\", \"mysqladmin\", \"ping\", \"-h\", \"localhost\" ]\n timeout: 20s\n retries: 10\n\n supertokens:\n image: registry.supertokens.io/supertokens/supertokens-mysql\n depends_on:\n - db\n ports:\n - 3567:3567\n environment:\n MYSQL_CONNECTION_URI: mysql://supertokens_user:somePassword@db:3306/supertokens\n networks:\n - app_network\n restart: unless-stopped\n healthcheck:\n test: >\n 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\"'\n interval: 10s\n timeout: 5s\n retries: 5\n\nnetworks:\n app_network:\n driver: bridgeYou can run the following command to start the service:
\ndocker-compose upVerify that it is setup correctly by querying the core service:
\ncurl http://localhost:3567/helloIf you get back a Hello reply, the core setup is done!
Install SuperTokens on your local machine by following the self-hosted, without docker, instructions in the SuperTokens’ documentation.
\nConnect to the PostgreSQL server on your local machine and create a database for SuperTokens to write to:
\nCREATE DATABASE supertokens;If you already have a database for your application and want SuperTokens to create tables in that, you can skip this step.
\nCreate a PostgreSQL user that has full access to the database created in the previous step. This user will be used by SuperTokens to create and write to the database tables:
\nCREATE USER supertokens_user WITH ENCRYPTED PASSWORD 'somePassword';GRANT ALL PRIVILEGES ON DATABASE supertokens TO supertokens_user;Edit the SuperTokens config.yaml file (located in /usr/lib/supertokens/config.yaml) to add the following config:
postgresql_connection_uri: \"postgresql://supertokens_user:somePassword@localhost:5432/supertokens\"\n\nMake sure that you put in the right values for the user, password, database name and location of your postgreSQL instance in the above connection uri string.
\n
Run SuperTokens by running supertokens start on your terminal:
\nsupertokens start\n\nLoading storage layer.\nLoading PostgreSQL config.\n...\nStarted SuperTokens on localhost:3567 with PID: ...Verify that it is setup correctly by querying the core service:
\ncurl http://localhost:3567/helloIf you get back a Hello reply, the core setup is done!
For this setup to work, we must connect SuperTokens and PostgreSQL via the host machine’s network. For this, we will have to allow PostgreSQL to allow incomming client connections over the network.
\nStart by pulling the SuperTokens docker image that is compatible with PostgreSQL:
\ndocker pull registry.supertokens.io/supertokens/supertokens-postgresqlAllow incoming client connections to your PostgreSQL database over your network by adding the following lines to the postgresql.confand pg_hba.conf file.
postgresql.conf
listen_addresses = '0.0.0.0'pg_hba.conf
host all all 0.0.0.0/0 md5Connect to the PostgreSQL server on your local machine and create a database for SuperTokens to write to:
\nCREATE DATABASE supertokens;If you already have a database for your application and want SuperTokens to create tables in that, you can skip this step.
\nCreate a PostgreSQL user that has full access to the database created in the previous step. This user will be used by SuperTokens to create and write to the database tables:
\nCREATE USER supertokens_user with encrypted password 'somePassword';GRANT ALL PRIVILEGES ON DATABASE supertokens TO supertokens_user;Run the SuperTokens docker image with the env var specifying the PostgreSQL connection URI:
\ndocker run \\\n -p 3567:3567 \\\n --network=host \\\n -e POSTGRESQL_CONNECTION_URI=\"postgresql://supertokens_user:somePassword@192.168.1.1:5432/supertokens\" \\\n -d registry.supertokens.io/supertokens/supertokens-postgresql\n\n\nBe sure to replace
\n192.168.1.1with the correct IP of your system.
This will start the docker image in the background. You can find it by running:
\ndocker psIf you want to run it in the foreground, you can remove the -d option from the docker run command.
Verify that it is setup correctly by querying the core service:
\ncurl http://localhost:3567/helloIf you get back a Hello reply, the core setup is done!
Install SuperTokens on your local machine by following the self-hosted, without docker, instructions in the SuperTokens’ documentation.
\nStart the PostgreSQL docker container:
\ndocker run \\\n -e POSTGRES_USER=root \\\n -e POSTGRES_PASSWORD=root \\\n --network=host \\\n -p 5432:5432 \\\n -d postgres \\\n -c listen_addresses=0.0.0.0The above will start the PostgreSQL db. You will need to connect to the database and create a user with the privileges.
\nCREATE DATABASE supertokens;If you already have a database for your application and want SuperTokens to create tables in that, you can skip this step.
\nCreate a PostgreSQL user that has full access to the database created in the previous step. This user will be used by SuperTokens to create and write to the database tables:
\nCREATE USER supertokens_user with encrypted password 'somePassword';GRANT ALL PRIVILEGES ON DATABASE supertokens TO supertokens_user;Edit the SuperTokens config.yaml file (located in /usr/lib/supertokens/config.yaml) to add the following config:
postgresql_connection_uri: \"postgresql://supertokens_user:somePassword@localhost:5432/supertokens\"\n\nMake sure that you put in the right values for the user, password, database name and location of your PostgreSQL instance in the above connection uri string.
\n
Run SuperTokens by running supertokens start on your terminal:
supertokens start\n\nLoading storage layer.\nLoading PostgreSQL config.\n...\nStarted SuperTokens on localhost:3567 with PID: ...Verify that it is setup correctly by querying the core service:
\ncurl http://localhost:3567/helloIf you get back a Hello reply, the core setup is done!
Start by pulling the SuperTokens docker image that is compatible with PostgreSQL:
\ndocker pull registry.supertokens.io/supertokens/supertokens-postgresqlStart the PostgreSQL docker container:
\ndocker run \\\n -e POSTGRES_USER=root \\\n -e POSTGRES_PASSWORD=root \\\n --network=host \\\n -p 5432:5432 \\\n -d postgres \\\n -c listen_addresses=0.0.0.0The above will start the PostgreSQL db. You will need to connect to the database and create a user with the privileges.
\nCREATE DATABASE supertokens;If you already have a database for your application and want SuperTokens to create tables in that, you can skip this step.
\nCreate a PostgreSQL user that has full access to the database created in the previous step. This user will be used by SuperTokens to create and write to the database tables:
\nCREATE USER supertokens_user with encrypted password 'somePassword';GRANT ALL PRIVILEGES ON DATABASE supertokens TO supertokens_user;Run the SuperTokens docker image with the env var specifying the PostgreSQL connection URI:
\ndocker run \\\n -p 3567:3567 \\\n --network=host \\\n -e POSTGRESQL_CONNECTION_URI=\"postgresql://supertokens_user:somePassword@192.168.1.1:5432/supertokens\" \\\n -d registry.supertokens.io/supertokens/supertokens-postgresql\n\n\nBe sure to replace
\n192.168.1.1with the correct IP of your system.
This will start the docker image in the background. You can find it by running:
\ndocker psIf you want to run it in the foreground, you can remove the -d option from the docker run command.
Verify that it is setup correctly by querying the core service:
\ncurl http://localhost:3567/helloIf you get back a Hello reply, the core setup is done!
Use the following docker compose file. You can call it docker-compose.yaml
version: '3'\n\nservices:\n db:\n image: 'postgres:latest'\n environment:\n POSTGRES_USER: supertokens_user \n POSTGRES_PASSWORD: somePassword \n POSTGRES_DB: supertokens\n ports:\n - 5432:5432\n networks:\n - app_network\n restart: unless-stopped\n healthcheck:\n test: ['CMD', 'pg_isready', '-U', 'supertokens_user', '-d', 'supertokens']\n interval: 5s\n timeout: 5s\n retries: 5\n\n supertokens:\n image: registry.supertokens.io/supertokens/supertokens-postgresql\n depends_on:\n - db\n ports:\n - 3567:3567\n environment:\n POSTGRESQL_CONNECTION_URI: \"postgresql://supertokens_user:somePassword@db:5432/supertokens\"\n networks:\n - app_network\n restart: unless-stopped\n healthcheck:\n test: >\n 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\"'\n interval: 10s\n timeout: 5s\n retries: 5\n\nnetworks:\n app_network:\n driver: bridge\n You can run the following command to start the service:
\ndocker-compose upVerify that it is setup correctly by querying the core service:
\ncurl http://localhost:3567/helloIf you get back a Hello reply, the core setup is done!