Merge with main

Author: erikguntner

.github/ISSUE_TEMPLATE/engineering-handoff-issue.md

@@ -0,0 +1,46 @@
+---
+name: Design to Engineering Handoff Issue
+about: PMs use this template when a User Story is ready for Engineering. This will be a separate issue for Engineering to track their work.
+title: 'Engineering for #[add related user story issue number] [Related User Story Title]'
+labels: 'milestone: missing, points: missing, Role: missing, Complexity: Missing, Feature: Missing'
+assignees: ''
+
+---
+
+**UPDATE LABELS: Add the following labels to each new issue, and remove default labels. Then remove this section:**
+* Role
+* Feature
+* Points 
+* Complexity
+
+### Dependencies/Related Engineering issues
+
+#### Back End
+- 
+
+#### Front End
+- 
+
+#### Dev Ops
+- 
+
+### Overview
+This issue is for tracking engineering work related to #[add related user story issue number], which is [add short description of related user story]
+
+### Action Items
+- Assign and Prep
+  - [ ] Engineering Lead: Review User Story and Design and assign Engineer
+  - [ ] Engineer: Review User Story and Design
+  - [ ] Engineer: Work with PM and Design Lead to clarify any questions about the User Story
+  - [ ] Engineer/Engineering Lead: determine if work should be split into multiple issues, if so create those issues and link them in this issue. 
+- Draft and Review:
+   - [ ] [Add engineering action items here]
+   - [ ] Code is deployed, changes are visible in https://dev.homeunite.us/
+   - Let Product know that it is ready for review
+      - [ ] Engineer: Change Issue Status to "For Review/Feedback Needed"
+      - [ ] Engineer: Add Label "Ready for: Product"
+      - [ ] Engineer: Tag the PM (assignee) of the related User Story in a comment below and let them know that a draft is ready for review
+   - [ ] Product: Review https://dev.homeunite.us/ and compare against Acceptance Criteria
+   - [ ] Repeat above steps until all Acceptance Criteria in the User Story are accounted for
+
+### Resources/Instructions

.github/workflows/run-tests-v1.yml

@@ -1,4 +1,4 @@
-name: Run API and App Tests
+name: Run API and Frontend Tests
 on:
   pull_request:
     branches: [main]
@@ -11,56 +11,45 @@ jobs:
     defaults:
       run:
         shell: bash
-        working-directory: ./api
+        working-directory: ./backend
     steps:
       - uses: actions/checkout@main
         with:
           fetch-depth: 500
           fetch-tags: true
-      - name: Set up Python 3.10
-        uses: actions/setup-python@v4
+      - name: Install poetry
+        run: pipx install poetry
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
-          cache: "pip"
-      - name: Upgrade pip
-        run: python -m pip install --upgrade pip
-      - name: Install API dev Dependencies
-        run: |
-          pip install -r requirements-dev.txt
-      - name: Run development tests with mocking enabled, using tox
-        run: |
-          # Use tox because it is configured to test against the same package type being deployed
-          tox
-      - name: Run release tests with mocking disabled, using tox
-        env:
-          COGNITO_REGION: ${{ secrets.COGNITO_REGION }}
-          COGNITO_ACCESS_ID: ${{ secrets.COGNITO_ACCESS_ID }}
-          COGNITO_ACCESS_KEY: ${{ secrets.COGNITO_ACCESS_KEY }}
-        run: |
-          echo "COGNITO_REGION set"
-          tox -e releasetest
-  test-app:
+          python-version: "3.12"
+          cache: "poetry"
+      - name: Install API Dependencies
+        run: poetry install --with test
+      - name: Run tests
+        run: poetry run pytest
+  test-frontend:
     runs-on: ubuntu-latest
     defaults:
       run:
         shell: bash
-        working-directory: ./app
+        working-directory: ./frontend
     steps:
       - uses: actions/checkout@v4
       - name: Use Node.js 20
         uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: "npm"
