Building from source

Building from source can allow you to customise SuperTokens as per your needs. This is recommended only for advanced users who are experts in authentication and security.

Installing manually

1. Please follow the CONTRIBUTING.md file for instructions on how to setup a development environment, make changes to the code and run tests.
2. Make sure you are in the supertokens-root folder, and have supertokens-core, supertokens-plugin-interface and a SuperTokens plugin repo in it.
3. Run ./startTestingEnv --wait
4. Open a new terminal in supertokens-root and run ls. Make sure you see install, core folder, plugin folder and the plugin-interface folder.
5. Run cp ./supertokens-core/config.yaml ./
6. To install SuperTokens on your machine, run java -classpath "./cli/*" io.supertokens.cli.Main true $@ (you may need to use sudo, but first try without it)
7. You can kill the process started in step 3. This should also remove the files / folders mentioned in step 4.
8. Check that SuperTokens is installed by running supertokens
9. To uninstall SuperTokens, run supertokens uninstall

Creating a docker image

Due to the code architecture, one docker image only works with one database. For example, you can build a docker image that has SuperTokens and works with a MySQL database, or one that only works with MongoDB. In fact, we distribute a docker image for each supported database.

To build your own:

1. Please follow the CONTRIBUTING.md file for instructions on how to setup a development environment, make changes to the code and run tests.
2. Find the correct docker repo (for your database). For example, if you want to build a docker image with MySQL, there will be a repository called supertokens-docker-mysql
3. Clone the repo you found in the previous step and make sure that it's side-by-side to the supertokens-root folder.
4. Copy the supertokens-root folder into the cloned directory. For example, if building for MySQL, run cp -rf ./supertokens-root ./supertokens-docker-mysql
5. Download the linux JRE from supertokens-jre, extract the ZIP, rename the folder to jre and put it in the copied supertokens-root folder.
6. Go into the copied supertokens-root folder and run ./startTestingEnv --wait
7. Open a new terminal in the cloned docker repo, and run cp supertokens-root/supertokens-core/config.yaml supertokens-root/
8. Open the Dockerfile in an editor.
9. Remove the following lines (should be line number 2 onwards):

   ARG PLUGIN_NAME=mysql
   ARG PLAN_TYPE=FREE
   ARG CORE_VERSION=2.4.0
   ARG PLUGIN_VERSION=1.3.0
   RUN apt-get update && apt-get install -y curl zip
   RUN curl -o supertokens.zip -s -X GET \
      "https://api.supertokens.io/0/app/download?pluginName=$PLUGIN_NAME&os=linux&mode=DEV&binary=$PLAN_TYPE&targetCore=$CORE_VERSION&targetPlugin=$PLUGIN_VERSION" \
      -H "api-version: 0"
   RUN unzip supertokens.zip
   RUN cd supertokens && ./install
   

10. Replace the above lines with:

    RUN mkdir ./supertokens
    COPY ./supertokens-root/ ./supertokens
    RUN cd supertokens && ./jre/bin/java -classpath "./cli/*" io.supertokens.cli.Main true
    

11. Run the docker build command: docker build -t supertokens .
12. Start the docker container (default to using in-memory database): docker run -p 3567:3567 supertokens