Merge pull request #36 from erland-syafiq/docs

Add more thorough documentation (including images)
erland-syafiq · Jun 12, 2024 · e69105f · e69105f
2 parents 65bfb07 + 46e04c1
commit e69105f
Show file tree

Hide file tree

Showing 9 changed files with 323 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,8 @@
 # VTMUNC Web Application
 
+![Home Page](/docs/assets/home-page.png "Home Page" )
+Figure 1: Home page of VTMUNC
+
 The VTMUNC web application serves as the online platform for the Virginia Tech Model United Nations Conference. It provides a centralized space for participants and delegates to register, access committee information, and discover the benefits of joining VTMUNC.
 
 ## Technologies Used
@@ -16,9 +19,20 @@ The VTMUNC web application serves as the online platform for the Virginia Tech M
 - **Committee Information**: Access detailed information about various committees and topics.
 - **Benefits Overview**: Learn about the advantages and opportunities available through VTMUNC participation.
 
+## Architecture
+
+![Architecture diagram](./docs/assets/aws-architecture-diagram.png "Architecture Diagram" )
+Figure 2: Architecture Diagram of VTMUNC web application
+
+The VTMUNC website is hosted on an Amazon EC2 instance, which serves as the core infrastructure for the web application. This EC2 instance also functions as a reverse proxy, efficiently managing incoming traffic to ensure smooth and secure operations. Additionally, the server interacts with AWS DynamoDB, providing scalable and rapid access to the database for handling data-related tasks. 
+
 ## Table Of Contents:
 
