STEP BY STEP GUIDE

Create a Flux dApp

Are you ready to create the next great decentralized application and disrupt with us on Web 3.0? Let's go!

Windows 10/11 Guide

Prerequisites

  • Windows 10 or 11
  • WSL 2 (Windows Subsystem for Linux - Ubuntu)
  • Stop / Disable any previously installed web servers on your system
  • An account on https://hub.docker.com/ (Docker Username aka Docker ID)
  • A terminal (Such as Windows Powershell)
  • A Code Editor such as VS Code, Atom or Notepad++
  • Zelcore Wallet and Zelcore ID https://zelcore.io/
  • Supported Browser for ZelCore Wallet: Chrome / Edge / Brave

Guide to Creating a Flux dApp

Install Basic Tools

  1. Download and install WSL 2 ( Windows Subsystem for Linux )
  2. Click on START and type in POWERSHELL
  3. Click on RUN AS ADMINISTRATOR
  4. When the command line opens type in:
  5. WSL ––install -d ubuntu
    The following will appear after typing the command:

  6. Restart computer
  7. Open up the newly installed program UBUNTU and follow the instructions for the first time install. E.G: it may ask for a new username, password etc
  8. When the command prompt comes up, type: sudo apt update
  9. This will update the core system ahead of the new installs coming up

  10. Download and install Docker Desktop by following these steps:
    • https://www.docker.com/products/docker-desktop
    • Open Docker and skip the tutorial
    • Sign in to Docker (top right) and create a Docker account if you don't have one already
    • Click on SETTINGS > RESOURCES > WSL INTEGRATION > Checkmark both options
    • Enable integration with my default WSL distro
    • Ubuntu
    • Click Apply & Restart
  11. Create a Sample dApp

    This guide explains how to create a simple html / javascript dApp:

  12. Create a folder somewhere on your computer called noderank ... E.G: C:\noderank
  13. In that new folder, create a file called index.html and save the following:
  14. < html >

    < head >

      < meta   name = "viewport"   content = "width=device-width, initial-scale=1" >

      < title >Node Rank</ title >

      < script   src = " https://code.jquery.com/jquery-3.6.0.min.js " ></ script >

      < script >

      function getNodeStats (){

        if ( $ ( "#node_ip" ). val ())

        {

          var settings = {

                    "cache" :   false ,

                    "dataType" :  "jsonp",

                    "async" :   true ,

                    "crossDomain" :   true ,

                    "url" :  " https://explorer.flux.zelcore.io/api/fluxnode/listfluxnodes/ " + $ ( "#node_ip" ). val () ,

                    "method" :  "GET",

                    "headers" :  {

                        "accept" :  "application/json",

                        "Access-Control-Allow-Origin" : "*"

              }

          }

          $ . ajax (settings). done ( function  (data) {

              if (data. result [ 0 ]. ip   ==   $ ( "#node_ip" ). val ()) {

                $ ( "#rank" ). text ( "#" + data. result [ 0 ]. rank );

                $ ( "#time_to_front" ). text ( Math . round (data. result [ 0 ]. rank   *   2  / 60 ) +   " hrs" );

             }

           

          });

        }

      }

      </ script >

    </ head >

    < body >

    < h1 >Flux Node Rank</ h1 >

    < p >< label >Node IP</ label > < input   type = "text"   id = "node_ip" > < button   onclick = "getNodeStats()" >Go</ button ></ p >

    < table   width = "300" >

      < tr >

        < td   width = "130" >Queue Position</ td > < td   id = "rank" ></ td >

      </ tr >

      < tr >

        < td >Time to Front</ td > < td   id = "time_to_front" ></ td >

      </ tr >

    </ table >

    </ body >

    </ html >

  15. Create a new file in the same folder called Dockerfile (no file extension, ensure uppercase D) and add the following:
  16. FROM nginx:alpine
    COPY . /usr/share/nginx/html
    
    *The purpose of this file is to instruct Docker what type of image to create. In this example we're installing an Nginx web server on the Alpine Linux distribution.

    Build Docker Image

    Now that we have the files we need (index.html and Dockerfile) we're going to copy them to the Ubuntu file system within Windows, ready to Dockerize them (add them to a Docker Image). The Docker Image is what we'll push to Flux.

  17. Click on START, type in the following, then click the result
  18. \\wsl$

  19. When Windows Explorer opens up, navigate to the following folder:
    • Ubuntu-20.4 (or whatever version was installed)
    • home
    • [username] (name specified during WSL install)

    Example:
    \\wsl.localhost\Ubuntu-20.04\home\username
  20. Go back to the original C:\noderank folder with the 2 files and copy/paste them to the folder above
  21. Example:
    \\wsl.localhost\Ubuntu-20.04\home\username\noderank
  22. Reopen the Ubuntu Terminal and type in the following chain of commands
  23. NOTE: If the expected output doesn't appear, close the Ubuntu Terminal, reopen and try again

    [email protected]:~$ dir
    noderank
    [email protected]:~$ cd noderank
    [email protected]:~/noderank$ sudo docker build -t noderank .
    

    When running the docker build command it may ask for the password that was created during WSL install

    If the docker build command was successful, something like this will appear:

    [email protected]:~/noderank$ sudo docker build -t noderank .
    [+] Building 2.4s (7/7) FINISHED
    => [internal] load build definition from Dockerfile
    => => transferring dockerfile: 92B
    => [2/2] COPY . /usr/share/nginx/html
    => exporting to image
    => => exporting layers
    => => writing image sha256:b69c071a02f4a066e98744cc7562447235ea
    => => naming to docker.io/library/noderank
    [email protected]:~/noderank$
    
  24. Now open Docker Desktop and click on IMAGES, then click RUN next to the newly created IMAGE
  25. Enter 80 for the PORT and click RUN
  26. The process is successful if the green running icon appears next to the randomly named CONTAINER. In this example: stoic_archimedes means there is a locally running web server.
  27. Open a browser and navigate to http://127.0.0.1/ The Node Rank app should be visible.
  28. Enter your Flux Node IP address (if you have one, if not, either purchase a 1,000 Flux Node, or use the sample Flux Node IP provided)
  29. This sample app queries the list of live Flux Nodes and shows the current position of the Flux Node using the IP address and calculates the estimated time to the front of the queue.

    Push to Docker Hub

    The next step is to push the Docker Image to the Docker Hub.

  30. Go back to Docker Desktop and click DELETE on the container, then click CONFIRM
  31. This does not delete the IMAGE, just the CONTAINER.

    Think of the CONTAINER as the VPS (Server); and think of the IMAGE as the operating system, software and files. In this example, Flux is the Container and the dApp is the Image.

  32. Now reopen the Ubuntu Terminal, make sure to be in the noderank directory, and type the following:
  33. sudo docker login

    Note: If it's not in the noderank directory, type in CD /home/username/noderank (replace username with the one you created during WSL install).

    You may be asked for your Ubuntu WSL password (otherwise known as the Root / Sudo Password); and you may be asked for your Docker username and password.

    Consider upgrading your password security by keeping your Docker password in a credentials store: https://docs.docker.com/engine/reference/commandline/login/#credentials-store

    Correct execution will yield the following:

    [email protected]:~/noderank$ sudo docker login
    [sudo] password for username:
    Login with your Docker ID to push and pull images from Docker Hub. If you don't have a Docker ID, head over to https://hub.docker.com to create one.
    Username: docker_user
    Password:
    
    Login Succeeded
    
    Logging in with your password grants your terminal complete access to your account.
    [email protected]:~/noderank$
    
  34. Now type the following… changing DOCKER_USER for the username created during registration of the Docker account
  35. sudo docker tag noderank docker_user/noderank:latest

    The newly tagged IMAGE in Docker Desktop should appear.

  36. Go back to the Ubuntu Terminal and type in:
  37. sudo docker push docker_user/noderank
    Expected outcome will show something like this:
    [email protected]:~/noderank$ sudo docker push docker_user/noderank
    Using default tag: latest
    The push refers to repository [docker.io/smartico/noderank]
    99524b48e93e: Pushed
    6fda88393b8b: Mounted from library/nginx
    a770f8eba3cb: Mounted from library/nginx
    318191938fd7: Mounted from library/nginx
    89f4d03665ce: Mounted from library/nginx
    67bae81de3dc: Mounted from library/nginx
    8d3ac3489996: Mounted from library/nginx
    latest: digest: sha256:1ce5bc6e3a003c0e63ba718807f543
    [email protected]:~/noderank$
    
  38. Head over to https://hub.docker.com/repositories and verify if it has been pushed.
  39. Make a note of the Docker Hub Repository (E.G: smartico/noderank) as it needs to be entered into the section Install Docker Image further down. This is where Flux will pull the dApp Image from

