Skip to content

1-InitialSetUp.md

Latest commit

 

History

History
285 lines (236 loc) · 13.3 KB

1-InitialSetUp.md

File metadata and controls

285 lines (236 loc) · 13.3 KB

Steps to Set Up EDAPT

Phase 1: Initial Set-Up

These initial steps will probably be performed in a local computer (as opposed to a remote server computer) so you can set-up, initialize, become familiar with EDAPT, and do any trouble-shooting or development necessary to get EDAPT working for the first time.


  1. Ensure you have node:

    NodeJS (aka Node.js, node, etc) is a back-end runtime environment for JavaScript/ECMAScript, with an associated shell command node. Note that with node installed, you will also have the npm (node package manager) npm utility at your command, which connects with an enormous registry of useful Node/JavaScript packages.

    In a command-line interface (also known as a CLI or (virtual) terminal) you can find out if you already have node installed. If the shell powering your terminal is bash or zsh, these instructions will work for you. You can confirm which shell you're using by executing the command echo $0 and see that bash or zsh is printed (with a dash in front if it's acting as a login shell).

    You can execute command -V node, and if the result shows a path location of "node", such as usr/bin/node, then you've already got it installed, otherwise it will tell you that node is "not found". The command node -v will show you the version. You might want to upgrade if your version is, say, below version 16 -- you should prefer to use the "Active LTS" (Long-Term Support) release of node, or a "Maintenance LTS" (which you can find here). (You can use command -V npm and npm -v too.)

    If you don't have node installed, you could just go to the node website and download from there, but you should probably consider other methods, including using a package manager. Here are two good options:

    • (Not preferred for EDAPT.)

      If you intend on just using node for a one-time implementation (without using globally-installed npm packages), you can follow instructions from NodeSource to just install one version of node+npm. If using GNU/Linux apt and NodeSource, you can follow step 1 in this tutorial.

    • (Preferred for EDAPT.)

      If you intend on using node on an on-going basis during JavaScript/Node development (or simply want to use a globally-installed npm package), it's best to follow the instructions from nvm (node version manager) to install nvm and node+npm. As the npm docs explain, installing node/npm with nvm "is the best way to avoid permissions issues". Also, with nvm you'll be able to quickly switch between versions of node, if you ever need to.

    Confirmation from Linuxize: "If you need Node.js only as a local runtime for deploying Node.js applications then the simplest option is to install Node.js from the NodeSource repository. Developers should prefer installing Node.js using the NVM script." This is further confirmed on stackoverflow (see the 2nd "2019 update" answer).

    Note that, if not using a package manager (such as apt for GNU/Linux or Homebrew for MacOS), you may have to take more steps if you want to keep your software up-to-date. For instance, you can use the same "curl" or "wget" command to update nvm as the one used to install it (if a newer file is referenced?). And you can install more versions of node+npm and switch between them; see nvm --help for more info. Note also that your globally-installed packages (seen with npm ls -g --depth 0) will change when switching between versions. (Also, for your information, if you're using MacOS with Homebrew, brew doctor will give a long warning about node, but that warning can just be ignored.)


  2. Ensure you have git:

    It is git, the "stupid content tracker", for file/project version control and downloading/uploading. You need git, but you're more likely to already have this installed by default. If using MacOS with Homebrew, you can use brew to install git.


  3. Pick and go to desired code location:

    In a terminal change directory to a location where you'd like to place the EDAPT code. Create any new folders/directories you'd like, if you want the EDAPT directory to be inside a new folder structure. Change directory to that final location where you'd like the EDAPT code to be placed.


  4. Download, install, and configure EDAPT:

    git clone https://github.com/oneforawe/edapt-data-handler.git edapt-data-handler (Download the code with git clone)
    cd edapt-data-handler (enter the repo)
    npm run install-all (install all the npm packages in the repo; this can take a little while; ignore warnings from npm)

    Configs:

    1. email-acct-info.js:
      cp email-handler/reference/email-acct-info-template.js email-handler/reference/email-acct-info.js (copy this file)
      Later, you can edit email-handler/reference/email-acct-info.js if you end up using a Gmail label to filter your data messages. You can follow the commented-out example of the label 'Biz Data', adding a line with your own label, and commenting out the labelsRequire line with an empty array. If you use a special Gmail account for development testing, you can note the username and address in this file, for reference, replacing the dummy example at the top of the file. (It would be best to store the password for this or any other accounts elsewhere in a more secure manner, especially the password for any business/production accounts.)

    2. dbConfig.js:
      cp database-api/config/dbConfig-template.js database-api/config/dbConfig.js (copy this file)
      Edit the file database-api/config/dbConfig.js so that the string "PICK-A-PASSWORD" contains your own chosen password. You will use this password when setting up a MySQL database with a user called "edapt". This config file will then allow the app to access the MySQL database with this username and password.

    3. users.js:
      cp web-app/server/app/config/users-template.js web-app/server/app/config/users.js (copy this file)
      Edit the file web-app/server/app/config/users.js to contain all the users that you'd like the app to allow. You can use the file add-user.js to create new users, following the instructions in that file. The users.js file should not contain any user passwords, so you can start by deleting the line with the password for 'theuser'. If you want to get rid of 'theuser' (and you probably should if you want a secure system), then delete the remaining three lines that declare that user and add your own user(s) with add-user.js. If you plan on just setting up a demo version of the app, you should leave 'theuser' as your user.

    4. auth.config.js:
      cp web-app/server/app/config/auth.config-template.js web-app/server/app/config/auth.config.js (copy this file)
      Edit the file web-app/server/app/config/auth.config.js to give your own secret string for jwt (jsonwebtoken). You can simply add more characters to the string that's already there.

  5. Ensure you have mysql:

    The MySQL (Community) Server runs as a background process and can be interacted-with via a client shell (via the command mysql) or via port calls (to port 3306) in JavaScript code (say, with Sequelize).

    You can execute command -V mysql, and if the result shows a path location of "mysql", such as usr/bin/mysql, then you've already got it installed. The command mysql -V will show you the version.

    On a Mac, if you plan on using Homebrew, you can follow the steps in this tutorial, plus Step 3 in this tutorial. For GNU/Linux, there are many potential methods you could use to install mysql, and the official steps for installing using apt seem a bit excessive, so I'd recommend using this simpler tutorial. (Instead of adding user 'sammy', you'll add user 'edapt', with the password you created in the previous step.) Briefly, the steps are:

    For MacOS (with Homebrew):
    brew install mysql
    mysql_secure_installation (see "NOTE" below)
    And play around with starting/stopping the daemon, starting/stopping the session server, and entering and exiting the mysql client shell.
    brew services (shows whether the daemon is running or not)
    mysql.server status (show session server status)

    For GNU/Linux (with apt):
    sudo apt update
    sudo apt install mysql-server
    sudo mysql_secure_installation (see "NOTE" below)
    systemctl status mysql (show status of daemon and session server)

    NOTE: Optionally set up the VALIDATE PASSWORD component -- might as well say yes -- create new password for mysql root user and store securely for reference; remove anonymous users; DO NOT disallow root login remotely; remove test database; reload privileges table now.

    For both:
    Enter mysql client:
    sudo mysql or mysql -u root -p
    Create special user and give access:
    mysql> CREATE USER edapt@localhost IDENTIFIED BY 'password'; (put your chosen password from database-api/config/dbConfig.js here)
    mysql> CREATE DATABASE edapt_db;
    mysql> GRANT ALL ON edapt_db.* TO edapt@localhost;

    See commands reference for more mysql commands and context with systemd/systemctl.


  6. Test the Database:

    You can do a quick initial test of the database by executing the command below. (If you check beforehand, you should see that there are no tables yet in the edapt_db database.)

    node database-api/test-runs/test-run-example.js
    You should see "Sequelize database connection: opened successfully.", a "report" with "Jane", and "Sequelize database connection: closed successfully.".

    And if you check in the edapt_db database, there should now be a table called "Users" with a record showing the same details as the "report" that was displayed by the command above.


  7. Test the demo web-app:

    First import the demo table:
    sudo mysql edapt_db < database-api/demo-files/edapt_db.Demo.sql
    You can check and see that a table named "Demo" is now in the database edapt_db.

    Then build the demo client-side code:
    npm run build-demo (This could take a little while.)
    (If the files in web-app/client/build/ do not change, then the demo build was already in place.)

    Then start the server:
    npm run serve-demo
    This command will not halt, but will settle when it displays "Server is running on port 8080." At that point you can open a web browser and enter the URI http://localhost:8080. The EDAPT web-app being locally-served (offline, not on the internet) by the server, and at that URI the Login page should appear. You can use any of your earlier-chosen username-password combinations to log in. From there you can explore the web-app.

    When you want to stop exploring the web-app and stop the server, you can go back to the terminal where it still shows "Server is running on port 8080." and press Control-C to kill the process. If you go back to the browser and refresh, the web-app should no longer be available.


If everything has worked so far, you should now be able to work on setting up the email-retrieval with the "email-handler" part of the app. If you don't intend on setting up the email portion, perhaps because you just want to serve the demo web-app, you can skip to Phase 3. Otherwise, on to Phase 2.