-- [🚀 Set Up](#set-up)
+- [🚀 Set Up](#-set-up)
+- [⚙️ Environment Variables File](docs/env-file.md)
+- [📂 Project Overview](docs/project-overview.md)
+- [📙 Site Overview](docs/site-overview.md)
+- [🎨 Style Guide](docs/style-guide.md)
 - [🌐 Deployment](docs/deployment.md)
 
 ## 🚀 Set Up
@@ -61,7 +75,7 @@ The VTMUNC web application serves as the online platform for the Virginia Tech M
    cp ../docs/assets/env.template .env
    ```
 
-   Open the `.env` file and fill in the necessary environment variables as per your project's requirements.
+   Open the `.env` file and fill in the necessary environment variables according to [these instructions](docs/env-file.md). 
 
 5. **Start the Development Server**
 

diff --git a/docs/assets/aws-architecture-diagram.png b/docs/assets/aws-architecture-diagram.png
diff --git a/docs/assets/design-language.jpg b/docs/assets/design-language.jpg
diff --git a/docs/assets/home-page.png b/docs/assets/home-page.png
diff --git a/docs/deployment.md b/docs/deployment.md
@@ -1,5 +1,8 @@
 # 🌐 Deployment Guide
 
+![Architecture diagram](./assets/aws-architecture-diagram.png "Architecture Diagram" )
+Figure 1: Architecture Diagram of VTMUNC web application
+
 ## Overview of VTMUNC Website Architecture
 The VTMUNC website is hosted on an Amazon EC2 instance, which serves as the core infrastructure for the web application. This EC2 instance also functions as a reverse proxy, efficiently managing incoming traffic to ensure smooth and secure operations. Additionally, the server interacts with AWS DynamoDB, providing scalable and rapid access to the database for handling data-related tasks.
 
@@ -17,11 +20,11 @@ The VTMUNC website is hosted on an Amazon EC2 instance, which serves as the core
     - **Key Pair**: Create a new key pair or select an existing key pair. This will be used for SSH access.
     - **Security Group**: Create a new security group with the following rules:
         * Inbound rules: 
-            - Allow SSH on port 22 from ony you and your collaborators ip addresses. 
+            - Allow SSH on port 22 from only you and your collaborators' ip addresses. 
             - Allow HTTP on port 80 from anywhere. 
             - Allow HTTPS on port 443 from anywhere.
         * Outbound rules: 
-            - Allow all traffic to a to anywhere
+            - Allow all traffic to anywhere
 
 3. **Launch the Instance**: Complete the instance launch process.
 
@@ -46,13 +49,19 @@ The VTMUNC website is hosted on an Amazon EC2 instance, which serves as the core
 
 ### Step 4: Configure GitHub Runner
 
-1. **Edit the GitHub Runner Configuration**:
+1. **Switch user to githubrunner**
+    - Once initial set up script has been run, login to user, githubrunner using the following command
+    ```bash
+    su - username -c "cd ~/actions-runner && exec bash"
+    ```bash
+
+2. **Edit the GitHub Runner Configuration**:
     - Navigate to your GitHub repository.
     - Go to `Settings` > `Actions` > `Runners` > `New self-hosted runner`
     - Select the option to configure a new self-hosted runner.
     - Most of the commands have already been done in the ec2-setup.sh script but you need to run the config script, which is unique to each repository. It should look like this: ./config.cmd --url https://github.com/Username/Repository --token <Token>
 
-2. **Run the GitHub Runner as a Systemd Daemon**:
+3. **Run the GitHub Runner as a Systemd Daemon**:
     - Once configured, execute the following command to run the setup script again, which will configure the GitHub runner to run as a systemd daemon:
 
       ```bash
@@ -65,9 +74,103 @@ The VTMUNC website is hosted on an Amazon EC2 instance, which serves as the core
     - Navigate to the DynamoDB service in the AWS Management Console.
     - Click on "Create table".
     - Set the table name to `vtmunc_applicants`.
-    - Define the primary key (e.g., `_id`) as per your application requirements.
+    - Define the primary key of type number, called `id`.
     - Click "Create" to create the table.
 
+### Step 6: Create a DockerHub Account and Repository
+
+1. **Create a DockerHub Account**:
+    - Go to the DockerHub website and sign up for a free account if you don't already have one.
+
+2. **Create a DockerHub Repository**:
+    - Once logged in, click on "Repositories" and then "Create Repository".
+    - Name your repository (e.g., `vtmunc`) and make it public or private as per your preference.
+    - Click "Create" to create the repository.
+
+### Step 7: Set Environment Variables in GitHub
+
+1. **Navigate to Your GitHub Repository Settings**:
+    - Go to your repository on GitHub.
+    - Click on `Settings` > `Secrets and variables` > `Actions` > `New repository secret`.
+
+2. **Add the Following Environment Variables**:
+    - **DOCKERHUB_USERNAME**: Your DockerHub username.
+    - **DOCKERHUB_PASSWORD**: Your DockerHub password.
+    - **ENV_FILE**: The content of your environment file. The instructions for filling this file are in [env-file docs](./env-file.md)
+
+    Instructions for adding a secret:
+    - Click `New repository secret`.
+    - Name the secret `DOCKERHUB_USERNAME`.
+    - Enter your DockerHub username as the value.
+    - Click `Add secret`.
+
+    Repeat the process for `DOCKERHUB_PASSWORD` and `ENV_FILE`.
+
+### Step 8: Add an A Record on Your DNS Registry
+
+1. **Navigate to Your DNS Provider**:
+    - Log in to your DNS provider (e.g., GoDaddy, Route 53).
+
+2. **Add an A Record**:
+    - Go to the DNS management section.
+    - Add a new A record with the following details:
+        - **Name**: Your domain name or subdomain (e.g., `www` or `api`).
+        - **Type**: A.
+        - **Value**: Your EC2 instance's public IP address.
+    - Save the record.
+
+### Step 9: Update `.github/workflows/vtmunc-runner.yml` (For Forked Repos)
+
+1. **Edit GitHub Actions Workflow**:
+    - If you have forked the repository, you need to update the `username` and `repo` fields in the `.github/workflows/vtmunc-runner.yml` file.
+
+    ```yaml
+    name: VTMUNC Runner
+
+    on: [push]
+
+    jobs:
+      build:
+        runs-on: self-hosted
+        steps:
+        - name: Checkout code
+          uses: actions/checkout@v2
+        - name: Set up Docker Buildx
+          uses: docker/setup-buildx-action@v1
+        - name: Log in to DockerHub
+          uses: docker/login-action@v1
+          with:
+            username: ${{ secrets.DOCKERHUB_USERNAME }}
+            password: ${{ secrets.DOCKERHUB_PASSWORD }}
+        - name: Build and push Docker image
+          run: |
+            docker build -t ${{ secrets.DOCKERHUB_USERNAME }}/your-repo-name:latest .
+            docker push ${{ secrets.DOCKERHUB_USERNAME }}/your-repo-name:latest
+    ```
+
+    Replace `your-repo-name` with your new repository name.
+
+### Step 10: Update the Caddy File
+
+1. **Edit the Caddy File**:
+    - Update the Caddy file on your EC2 instance to replace the URL with your new domain if you have moved away from `vtmunc.org`.
+
+    ```caddyfile
+    yourdomain.com {
+        reverse_proxy localhost:8080
+    }
+    ```
+
+    Replace `yourdomain.com` with your new domain name.
+
+2. **Restart Caddy**:
+    - After updating the Caddy file, restart the Caddy service to apply the changes:
+
+    ```bash
+    sudo systemctl restart caddy
+    ```
+
+
 ## Subsequent Deploys
 
 For subsequent deployments, simply push your changes to the `main` branch of your GitHub repository. The configured GitHub Actions workflow will automatically deploy the updates.
@@ -78,4 +181,4 @@ git commit -m "Your commit message"
 git push origin main
 ```
 
-That's it! Your deployment process is now automated, and your application will be deployed upon every push to the main branch.
+That's it! Your deployment process is now automated, and your application will be deployed upon every push to the main branch.
diff --git a/docs/env-file.md b/docs/env-file.md
@@ -0,0 +1,30 @@
+# ⚙️ Environment Variables File
+
+This file defines environment variables used by VTMUNC. Note, that this env file is seperate from the environment variables for GitHub, where you need to paste in this environment variable file as a variable called ENV_FILE. Find out more from the [deployment docs](./deployment.md#-step-7-set-environment-variables-in-github)
+
+## Important security notice
+Never, commit .env files to any remote repository, including GitHub. Only share this environment variable with trusted personell. 
+
+## Environment Variables in .env file
+| Variable Name | Description | Example Value |
+|---|---|---|
+| AWS_DYNAMODB_ACCESS_KEY_ID | Your AWS DynamoDB access key ID. Refer to "Obtaining AWS Credentials Securely" to obtain this value. | `JKSOKJSDO` (fake) |
+| AWS_DYNAMODB_SECRET_ACCESS_KEY | Your AWS DynamoDB secret access key. Refer to "Obtaining AWS Credentials Securely" to obtain this value.  | `sb0lasoiwkdouwedfes` (fake) |
+| AWS_DEFAULT_REGION | The default AWS region your application will use | `us-east1` |
+| BACKEND_URL | The URL of your backend API | `localhost:3000/api` |
+| USERNAME | The admin username | `randomemail@gmail.com` (fake) |
+| PASSWORD | The admin password | `randOMPassWordForMUN&283` (fake) |
+| JWT_SECRET | A secret key used for generating JSON Web Tokens (JWTs) for authentication. | `okmasfq;eiuidf` (fake) |
+
+## Obtaining AWS Credentials Securely
+
+1. Go to the AWS Management Console and navigate to the IAM service.
+2. In the IAM service, select "Users" from the navigation pane.
+3. Click on "Add user".
+4. Provide a name for the user and choose "Programmatic access" as the access type.
+5. Deselect "Attach existing policies directly" and click on "Next: Permissions".
+6. In the search bar, type "AdministratorAccess" and select the policy.
+7. Click on "Next: Review".
+8. Review the details of the user and click on "Create user".
+9. Download the credentials (access key ID and secret access key) for the newly created user.
+
diff --git a/docs/project-overview.md b/docs/project-overview.md
@@ -0,0 +1,58 @@
+# 📂 Project Overview
+
+## Directory Structure
+
+The project repository is organized into several directories, each serving a specific purpose. Below is an overview of the main directories and their contents:
+
+```
+.
+├── .git
+├── .github
+├── LICENSE
+├── README.md
+├── aws
+├── docs
+├── dotnet-archive
+├── reverse-proxy
+└── site
+```
+
+### 1. `.git`
+
+This directory contains the Git version control system files. It tracks changes in the project files and manages the history and collaboration features of Git.
+
+### 2. `.github`
+
+This directory holds GitHub-specific configuration files, including GitHub Actions workflows.. The workflows defined here automate tasks such as testing and deployment.
+
+### 3. `LICENSE`
+
+This file contains the license under which the project is distributed. It specifies the terms and conditions for using, copying, modifying, and distributing the software.
+
+### 4. `README.md`
+
+The README file provides an overview of the project, including instructions on how to set up, build, and run the application. It serves as the first point of reference for anyone interested in the project.
+
+### 5. `aws`
+
+This directory includes scripts and configuration files needed for setting up and managing the AWS infrastructure. Specifically, it contains the EC2 instance setup scripts used to initialize the server environment.
+
+### 6. `docs`
+
+The `docs` directory contains documentation related to the project. This can include design documents, user guides, developer notes, and other relevant documentation that aids in understanding and contributing to the project.
+
+### 7. `dotnet-archive`
+
+This directory holds the old version of the website, which was built using ASP.NET. It serves as an archive for the legacy codebase, allowing reference and potential reuse of previous implementations.
+
+### 8. `reverse-proxy`
+
+The `reverse-proxy` directory contains configuration files for the reverse proxy setup. This is used to manage incoming traffic and route it to the appropriate services, enhancing security and performance.
+
+### 9. `site`
+
+The `site` directory contains the code for the current version of the website, built using the NEXT.js framework. This includes all the components, pages, styles, and logic required for the web application.
+
+---
+
+By maintaining a well-organized directory structure, the project ensures clarity and ease of navigation for developers and contributors. Each directory has a clear purpose, facilitating efficient development and management of the project.