Skip to content

Latest commit

 

History

History
414 lines (284 loc) · 12.7 KB

README.md

File metadata and controls

414 lines (284 loc) · 12.7 KB

Techtonica

This repo is for the Techtonica website, which is currently hosted on DreamHost.

Who

The audience of the website is made up of (potential) volunteers, sponsors, and program participants.

What

We need to effectively communicate that Techtonica and its participants are worth supporting and share details of the program for potential applicants and volunteers.

How

There should be a good understanding of how the program works with vetting, training, mentoring, and placements.

Detailed instructions on how to update the website

Getting Started

You need Python version 3.8.10 and pip version 23 in order to properly update dependencies and replicate the production server environment locally.

Using Python 3.8.10 and pip 23 helps ensure compatibility and consistency between your local development environment and the server environment. This minimizes potential issues during deployment by keeping dependencies in sync with the versions expected by the servers and eliminates discrepancies caused by different versions, ensuring that code runs the same way on every developer's machine.

Set Up Virtual Environment

It is recommended you use a virtual environment to keep dependencies required by different projects separate. Learn more about Python virtual environments.

Set up virtual environment with Python 3.8.10 and Pip 23 using pyenv and venv:

# Install pyenv using brew
brew install pyenv
# Use pyenv to install version python 3.8.10
pyenv install 3.8.10
# Set your python version to 3.8.10
pyenv local 3.8.10
# Create a virtual environment using venv
python -m venv venv
# Activate your new virtual environment
source venv/bin/activate

Note: if you are running into an error with running python -m venv venv you may need to instead use the full path to the python executable when creating your virual environment. An example is /Users/yourPCName/.pyenv/versions/3.8.10/bin/python -m venv venv

Install pip Version 23

Ensure you are running pip23 to match the version on the servers:

pip install --upgrade pip==23.0

Install and Upgrade pip-tools

python -m pip install -U pip-tools

Install Pre-Commit Hooks

This project uses various pre-commit hooks to ensure code quality and formatting consistency.

  1. Install pre-commit globally.
  2. Install the project pre-commit hooks:
pip install pre-commit
pre-commit install -f --install-hooks

Install Requirements

pip install -r dev.txt

Create Config.ini File

touch config.ini

