Installation & Setup Guide ========================== Development Environment ----------------------- While developers have the flexibility to choose any Integrated Development Environment (IDE), this guide uses **Visual Studio Code** for consistency. Please follow the steps outlined below to install and set up your development environment. You can download and install Visual Studio Code from the following link: `Visual Studio Code Download `_. Environment Setup ----------------- `Node.js` is an open-source, cross-platform JavaScript runtime environment that developers use to build servers, web applications, command-line tools, and scripts. We require Node.js to execute all components currently under development. Alongside Node.js, we will also be using npm (Node.js package manager). Node.js Package Manager (npm) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ npm is the primary package manager utilized within the Node.js ecosystem. It simplifies the process of installing, updating, and managing dependencies for your Node.js projects. Project Structure ~~~~~~~~~~~~~~~~~ Each part of the project is structured as an individual code base, however, we merged everything in this repository, and we can clone it. Repository Links: - `Full code-base `_ Cloning the Repositories ~~~~~~~~~~~~~~~~~~~~~~~~ To clone the repositories to your local development environment, open your terminal or command-line interface and navigate to the directory where you want to clone the project. Then, use the following command: .. code-block:: bash $ git clone https://github.com/AlfredoMartins/blockchain-angola.git > Cloning into `Spoon-Knife`... > remote: Counting objects: 10, done. > remote: Compressing objects: 100% (8/8), done. > remote: Total 10 (delta 1), reused 10 (delta 1) > Unpacking objects: 100% (10/10), done. Set Environment Variables ------------------------- Encryption and Decryption Secrets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The encryption and decryption keys can be generated by running a script which can be found in the codebase under ``src/crypto/genKey.ts`` in the backend project. Once there, simply run the command, and you will see the keys in the console output and written to a ``secret.key`` file. .. code-block:: shell $ tsnd --respawn src/crypto/genKey.ts # Sample output [INFO] 11:34:24 ts-node-dev ver. 2.0.0 (using ts-node ver. 10.9.2, typescript ver. 5.4.3) Secret key has been written to 'secret.key' file. KEY: 252ea9d12942dff0014784390f781fbad6a37746af11600abbb276 IV: d50786ca0f68f489f538983262ff0a6f Whenever the command above is executed from the root project directory, new *key pairs* (````) are generated. Subsequently, developers must copy and paste them accordingly into the ``.env`` file. As shown, placeholder values are currently set as ``"..."``, which will eventually be replaced by actual values. JWT Keys Generation ~~~~~~~~~~~~~~~~~~~ This time, to generate a more secure and lengthy series of credentials for **JWT**, we utilize **OpenSSL**. `OpenSSL` is a software library used in applications to ensure secure communications over computer networks, preventing eavesdropping and verifying the identity of the communicating parties (``). JWT Keys Generation ------------------- To generate JWT keys, we'll use `OpenSSL`. Below are the installation steps and commands to generate the key. Installation ~~~~~~~~~~~~ Linux: .. code-block:: shell $ sudo apt-get update $ sudo apt-get install openssl Mac: .. code-block:: shell $ brew install openssl Key Generation ~~~~~~~~~~~~~~ .. code-block:: shell $ openssl genrsa -out secret.key 2048 $ cat secret.key # Sample output -----BEGIN PRIVATE KEY----- MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCtSgLQD33cxNYp av0Q6SQgjIdztH+/970mvgJtR3R/zX6Mc3ygmkIJOm8mkgUznPDpS94vTP/3LYlM q7HzNsOg/QvFhQ4F8xGlSmHDE+eAGfgj8tb++aDX+wVOfk3gkiZU+8H3jQLr9cMk Sh5FRlIBcX/LVIqnasY81AruCiE8MfM9yUiycx0zIrNswpMYXdIb5TthnQEkyPY6 rM00KfTLtfqlocJW8U8g/REpGDxR2LTDBc... -----END PRIVATE KEY----- Bear in mind that if this process fails, you can optionally use a key generated in the Encryption and Decryption part. Firebase Credentials / Storage Secrets -------------------------------------- We encourage developers to explore the `Google Firebase documentation `_ to learn how to obtain credentials. This helps avoid unnecessary lengthening of the documentation, as settings may change over time. Please refer to the complete procedure for Web and Mobile settings using the `following link ` (``_). It is worth noting that this link may become broken over time. Optionally, you can conduct research using Google archives. OpenAI Credentials ------------------ Similarly, please explore the link (``_) for OpenAI credentials. Assuming all the requirements mentioned previously are met, these variables must be set accordingly: .. code-block:: shell # BACKEND /.ENV: # Encryption and decryption credentials SECRET_KEY_VOTES=... SECRET_IV_VOTES=... SECRET_KEY_IDENTIFIER=... SECRET_IV_IDENTIFIER=... # JWT credentials ACCESS_TOKEN_SECRET=... REFRESH_TOKEN_SECRET=... # Mailer credentials MAILER_SERVICE=Gmail MAILER_HOST=smtp.gmail.com MAILER_PORT=465 MAILER_USER=... MAILER_PASS=... # MOBILE /.ENV: # Firebase credentials API_KEY=... AUTH_DOMAIN=election-blockchain.firebaseapp.com PROJECT_ID=election-blockchain STORAGE_BUCKET=election-blockchain.appspot.com MESSANGING_SENDER_ID=... APP_ID=... # FRONTEND /.ENV: # Firebase credentials API_KEY=... AUTH_DOMAIN=election-blockchain.firebaseapp.com PROJECT_ID=election-blockchain STORAGE_BUCKET=election-blockchain.appspot.com MESSANGING_SENDER_ID=... APP_ID=... # Open AI credentials ORGANIZATION=org-8DxV2NIjwStZ2eFMwq3HI2KP PROJECT_ID=proj_t2WJqJ4Mt5W3wrZAbaJxW4UI OPENAI_API_KEY=sk-proj-... In addition, it is important to mention that if any of the variables are not properly set up, the corresponding features may not work as expected. Run Development Environment --------------------------- Now that we are all set, we can finally up and run all the servers. We separate accordingly depending on the platform we wish to run. Backend ~~~~~~~ .. code-block:: shell $ tsnd --respawn src/network.ts 3010 Sample output: .. code-block:: shell SOCKET: listening on *: 3010 | NODE ADDRESS: 3010 Press "M" or "m" to open the menu. Mobile ~~~~~~ .. code-block:: bash $ npx expo start Sample output: .. code-block:: bash > Metro waiting on exp://192.168.0.38:8081 > Scan the QR code above with Expo Go (Android) or the Camera app (iOS) > QR Code > Using Expo Go ... > Press a │ open Android > Press i │ open iOS simulator > Press w │ open web ... > Press ? │ show all commands Logs for your project will appear below. Press Ctrl+C to exit. Web ~~~ .. code-block:: shell $ npm run dev Sample output: .. code-block:: shell > blockchain-web-frontend@0.0.0 dev > vite VITE v5.2.8 ready in 191 ms ➜ Local: http://localhost:3007/ ➜ Network: use --host to expose ➜ press h + enter to show help