MacOS Guide

Prerequisites

  • MacOS (Big Sur on a MacBook Air was used for this Guide)
  • Stop / Disable any previously installed web servers on your system.
  • An account on https://hub.docker.com/ (Docker Username aka Docker ID)
  • A Terminal App, also known as a Shell
  • A Code Editor such as VS Code or TextEdit
  • Zelcore Wallet and Zelcore ID https://zelcore.io/
  • Supported Browser for ZelCore Wallet: Chrome / Edge / Brave

Install Docker

  1. Download and install Docker Desktop https://www.docker.com/products/docker-desktop
  2. Open Docker
  3. Sign in (top right) and create a Docker account, otherwise login instead
  4. Create a folder on your desktop called "noderank"

Create a Sample App

This guide demonstrates how to create a simple HTML/ JavaScript dApp:

  1. Open the App TextEdit, go to the Format menu and choose Make Plain Text and add the following code:
  2. < html >

    < head >

      < meta   name = "viewport"   content = "width=device-width, initial-scale=1" >

      < title >Node Rank</ title >

      < script   src = " https://code.jquery.com/jquery-3.6.0.min.js " ></ script >

      < script >

      function getNodeStats (){

        if ( $ ( "#node_ip" ). val ())

        {

          var settings = {

                    "cache" :   false ,

                    "dataType" :  "jsonp",

                    "async" :   true ,

                    "crossDomain" :   true ,

                    "url" :  " https://explorer.flux.zelcore.io/api/fluxnode/listfluxnodes/ " + $ ( "#node_ip" ). val () ,

                    "method" :  "GET",

                    "headers" :  {

                        "accept" :  "application/json",

                        "Access-Control-Allow-Origin" : "*"

              }

          }

          $ . ajax (settings). done ( function  (data) {

              if (data. result [ 0 ]. ip   ==   $ ( "#node_ip" ). val ()) {

                $ ( "#rank" ). text ( "#" + data. result [ 0 ]. rank );

                $ ( "#time_to_front" ). text ( Math . round (data. result [ 0 ]. rank   *   2  / 60 ) +   " hrs" );

             }

           

          });

        }

      }

      </ script >

    </ head >

    < body >

    < h1 >Flux Node Rank</ h1 >

    < p >< label >Node IP</ label > < input   type = "text"   id = "node_ip" > < button   onclick = "getNodeStats()" >Go</ button ></ p >

    < table   width = "300" >

      < tr >

        < td   width = "130" >Queue Position</ td > < td   id = "rank" ></ td >

      </ tr >

      < tr >

        < td >Time to Front</ td > < td   id = "time_to_front" ></ td >

      </ tr >

    </ table >

    </ body >

    </ html >

  3. Save that file as index.html in the folder you just created noderank.
  4. Create a new file in the same folder called Dockerfile (no file extension, ensure uppercase D) and add the following:
  5. FROM nginx:alpine
    COPY . /usr/share/nginx/html
    
    Note: The purpose of this file is to instruct Docker what type of image to create. In this example, it is installing an Nginx web server on the Alpine Linux distribution.

    Build Docker Image

    With the new files in place (index.html and Dockerfile) the next step is to Dockerize them (add them to a Docker Image). The Docker Image is what we'll push to Flux.

  6. Open the app Terminal and type in the following chain of commands:
  7. computer:~ username$ cd Desktop/noderank
    computer:noderank username$ sudo docker build -t noderank .
    
  8. When the docker build command is complete, it may ask for the system password
  9. If the docker build command was successful, output may look something like this:
  10. computer:noderank username$ sudo docker build -t noderank .
    [+] Building 2.4s (7/7) FINISHED
    => [internal] load build definition from Dockerfile
    => => transferring dockerfile: 92B
    => [2/2] COPY . /usr/share/nginx/html
    => exporting to image
    => => exporting layers
    => => writing image sha256:b69c071a02f4a066e98744cc7562447235ea
    => => naming to docker.io/library/noderank
    computer:noderank username$
    
  11. Now open Docker Desktop and click on IMAGES, then click RUN next to the newly created IMAGE
  12. Enter 80 for the PORT and click RUN
  13. The green running icon next to the randomly named CONTAINER indicates the successful execution of this step.. In this example stoic_archimedes means there is a locally running web server
  14. Open the browser and navigate to http://127.0.0.1/ The Node Rank app should appear
  15. Enter the Flux Node IP address (if not, either purchase a 1,000 Flux Node, or use the sample Flux Node IP provided)
  16. This sample app queries the list of live Flux Nodes and shows the current position of the Flux Node using the IP address and calculates the estimated time to the front of the queue

    Push to Docker Hub

    The Docker Image is now ready to be pushed to Docker Hub:

  17. Go back to Docker Desktop and click DELETE on the container, then click CONFIRM
  18. Note: This does not delete the IMAGE, just the CONTAINER. Think of the CONTAINER as the VPS (Server); and think of the IMAGE as the operating system, software and files. In this case, Flux is the Container and the dApp is the Image.

  19. Now reopen the Terminal, make sure to be in the noderank directory, and type the following:
  20. sudo docker login

    Note: If not in the noderank directory, type CD /users/username/desktop/noderank (replace username with your mac login username).

    The Mac login password may be requested here; as might the Docker Hub username and password.

    Consider upgrading the password security by keeping the Docker password in a credentials store: https://docs.docker.com/engine/reference/commandline/login/#credentials-store

    If this step has worked this message will appear

    computer:noderank username$ sudo docker login
    [sudo] password for username:
    Login with your Docker ID to push and pull images from Docker Hub. If you don't have a Docker ID, head over to https://hub.docker.com to create one.
    Username: docker_user
    Password:
    
    Login Succeeded
    
    Logging in with your password grants your terminal complete access to your account.
    computer:noderank username$
    
  21. Now type the following... changing DOCKER_USER for the username you created when Docker account was registered
  22. sudo docker tag noderank docker_user/noderank:latest
    The newly tagged IMAGE in Docker Desktop will appear

  23. Go back to the Terminal and type in:
  24. sudo docker push docker_user/noderank

    Successful execution of step 4 will return this:

    computer:noderank username$ sudo docker push docker_user/noderank
    Using default tag: latest
    The push refers to repository [docker.io/smartico/noderank]
    99524b48e93e: Pushed
    6fda88393b8b: Mounted from library/nginx
    a770f8eba3cb: Mounted from library/nginx
    318191938fd7: Mounted from library/nginx
    89f4d03665ce: Mounted from library/nginx
    67bae81de3dc: Mounted from library/nginx
    8d3ac3489996: Mounted from library/nginx
    latest: digest: sha256:1ce5bc6e3a003c0e63ba718807f543
    computer:noderank username$
    
  25. Go to https://hub.docker.com/repositories and verify if it's been pushed.
  26. Make a note of the Docker Hub Repository (E.G: smartico/noderank) as it will be needed in the section Install Docker Image below ... This is where Flux will pull the dApp Image from.