-          cache-dependency-path: app/package-lock.json
+          cache-dependency-path: frontend/package-lock.json
       - name: Run npm CI
         run: npm ci
-      - name: Test app
+      - name: Test frontend
         run: npm run test -- --no-color --run
       - name: Run E2E tests
         uses: cypress-io/github-action@v5
         with:
           install: false
           start: npm run dev
-          working-directory: ./app
-          wait-on: "http://[::1]:4040/"
+          working-directory: ./frontend
+          wait-on: "http://localhost:4040/"

.incubator/app.Dockerfile

@@ -0,0 +1,84 @@
+ARG NODE_VERSION=20.18.0-bookworm
+ARG HUU_BASE_VERSION=1.1
+ARG HUU_ECR_REPOSITORY=035866691871.dkr.ecr.us-west-2.amazonaws.com/homeuniteus
+
+# use the official Node image for building the UI bundle
+FROM node:${NODE_VERSION} AS client-builder
+
+
+# navigate to dir where client app source and build will live
+WORKDIR /app
+
+# copy the UI source code and configurations into our working dir
+COPY ./frontend ./
+
+ENV VITE_HUU_API_BASE_URL=https://qa.homeunite.us/api
+
+# install the NPM packages and generate the UI build
+RUN npm install && npm run build
+
+# use our custom base image with pre-installed Python
+#    note: if we adjust to work with a common stable
+#      version of Python (i.e. latest available package 
+#      for distro), then we should merge the base image
+#      dockerfile here and install directly
+FROM ${HUU_ECR_REPOSITORY}:base-${HUU_BASE_VERSION}
+
+# expose parameters for custom configuration of build SDK/runtime versions
+#    and build process configurations
+ARG POETRY_VERSION=1.8
+ARG HUU_TARGET_ENV=qa
+
+# navigate to dir where API sources and scripts will live
+WORKDIR /opt/huu
+
+# copy the API source into our working dir
+COPY ./backend ./
+
+# set some env vars to configure poetry behavior
+ENV POETRY_HOME=/opt/poetry
+ENV POETRY_NO_INTERACTION=1
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+# Tell Poetry where to place its cache and virtual environment
+ENV POETRY_CACHE_DIR=/opt/.cache
+
+# create a virtual env for the poetry workspace
+RUN python3 -m venv venv
+
+# install poetry using the virtual env's version of `pip`
+RUN ./venv/bin/pip install "poetry==${POETRY_VERSION}"
+
+# Install the dependencies and clear the cache afterwards.
+#   This may save some MBs.
+# RUN ./venv/bin/poetry install --no-root && rm -rf $POETRY_CACHE_DIR
+RUN ./venv/bin/poetry install
+
+# pull our UI build (generated in previous stage) into the conventional
+#   location for its nginx `server` block
+COPY --from=client-builder /app/dist /var/www/${HUU_TARGET_ENV}.homeunite.us/html/
+
+# overwrite the default nginx `server` block with ours - note that
+#   if we ever want to acutally deploy separate server blocks, this
+#   file should be deleted in favor of a conf file at:
+#     /etc/nginx/sites-available/${HUU_TARGET_ENV}.homeunite.us
+#   which should be symlinked to: `/etc/nginx/sites-enabled/`
+COPY ./.incubator/default.conf /etc/nginx/conf.d/default.conf
+
+# replace the template values for the environment - this corresponds
+#   to the subdomain of *.homeunite.us where this image will be deployed
+RUN sed -i "s/<HUU_ENVIRONMENT>/${HUU_TARGET_ENV}/g" /etc/nginx/conf.d/default.conf
+
+# add our entrypoint script, which will start the API process and fork 
+#   it into the background, then run the default entrypoint for nginx
+COPY ./.incubator/huu-entrypoint.sh ./
+
+# set the `x` flag to allow execution by the dockerd process
+RUN chmod +x /opt/huu/huu-entrypoint.sh
+
+# create the target directory for the nginx access and error logs
+RUN mkdir -p /var/log/${HUU_TARGET_ENV}.homeunite.us/
+
+# launch the application from our custom entrypoint script
+ENTRYPOINT [ "/opt/huu/huu-entrypoint.sh" ]

