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. Based on your system OS, download the JRE from supertokens-jre, extract the ZIP, rename the folder to jre and put it in the supertokens-root folder.
4. Run ./startTestingEnv --wait
5. Open a new terminal in supertokens-root and run ls. Make sure you see core folder, plugin folder and the plugin-interface folder.
6. In supertokens-root, run cp temp/config.yaml .
7. If you want to install SuperTokens on your machine, run java -classpath "./cli/*" io.supertokens.cli.Main true install (you may need to use sudo, but first try without it). You can kill the process started in step 4. This should also remove the files / folders mentioned in step 5. Then check that SuperTokens is installed by running supertokens. Finally, to uninstall SuperTokens, run supertokens uninstall
8. If you do not want to install SuperTokens and just run the core using java directly, run java -Djava.security.egd=file:/dev/urandom -classpath "./core/*:./plugin-interface/*" io.supertokens.Main ./ in the supertokens-root folder.

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