Register Flux App

IMPORTANT PREREQUISITE

Before you can register an App, you are required to submit it for approval to be whitelisted.

Please submit a request on https://discord.io/runonflux in the #deploy_dapp_runonflux_info channel

After it's been whitelisted please continue to register...

  1. In the browser (Chrome / Edge / Brave), go to the Dapp Register page.
  2. Complete the 5 steps using the table below as a guide
  3. Step 1

    App Name

    Name of your dApp which will form part of the URL
    E.G:
    https://noderank.app.runonflux.io  

    App Desc.

    Description that will appear in the Global Apps List.

    Owner

    Your Zel ID
    To find the Zel ID, open the Zelcore Wallet, go to Apps, then Zel ID

    Step 2

    A component is essentially a single Docker Image. Therefore it is possible to have multiple components in the same App and have them talk to each other through their component name.

    Repository

    Docker Hub Image Namespace
    E.G: docker_username/app_name:latest

    Environment

    Environment Variables: a place to store your sensitive data (mysql password) so that they’re not hardcoded in your app files.

    Run Command

    Array of strings of Commands
    E.G:
    /bin/bash,-c,(./script.sh)

    Directory

    Data folder that is shared by application to App volume

    E.G: /tmp

    Step 3

    Public Port(s)

    Array of Ports on which application will be available

    Domain(s)

    Array of strings of Domains managed by Flux Domain Manager (FDM). Length must correspond to available ports. Use empty strings for no domains

    E.G: [“”]  or  [“noderank.com”]

    If you use a custom domain for the app, please create a DNS CNAME record at the domain host and point it to the Flux Domain (noderank.app.runonflux.io)

    Private Port(s)

    Container Ports - Array of ports which the container has
    E.G: [“80”]  or  [“80”,“8080”]

    Step 4

    Instances

    Number of Flux Nodes you want your app replicated on.

    The more instances selected, the more traffic your App can handle.

    It is recommended starting off with the minimum of three.

    Each Instance above three carries a cost depending on the hardware selected.

    CPU

    Processors:

    From 0.1 to 7  vCore

    Price: 0.06 FLUX // per 0.1 cpu core

    RAM

    Memory:

    From 100 to 28,000  MB

    Price: 0.02 FLUX // per 100mb

    SSD

    Storage:

    From 1 to 565  GB

    Price: 0.01 FLUX // per 1gb

    Step 5 - Final Steps

  4. Double check the specification is correct
  5. Click Validate Spec & Get Cost
  6. The monthly cost will appear in FLUX and USD
  7. If the cost is acceptable, click Accept Cost & Login
  8. This will trigger the Zelcore wallet to open; a popup confirmation box may appear Open Zelcore?
  9. In Zelcore, enter your Zelcore login credentials and click Sign and Send
    • Sometimes the secure connection between the Zelcore Wallet and Dapp Registration Page can timeout if no action was taken in a certain time frame; therefore after clicking Sign and Send in Zelcore, and the App Registration page still says Opening Zelcore; click the Opening Zelcore button again to repeat the process (But quicker this time ;)
  10. Next in the App Register page, click Get Zelcore Signature, it will open Zelcore Wallet again, and complete the Signature process
  11. Back at the App Registration page, the final step is to click Register Flux App
  12. If the registration was successful, a success message and a Open Zelcore to Pay button will show. clicking it will open the Zelcore Wallet one last time to complete the payment process
  13. It might take a short while for the Block to get mined before accessing the app

  14. Navigate here and find the App https://home.runonflux.io/apps/globalapps
  15. Click VISIT on your App to open and preview in a browser:
  16. Example: https://noderank.app.runonflux.io

    Note: Do not leave the Register Your App page open for too long with no activity, otherwise it will timeout and you may have to repeat the entire process again.

    Updating the App

    As the app is tested and evolves, changes will need to be pushed to the live Flux App. Here are the steps to push it from a local machine to the Flux Network.

  17. Push changes to Docker Hub as outlined in Step 16.b in the Windows Guide and Step 19.b in the MacOS Guide.
  18. Changes will be automatically pulled by Flux.
  19. Please allow up to a few hours for propagation.