.incubator/base.Dockerfile

@@ -0,0 +1,37 @@
+ARG NGINX_VERSION=1.27.2
+
+FROM nginx:${NGINX_VERSION}
+
+ARG PYTHON_VERSION=3.12.5
+
+# use latest available system package listings and installations
+RUN apt-get update -y && apt-get upgrade -y
+
+# we need `curl` to download things, and `build-essential` to 
+#   install python and node from source
+RUN apt-get install -y \
+    curl \
+    build-essential \
+    libsqlite3-dev \
+    libpq-dev \
+    zlib1g-dev
+
+# keep dependency installation resources separate from source
+WORKDIR /opt
+
+# download and install python from source
+#   as of this writing, the latest package supported by apt is Python 3.9, and
+#   this is the simplest way to get Python 3.12+ installed
+
+# download and extract Python source
+RUN curl -LO https://www.python.org/ftp/python/${PYTHON_VERSION}/Python-${PYTHON_VERSION}.tgz \
+    && tar xzf Python-${PYTHON_VERSION}.tgz
+
+# navigate to root of Python source for installation
+WORKDIR /opt/Python-${PYTHON_VERSION}
+
+# build and install Python from source
+RUN ./configure --enable-loadable-sqlite-extensions \
+    && make \
+    && make install
+

.incubator/default.conf

@@ -0,0 +1,34 @@
+server {
+
+    listen 80;
+    listen [::]:80;
+
+    root /var/www/<HUU_ENVIRONMENT>.homeunite.us/html;
+    index index.html index.htm index.nginx-debian.html;
+
+    server_name <HUU_ENVIRONMENT>.homeunite.us www.<HUU_ENVIRONMENT>.homeunite.us localhost;
+
+    access_log /var/log/<HUU_ENVIRONMENT>.homeunite.us/nginx-access.log;
+    error_log /var/log/<HUU_ENVIRONMENT>.homeunite.us/nginx-error.log;
+
+    location / {
+        try_files $uri $uri/ /index.html =404;
+    }
+
+    location /img {
+        try_files $uri =404;
+    }
+
+    location /api/ {
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-NginX-Proxy true;
+        proxy_pass http://127.0.0.1:8000/api/;
+        proxy_ssl_session_reuse off;
+        proxy_set_header Host $http_host;
+        proxy_cache_bypass $http_upgrade;
+        proxy_redirect off;
+    }
+
+}

.incubator/huu-entrypoint.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+pushd /opt/huu
+    ./venv/bin/poetry run fastapi run app/main.py --port 8000 &
+popd
+
+/docker-entrypoint.sh nginx -g 'daemon off;'

README.md

@@ -14,28 +14,28 @@ This project is part of a larger initiative at Hack for LA around creating a sha
 
 ## Technology Overview
 