And then copy and paste this code into your new file (note: For the actual values, please see Updating Techtonica's Website):

   [default]
   # Acceptable values are sandbox or production
   environment = sandbox
   dev_password = dev_password

   [production]
   square_application_id = production_application_id
   square_access_token = production_access_token
   square_location_id = production_location_id

   [sandbox]
   square_application_id = <sandbox app id>
   square_access_token = <sandbox access token>
   square_location_id = <sandbox location id>

   [slack]
   slack_webhook =  <slack webhook>

Running Locally

Each time you want to work on your code, you will need to activate your virtual environment and run the server locally. You do not need to do any of the setup instructions again (besides installing requirements, if those have changed).

If you prefer using Docker, see instructions.

Activate your virtual environment:

source venv/bin/activate

Install any requirements if they've changed:

pip install -r dev.txt

Start the application's server:

FLASK_DEBUG=1 FLASK_APP=main_site.py flask run

Browse to http://localhost:5000.

Using Docker to Run Locally

First Time Using Docker?

  1. Download Docker Desktop
  2. cd into the folder that holds your techtonica.org repo
  3. Run your app: docker-compose up

⚠️ When there are updates to requirements.txt or Dockerfile, you will have to rebuild the Docker image in order for those changes to take effect.

For Docker Pros

  • To run app: docker-compose up
  • To rebuild Docker image: docker build . -t techtonica/website --pull
  • To push latest image to Docker Hub: docker push techtonica/website

CSS / SCSS

Styling changes should be made to the Sass (.scss) files and then compiled to CSS using one of the following commands:

👷‍♀️ Install Sass using one of the following

Mac: brew install sass/sass/sass Windows: choco install sass

sass static/sass/style.scss static/css/style.css
sass --watch static/sass/style.scss static/css/style.css

Square Testing

There are features on the site that use Square for payments and will periodically need testing (especially if their libraries get updated). Currently this is only the "Post a Job" page.

Setup

  1. Secrets required for the Square payment API and Slack webhook are stored in a config.ini file in the root directory of our repository.
  2. This file is listed in our .gitignore file and will not be included when pushing or pulling updates.
  3. You will need to manually add it into your local repository to test these features locally, and will also need to manually add it into whatever Dreamhost server (testing, staging, or production) that you are using as well, if it’s not already there.
  4. BE CAREFUL ABOUT environment VALUE! If it’s set to production it will actually charge the cards you test with, so be sure to set it to sandbox when testing locally or on staging or testing.
  5. Please see the Updating Techtonica's Website doc to get the keys and secrets.

Running Locally

Run your server using the following command, it will bypass any HTTPS cert errors.

pip install pyopenssl
FLASK_DEBUG=1 FLASK_APP=main_site.py FLASK_RUN_CERT=adhoc flask run

When navigating to the site, if your browser pops up an HTTPS insecure warning, click "Advanced" and "Proceed to 127.0.0.1 (unsafe)" image

Navigate to one of the pages that uses Square, currently "Post a Job".

Follow the instructions on the page, and when instructed to enter a credit card number, use one of the following numbers found here.

Updating the Demographics Chart for the Apply Section

This is an example of the chart that can be found on the full-time-program.html page.

At the moment, we do not have styling in place that will enable us to have a coded, adequately sized piechart while still maintaining mobile responsiveness. Until that happens, here is how to update the piechart when numbers change.

  1. Start the server.
  2. Open the browser and navigate to the Apply page.
  3. Update the data section in static/js/piechart.js#L30.
  4. Uncomment out following in full-time-program.html.
  <!-- <div class="blue-background">
     <canvas id="myChart" width="700" height="350"></canvas>
  </div> -->
  1. Take a screenshot of the piechart on the rendered page.
  2. Add the screenshot to the static/img directory saved with YEAR-H#-Cohort-Demographics.jpg, ex. 2023-H1-Cohort-Demographics.jpg.
  3. Update full-time-program.html to point to the new image you just added. Update the alt text if necessary.
 <img
     src="{{ url_for('static', filename='img/2023-H1-Cohort-Demographics.jpg') }}"
     alt="2023 Cohort Demographics."
     class="full-width-img"
  />
  1. Re-comment the following.
  <!-- <div class="blue-background">
     <canvas id="myChart" width="700" height="350"></canvas>
  </div> -->
  1. Stop the server
  2. Commit your code and open a pull request

Updating Dependencies

This project uses pip-tools to manage dependencies. If there are dependencies only needed for local development, these go in dev.in/dev.txt. Otherwise they go in requirements.in/requirements.txt. If you need to add or remove a Python library dependency:

  1. Edit requirements.in or dev.in (referred to below as file_name.in)

  2. Generate the .txt file

    pip-compile -U <file_name.in>
pip install -r <file_name.txt>

Once the new library is used in the code base, you'll need to update the isort config to reflect third party library usage:

pre-commit run seed-isort-config -a --hook-stage manual

Deployment to DreamHost

Initial Setup

The below instructions are for setting up a new server in DreamHost.

  1. Follow the instructions in the Setting up and deploying Python Flask to Dreamhost blog post.

  2. Update package tools, while you're still operating in the virtual environment:

    pip install -U pip setuptools pip-tools

  3. Create a config.ini file in the root directory of the repo in whichever Dreamhost server if there isn't one already present, and populate it with the necessary keys.

    [default]
# Acceptable values are sandbox or production
environment = sandbox
dev_password = dev_password

[production]
square_application_id = production_application_id
square_access_token = production_access_token
square_location_id = production_location_id

[sandbox]
square_application_id = <sandbox app id>
square_access_token = <sandbox access token>
square_location_id = <sandbox location id>

[slack]
slack_webhook =  <slack webhook>

Deploy Feature Branch

The below instructions describe how to deploy your feature branch once it has been tested and your PR has been approved. Make sure your feature branch was branched off of develop.

  1. Push changes to feature branch

  2. Merge feature branch into develop

  3. Push develop to GitHub

  4. Delete feature branch

  5. Deploy develop to staging

  6. Merge develop into main

  7. Push main to GitHub

  8. Deploy main to techtonica.org

  9. Tag the date after deployment

Updating the Site

Important: Only ever Pull from the server! There are currently 3 main servers in use: "staging", "techtonica.org" and "testing".

  1. Log in via SSH using your SSH key.

  2. Change directory to the appropriate domain:

    cd techtonica.org

    or

    cd staging.techtonica.org

  3. Activate the virtual envrionment:

    . bin/activate

  4. Change to the source directory:

    cd techtonica

  5. Pull the latest code using

    git pull

  6. Update requirements:

    pip-sync

  7. "Restart" the server to showcase new changes

    # staging.techtonica.org
systemctl --user stop gunicorn_staging
systemctl --user enable gunicorn_staging
systemctl --user restart gunicorn_staging
systemctl --user status gunicorn_staging

# testing.techtonica.org
systemctl --user stop gunicorn_testing
systemctl --user enable gunicorn_testing
systemctl --user restart gunicorn_testing
systemctl --user status gunicorn_testing

# techtonica.org
systemctl --user stop gunicorn_techtonica
systemctl --user enable gunicorn_techtonica
systemctl --user restart gunicorn_techtonica
systemctl --user status gunicorn_techtonica

  8. Deactivate virtual environment and exit server:

    deactivate
    exit