Forcing through a soft deploy to one Node

If a few hours is too long to wait for the changes to propagate globally across the Flux network (I.E: https://noderank.app.runonflux.io ) follow these steps to soft redeploy to just one Node.

  1. Go to https://home.runonflux.io/apps/globalapps and click on your App
  2. Scroll down to LOCATIONS and copy the IP address of one of the Nodes
  3. Now open that IP in your browser appending the port 16126 to the end: http://75.119.149.237:16126/
  4. Log in to the Node using your Zel ID (if not already logged in)
  5. Click on APPS > LOCAL APPS > MY LOCAL APPS
  6. Then click MANAGE > CONTROL > SOFT REDEPLOY APP
  7. Now visit the app in that Node IP through port 33828: http://75.119.149.237:33828/

Add a Custom Domain

You can point a custom domain of your choice such as yourdapp.com to your Flux Dapp via a Flux Domain Name (FDN) - yourdapp.app.runonflux.io. It is recommended to use CloudFlare; and you only need to add a CNAME record.

If you did not add a custom domain during your initial dApp setup, adding it afterwards will incur a very small Flux charge, as your app change submission has to be sent to the Flux network to be mined and confirmed.

  1. Go to https://home.runonflux.io/apps/globalapps and click on your App
  2. Scroll down to LOCATIONS and copy the IP address of one of the Nodes
  3. Now open that IP in your browser appending the port 16126 to the end: http://75.119.149.237:16126/
  4. Log in to the Node using your Zel ID (if not already logged in)
  5. Click on APPS > LOCAL APPS > MY LOCAL APPS
  6. Then click MANAGE > UPDATE SPECIFICATIONS
  7. Under CONNECTIVITY and DOMAINS enter your custom domain inside array brackets
    • ["mydomain.com"] or ["myapp.mydomain.com"]
  8. Then click COMPUTE UPDATE MESSAGE and follow the instructions to SIGN and PAY via Zelcore

Cloudflare Config

That's it from the Flux side, now we need to configure your custom domain at your host and Cloudflare.

Note: In the example use case, CloudFlare's role is to act as a middleman between the domain name company (E.G: godaddy.com) and the Flux network, forwarding traffic to the Flux dApp.

 

  1. If you haven't already, create a free account at CloudFlare: https://cloudflare.com
  2. You'll be asked to 'Add a Site', so enter your domain name and CloudFlare will automatically pull your DNS settings from your current Host to CloudFlare. Double check all DNS entries have been pulled across.
  3. After you've added a site, you'll be issued nameservers by CloudFlare to change over at your Domain Name Registrar:
    • E.G: nick.ns.cloudflare.com and tina.ns.cloudflare.com
    • They replace your existing name servers: E.G: ns1.yourdomain.com
  4. Once the settings have taken effect, anywhere from a few minutes to a few hours, your custom domain name will be passed through CloudFlares system forwarding to your original host.
  5. The final step is to add a CNAME record for the Flux Domain Name to CloudFlare.
  6. Click on DNS, Add Record and complete the fields like this:
    • Type: CNAME
    • Name: Your App Name (yourapp.yourdomain.com) or if you want to use the root domain name enter just enter @
    • Target: Your Flux Domain Name
    • Proxy: Make sure this is checked

    CloudFlare should look something like this:

  7. In this example setup as shown in the Screenshot, the root domain is still being hosted on another third party server (E.G: godaddy.com), and just the subdomain is being forwarded to Flux.
    • yourdomain.com >> CloudFlare >> Godaddy (Wordpress Site)
    • yourapp.yourdomain.com >> CloudFlare >> Flux Dapp (yourdapp.app.runonflux.io)
Register & Deploy