-The HomeUniteUs project is structured as a multi-[docker](https://docs.docker.com/) container application (for local development and testing), with secret-protected access to networked resources. The project contains three containers, whose activities are coordinated using the `docker compose` configuration outlined in `docker-compose.yml`. The three containers are:
-
-1. `app`: A frontend [React](https://reactjs.org/docs/getting-started.html) app developed using [TypeScript](https://www.typescriptlang.org/).
-   * We use [Redux](https://redux.js.org/) to manage client state, with the [Redux Toolkit](https://redux-toolkit.js.org/) to simplify development.
-   * We use the [Material UI](https://material-ui.com/) component library, for access to high quality UI components designed with accessibility in mind.
-   * We use the [Vite](https://vitejs.dev/) build tool, for fast dev builds and optimized production builds.
-2. `api`: A backend python [connexion](https://connexion.readthedocs.io/en/latest/) REST API, hosted on [AWS](https://docs.aws.amazon.com/).
-   * We use `connexion` to simplify our API specification and validation. `connexion` uses the [OpenAPI](https://www.openapis.org/) [specification](https://spec.openapis.org/oas/v3.0.1.html) to map API URLs to specific python functions. It will handle routing, validation, security, and parameter passing when an API request is made. `connexion` also generates documentation for our API, and provides a useful user interface (at `{URL}/api/ui`) that can be used to easily interact with the API for development purposes. We use the variant of `connexion` that runs on top of [Flask](https://flask.palletsprojects.com/en/1.1.x/).
-   * We use the [SQLAlchemy](https://www.sqlalchemy.org/) SQL toolkit and [Object-Relational Mapper (ORM)](https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping). This serves as a developer-friendly layer between the python app and the database.
-   * We use [gunicorn](https://gunicorn.org/) as our WSGI server. A WSGI server acts as a communication intermediary between an HTTP proxy and the Hone Unite Us API, handling client requests and passing them to the application, then returning the application's responses to the client.
-   * We use [nginx](https://nginx.org/en/docs/) as our HTTP server. This “reverse proxy” sits in front of the WSGI server, and handles a number of complex web server tasks. It is capable of load balancing across the WSGI server works, managing TLS connections, serving static files, and more.
+The HomeUniteUs project is structured as a multi-[docker](https://docs.docker.com/) container application, with secret-protected access to networked resources. The project contains five containers, whose activities are coordinated using the `docker compose` configuration outlined in `docker-compose.yml`. The five containers are:
+
+1. `frontend`: A frontend [React](https://reactjs.org/docs/getting-started.html) app developed using [TypeScript](https://www.typescriptlang.org/).
+   * It uses [Redux](https://redux.js.org/) to manage client state, with the [Redux Toolkit](https://redux-toolkit.js.org/) to simplify development.
+   * It uses the [Material UI](https://material-ui.com/) component library, for access to high quality UI components designed with accessibility in mind.
+   * It uses the [Vite](https://vitejs.dev/) build tool, for fast dev builds and optimized production builds.
+2. `backend`: A backend python API, hosted on [AWS](https://docs.aws.amazon.com/).
+   * It uses `FastAPI` as its web framework.
+   * It uses the [SQLAlchemy](https://www.sqlalchemy.org/) SQL toolkit and [Object-Relational Mapper (ORM)](https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping). This serves as a developer-friendly layer between the Python app and the database.
 3. `db`: A [PostgreSQL](https://www.postgresql.org/) database container.
    * The database is stored as a docker volume, `db-data`.
    * If the volume is not found during spin-up, then an empty database volume will be created.
-
-In the production environment, each of these services along with `nginx` are deployed onto an EC2 instance and managed as `systemd` service units instead of with Docker.
+4. `motoserver`: A development tool. It runs  [`moto`](http://docs.getmoto.org/en/latest/docs/server_mode.html) in Server Mode.
+   * It allows developers to mock AWS so that AWS secrets are not needed for local development. This tool is used because HUU uses AWS Cognito as its identity and access provider. However, most local development will not need to make actual calls to AWS Cognito for HUU feature development. Using this tool will allow developers to login to HUU on their development machine.
+   * It has a dashboard located at http://127.0.0.1:5000/moto-api/
+5. `pgadmin`: An optional development tool. It is a container running [pgAdmin4](https://www.pgadmin.org/). pgAdmin4 is database administration and development platform for PostgreSQL.
+    * This tool will allow can be used to run queries against the PostgreSQL server running in the `db` container.
+    * It is accessed by going to http://127.0.0.1:5050
 
 ## Build Instructions
 
-Before you can build the project, you will require a `.env` file containing access keys to the application third party services. Please message a team member on the [#home-unite-us slack channel](https://hackforla.slack.com/archives/CRWUG7X0C) once you've completed onboarding. See the [api](./api/README.md) and [app](./app/README.md) READMEs for more information about the required and optional environment variables.
-
-Since this project is dockerized, you can choose to either build the backend and frontend apps as docker containers or directly onto your local machine. This guide will focus on docker builds, but full local build and deployment instructions can be found in the [api](./api/README.md) and [app](./app/README.md) READMEs.
+Since this project is Dockerized, you can choose to either build the backend and frontend apps as Docker containers or directly onto your local machine. This guide will focus on Docker builds, but full local build and deployment instructions can be found in the [api](./backend/README.md) and [app](./frontend/README.md) READMEs.
 
 Also note that the code in this repo *should* build without issue on Linux, Windows, and MacOS. We do, however, utilize some Linux-only tools during deployment and primarily target the Linux platform.
 
@@ -45,16 +45,28 @@ Building with Docker is the simplest option, and debugging applications within t
 
 #### Requirements
 
-* A copy of the `.env` file described above
-* An up-to-date installation of [docker](https://docs.docker.com/get-docker/)
+* An up-to-date installation of [Docker](https://docs.docker.com/get-docker/)
 
 #### Instructions
 
-1. Place a copy of the `.env` file in the `app` directory
-2. Place a copy of the `.env` file in the `api` directory
-3. Build all three containers by running the `docker compose up` shell command from the root directory:
-4. Verify there are no build errors, and open `localhost:4040` in any browser, to see the application
+1. Build and run all containers by running the `docker compose up -d --build` shell command from the root directory:
+2. Verify there are no build errors. If there are build errors, reach out to the development team.
+3. Open `http://localhost:4040` in any browser to use Home Unite Us.
+
+* `pgAdmin4` is available at http://localhost:5050/browser/ to query the database.
+* `moto` server is available at http://localhost:5000/moto-api/ to view mocked AWS data.
+
+#### Test Users
+
+For local development, test users already exist when started using Docker.
+
+The password for all test users is `Test123!`.
+
+- 1 Admin: admin@email.com
+- 26 Guests: guest[a-z]@email.com (e.g. `guesta@email.com`, `guestb@email.com`, ... `guestz@email.com`)
+- 26 Coordinators: coordinator[a-z]@email.com (e.g. `coordinatora@email.com`, `coordinatorb@email.com`, ... `coordinatorz@email.com`)
+- 26 Hosts: host[a-z]@email.com (e.g. `hosta@email.com`, `hostb@email.com`, ... `hostz@email.com`)
 
 ## Testing Instructions
 
-Testing instructions for each application are in the [api](./api/README.md) and [app](./app/README.md) README files.
+Testing instructions for each application are in the [backend](./backend/README.md) and [frontend](./frontend/README.md) README files.

backend/.env.example

@@ -1,9 +1,10 @@
-COGNITO_CLIENT_ID=
-COGNITO_CLIENT_SECRET=
-COGNITO_REGION=
-COGNITO_REDIRECT_URI=http://localhost:34828/signin
-COGNITO_USER_POOL_ID=
-COGNITO_ACCESS_ID=
-COGNITO_ACCESS_KEY=
-ROOT_URL=http://localhost:34828
-DATABASE_URL=sqlite:///./homeuniteus.db
+COGNITO_CLIENT_ID=testing
+COGNITO_CLIENT_SECRET=testing
+COGNITO_REGION=us-east-1
+COGNITO_REDIRECT_URI=http://localhost:4040/signin
+COGNITO_USER_POOL_ID=testing
+COGNITO_ACCESS_ID=testing
+COGNITO_ACCESS_KEY=testing
+COGNITO_ENDPOINT_URL=http://127.0.0.1:5000
+ROOT_URL=http://localhost:4040
+DATABASE_URL=postgresql+psycopg2://postgres:postgres@127.0.0.1:5432/huu