From 3b7d0362ba1a5f7670593c3557d2c06ff9b3f079 Mon Sep 17 00:00:00 2001 From: guaaaaa <63753679+guaaaaa@users.noreply.github.com> Date: Sun, 13 Apr 2025 11:24:20 -0400 Subject: [PATCH 1/3] Create sync-forks.yml --- .github/workflows/sync-forks.yml | 58 ++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 .github/workflows/sync-forks.yml diff --git a/.github/workflows/sync-forks.yml b/.github/workflows/sync-forks.yml new file mode 100644 index 000000000..5dd210015 --- /dev/null +++ b/.github/workflows/sync-forks.yml @@ -0,0 +1,58 @@ +name: Sync Template Changes to Forks + +on: + push: + branches: + - develop # Trigger only when develop branch is updated + +jobs: + sync-forks: + runs-on: ubuntu-latest + + steps: + - name: Checkout Template Repo + uses: actions/checkout@v3 + + - name: Set up Git identity + run: | + git config --global user.name "IEEEAutomationBot" + git config --global user.email "webmaster@ieee.utoronto.ca" + + - name: Install GitHub CLI + uses: cli/cli-action@v2 + + - name: Sync to Forked Repos + env: + GH_TOKEN: ${{ secrets.GH_PAT }} + run: | + TEMPLATE_REPO=https://github.com/ieeeuoft/hackathon-template.git + FORKS=( + "ieeeuoft/newhacks" + # Add other forked repos here, like: + # "ieeeuoft/hardware" + # "ieeeuoft/devday" + ) + + for FORK in "${FORKS[@]}"; do + REPO_NAME=$(basename $FORK) + BRANCH_NAME=sync-from-template-$(date +%s) + + echo "πŸ” Syncing to $REPO_NAME" + + git clone https://x-access-token:${GH_TOKEN}@github.com/${FORK}.git + cd $REPO_NAME + + git remote add upstream $TEMPLATE_REPO + git fetch upstream develop + git checkout -b $BRANCH_NAME + git merge upstream/develop --allow-unrelated-histories -m "πŸ”„ Auto-sync from hackathon-template (develop)" + git push origin $BRANCH_NAME + + gh pr create --repo $FORK \ + --title "πŸ”„ Sync from hackathon-template" \ + --body "Automated sync from the template repo (develop branch)" \ + --base develop \ + --head $BRANCH_NAME || echo "⚠️ PR may already exist or failed" + + cd .. + done From 26a76bf61c271b9ac31941c6087cfbf51764d9c5 Mon Sep 17 00:00:00 2001 From: Aaron Gu Date: Wed, 13 Aug 2025 21:08:23 -0400 Subject: [PATCH 2/3] Modify documentations, add new environment setup guild --- Onboard.md | 92 ++++++++ README.md | 544 ++++++++++++++++++++++----------------------- archive/old_doc.md | 436 ++++++++++++++++++++++++++++++++++++ environment.yml | 73 ++++++ 4 files changed, 863 insertions(+), 282 deletions(-) create mode 100644 Onboard.md create mode 100644 archive/old_doc.md create mode 100644 environment.yml diff --git a/Onboard.md b/Onboard.md new file mode 100644 index 000000000..855fd8656 --- /dev/null +++ b/Onboard.md @@ -0,0 +1,92 @@ +# IEEE Hackathon Website Template + +A customizable website template for hackathons run by [IEEE University of Toronto Student Branch](https://ieee.utoronto.ca/). + +## IEEE Web Team 2025-2026 + +#### Directors + +- Aaron Gu +- Ashwin Santhosh + +#### Advisors + +- Mustafa Abdulrahman +- Carmen Chau + +#### Associates + +- Wahib Barqawi +- Aidan Tran +- Warrick Tsui + +--- + +## Quick Start Guide + +### 1. Install Prerequisites + +- Python 3.9 +- [Docker](https://docs.docker.com/get-docker/) + [Docker Compose](https://docs.docker.com/compose/install/) +- Node.js v16 + +### 2. Setup Environment + +```bash +# Create and activate conda environment +conda env create -f environment.yml +conda activate ieee-template + +# Set required environment variables +conda env config vars set SECRET_KEY=123 +conda env config vars set DEBUG=1 +conda env config vars set REACT_APP_DEV_SERVER_URL=http://localhost:8000 + +# Reactivate environment +conda deactivate +conda activate ieee-template +``` + +### 3. Start Services + +```bash +# Launch database and cache +docker compose -f development/docker-compose.yml up -d + +# Apply database migrations +cd hackathon_site +python manage.py migrate +``` + +### 4. Build Assets + +```bash +# Compile SCSS to CSS +yarn install +yarn run scss + +# Watch for SCSS changes (optional) +yarn run scss-watch +``` + +### 5. Run Development Servers + +```bash +# Start Django server (main site) +python manage.py runserver + +# In separate terminal - Start Hardware Signout System (HSS) +conda activate ieee-template +cd hackathon_site/dashboard/frontend +nvm use 16 +yarn install +yarn run start +``` + +### 6. Access + +- Main site: http://localhost:8000 + +- HSS: http://localhost:3000 + +- Admin: http://localhost:8000/admin diff --git a/README.md b/README.md index 2d5112029..84bd5c2ab 100644 --- a/README.md +++ b/README.md @@ -1,380 +1,360 @@ # IEEE Hackathon Website Template -A website template for hackathons run by [IEEE University of Toronto Student Branch](https://ieee.utoronto.ca/). +A comprehensive, customizable website template for hackathons run by [IEEE University of Toronto Student Branch](https://ieee.utoronto.ca/). This template provides a complete solution for hackathon management, including registration, hardware sign-out systems, and administrative dashboards. + +## IEEE Web Team 2025-2026 -## IEEE Web Team 2023-2024 #### Directors -- Luke Cheseldine -- Mustafa Abdulrahman (PM) -#### Associates -- Karandeep Lubana -- Terry Luan -- Dalia Mahidashti +- Aaron Gu +- Ashwin Santhosh + +#### Advisors + +- Mustafa Abdulrahman - Carmen Chau -- Samuel Liu -- Daniel Qiu -- Ishika Mittal -- Kenny Cui -- Himanish Jindal -- Abubukker Chaudhary -- Natalie Chan - -## Contents -- [Requirements](#requirements) -- [Getting Started](#getting-started) - * [Python Environment](#python-environment) - * [Environment Variables](#environment-variables) - * [Running the development server](#running-the-development-server) - * [Creating users locally](#creating-users-locally) - * [Tests](#tests) -- [File Structure](#file-structure) -- [Using this Template](#using-this-template) - * [Forking](#forking) - * [From the Template (Recommended)](#from-the-template) - * [Copy the Repository](#copy-the-repository) + +#### Associates + +- Wahib Barqawi +- Aidan Tran +- Warrick Tsui + +## πŸš€ Quick Start + +For a streamlined setup experience, see our [Onboard.md](Onboard.md) for a quick start guide. + +## πŸ“‹ Table of Contents + +- [Features](#features) +- [Architecture](#architecture) +- [Prerequisites](#prerequisites) +- [Installation & Setup](#installation--setup) + - [Environment Setup](#environment-setup) + - [Database & Cache Services](#database--cache-services) + - [Running the Application](#running-the-application) +- [Development](#development) + - [Creating Users](#creating-users) + - [Testing](#testing) + - [Static Files & Styling](#static-files--styling) +- [Project Structure](#project-structure) +- [Using This Template](#using-this-template) + - [Forking](#forking) + - [From Template (Recommended)](#from-template-recommended) + - [Copy Repository](#copy-repository) - [Customization](#customization) - * [Branding and Styling](#branding-and-styling) + - [Event Configuration](#event-configuration) + - [Branding & Styling](#branding--styling) +- [Deployment](#deployment) +- [Contributing](#contributing) -## Requirements -- Python 3.8 or higher -- [Docker](https://docs.docker.com/get-docker/) -- [Docker Compose](https://docs.docker.com/compose/install/) +## ✨ Features -## Getting Started -### Python Environment -For local development, create a Python virtual environment. +- **Public Landing Page**: Customizable event landing page with registration +- **User Registration System**: Complete user management with email verification +- **Hardware Sign-Out System (HSS)**: React-based inventory management dashboard +- **Admin Dashboard**: Django admin interface for event management +- **Email Integration**: Automated email notifications and confirmations +- **File Upload System**: Secure handling of resumes and other documents +- **Team Management**: Support for team-based hackathons +- **Responsive Design**: Mobile-friendly interface using Material-UI +- **API Integration**: RESTful API for frontend-backend communication -#### Conda -We recommend you use [Anaconda](https://www.anaconda.com/products/individual) (or [Miniconda](https://docs.conda.io/en/latest/miniconda.html)), as it makes managing virtual environments with different Python versions easier: -```bash -$ conda create -n hackathon_site python=3.8 -``` +## πŸ—οΈ Architecture -This will create a new conda environment named `hackathon_site` (you may choose a different name). Then, activate the environment: -```bash -$ conda activate hackathon_site -``` +This project uses a modern full-stack architecture: -#### venv -Alternatively, you can use [venv](https://docs.python.org/3/library/venv.html) provided under the standard library, but note that you must already have Python 3.8 installed first: -```bash -$ python3.8 -m venv venv -``` +- **Backend**: Django 3.2 with Django REST Framework +- **Frontend**: React 16 with TypeScript and Material-UI +- **Database**: PostgreSQL 12.2 +- **Cache**: Redis 6 +- **Templating**: Jinja2 (instead of Django templates) +- **Styling**: SCSS with Materialize CSS framework +- **Containerization**: Docker & Docker Compose for development -How you activate the environment depends on your operating system, consult [the docs](https://docs.python.org/3/library/venv.html) for further information. +## πŸ“‹ Prerequisites -#### Installing Requirements -Install the requirements in `hackathon_site/requirements.txt`. This should be done regularly as new requirements are added, not just the first time you set up. -```bash -$ cd hackathon_site -$ pip install -r requirements.txt -``` +Before setting up the project, ensure you have the following installed: -### Environment Variables -In order to run the django and react development servers locally (or run tests), the following environment variables are used. Those in **bold** are required. - -| **Variable** | **Required value** | **Default** | **Description** | -|----------------|-----------------------------------|-------------------|-----------------------------------------------------------------------------------| -| **DEBUG** | 1 | 0 | Run Django in debug mode. Required to run locally. | -| **SECRET_KEY** | Something secret, create your own | None | Secret key for cryptographic signing. Must not be shared. Required. | -| DB_HOST | | 127.0.0.1 | Postgres database host. | -| DB_USER | | postgres | User on the postgres database. Must have permissions to create and modify tables. | -| DB_PASSWORD | | | Password for the postgres user. | -| DB_PORT | | 5432 | Port the postgres server is open on. | -| DB_NAME | | hackathon_site | Postgres database name. | -| REDIS_URI | | 172.17.0.1:6379/1 | Redis [URI](https://github.com/lettuce-io/lettuce-core/wiki/Redis-URI-and-connection-details#uri-syntax). `:/`. | -| **REACT_APP_DEV_SERVER_URL** | http://localhost:8000 | | Path to the django development server, used by React. Update the port if you aren't using the default 8000. | -| RECAPTCHA_PUBLIC_KEY | Something | A recaptcha public key that will skip the challenge | Key info: https://www.google.com/recaptcha/ | -| RECAPTCHA_PRIVATE_KEY | Something | A recaptcha private key that will skip the challenge | Key info: https://www.google.com/recaptcha/ | - -#### Testing -Specifying `SECRET_KEY` is still required to run tests, because the settings file expects it to be set. `DEBUG` is forced to `False` by Django. - -In the [GitHub action for Python tests](.github/workflows/pythonchecks.yml), `DEBUG` is set to be `1`. `SECRET_KEY` is taken from the `DJANGO_SECRET_KEY` repository secret. In order to run tests on a fork of this repo, you will need to [create this secret yourself](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets). - -### Running the development server -#### Database -Before the development server can be ran, the database must be running. This project is configured to use [PostgreSQL](https://www.postgresql.org/). - -You may install Postgres on your machine if you wish, but we recommend running it locally using docker. A docker-compose service is available in [development/docker-compose.yml](/home/graham/ieee/hackathon-template/README.md). To run all the services, including the database: -```bash -$ docker-compose -f development/docker-compose.yml up -d -``` +- **Python 3.9** (required - specified in environment.yml) +- **Docker** & **Docker Compose** - [Installation Guide](https://docs.docker.com/get-docker/) +- **Node.js v16** - Required for the React frontend +- **Conda** (recommended) or **Miniconda** - [Installation Guide](https://docs.conda.io/en/latest/miniconda.html) -To shut down the database and all other services: -```bash -$ docker-compose -f development/docker-compose.yml down -``` +## πŸ› οΈ Installation & Setup -To run only the database service: -```bash -$ docker-compose -f development/docker-compose.yml up -d postgres -``` +### Environment Setup -The postgres container uses a volume mounted to `development/.postgres-data/` for persistent data storage, so you can safely stop the service without losing any data in your local database. +1. **Clone the repository**: -A note about security: by default, the Postgres service is run with [trust authentication](https://www.postgresql.org/docs/current/auth-trust.html) for convenience, so no passwords are required even if they are set. You should not store any sensitive information in your local database, or broadcast your database host publicly with these settings. + ```bash + git clone + cd hackathon-template + ``` -#### Database migrations -[Migrations](https://docs.djangoproject.com/en/3.0/topics/migrations/) are Django's way of managing changes to the database structure. Before you run the development server, you should run any unapplied migrations; this should be done every time you pull an update to the codebase, not just the first time you set up: -```bash -$ cd hackathon_site -$ python manage.py migrate -``` +2. **Create and activate the conda environment**: -#### Cache -This application also relies on a cache, for which we use [Redis](https://redis.io/). + ```bash + conda env create -f environment.yml + conda activate ieee-template + ``` -You may install Redis on your machine if you wish, but we recommend running it locally using docker. A Redis service is available in [development/docker-compose.yml](/home/graham/ieee/hackathon-template/README.md). To run all the services, including the database: -```bash -$ docker-compose -f development/docker-compose.yml up -d -``` +3. **Set required environment variables**: -To run only the redis service: -```bash -$ docker-compose -f development/docker-compose.yml up -d redis -``` + ```bash + conda env config vars set SECRET_KEY=your-secret-key-here + conda env config vars set DEBUG=1 + conda env config vars set REACT_APP_DEV_SERVER_URL=http://localhost:8000 + ``` -If you run multiple instances of this application in production using Redis through Docker (perhaps in Swarm mode), you should make sure that the Redis databases used between applications do not conflict. The easiest way to do this is to change the database id in the [Redis URI environment variable](#environment-variables), eg to `172.17.0.1:6379/2`. +4. **Reactivate the environment**: + ```bash + conda deactivate + conda activate ieee-template + ``` -#### Run the development server -Finally, you can run the development server, by default on port 8000. From above, you should already be in the top-level `hackathon_site` directory: -```bash -$ python manage.py runserver -``` +### Database & Cache Services -If you would like to run on a port other than 8000, specify a port number after `runserver`. +The project uses PostgreSQL and Redis, which are managed via Docker: -### Creating users locally -In order to access most of the functionality of the site (the React dashboard or otherwise), you will need to have user accounts to test with. +1. **Start the services**: -To start, create an admin user. This will give you access to the admin site, and will bypass all Django permissions checks: + ```bash + docker compose -f development/docker-compose.yml up -d + ``` -```bash -$ python manage.py createsuperuser -``` +2. **Apply database migrations**: -Once a superuser is created (and the Django dev server is running), you can log in to the admin site at `http://localhost:8000/admin`. Note that creating a superuser does not give it a first or last name, so you should set those from the admin site otherwise some parts of the site may behave weird. Our regular sign up flow also assumes that username and email are the same, so we recommend creating your superuser accordingly. + ```bash + cd hackathon_site + python manage.py migrate + ``` -#### Adding additional users -The easiest way to add new users is via the admin site, through the "Users" link of the "Authentication and Authorization" panel. When adding a user, you will be prompted for only a username and a password. The react site uses email to log in, so *make sure* to click "Save and continue editing" and add a first name, last name, and email address. +3. **Stop services** (when needed): + ```bash + docker compose -f development/docker-compose.yml down + ``` -#### Giving a user a profile -Profiles are used by participants who have either been accepted or waitlisted. Some features of the React dashboard require the user to have a profile. This can be done through the "Profiles" link of the "Event" panel on the admin site. Click "Add profile", select a user from the dropdown, either add them to an existing team (if you have any) or click the green "+" to create a team, pick a status, fill out any other required fields, and click save. +**Note**: The PostgreSQL container uses trust authentication for development convenience. Never store sensitive data in the local development database. +### Running the Application -### Tests -#### Django -Django tests are run using [Django's test system](https://docs.djangoproject.com/en/3.0/topics/testing/overview/), based on the standard python `unittest` module. +1. **Compile SCSS assets**: -A custom settings settings module is available for testing, which tells Django to use an in-memory sqlite3 database instead of the postgresql database and to use an in-memory cache instead of Redis. To run the full test suite locally: + ```bash + yarn run scss + ``` -```bash -$ cd hackathon_site -$ python manage.py test --settings=hackathon_site.settings.ci -``` -##### Fixtures -Django has fixtures which are hardcoded files (YAML/JSON) that provide initial data for models. They are placed in a fixtures folder under each app. +2. **Start the Django development server** (main site): -More information at [this link](https://docs.djangoproject.com/en/3.0/howto/initial-data/). + ```bash + python manage.py runserver + ``` -To load fixtures into the database, use the command `python manage.py loaddata ` where `` is the name of the fixture file you’ve created. Each time you run loaddata, the data will be read from the fixture and re-loaded into the database. Note this means that if you change one of the rows created by a fixture and then run loaddata again, you’ll wipe out any changes you’ve made. +3. **Start the Hardware Sign-Out System** (in a separate terminal): + ```bash + conda activate ieee-template + cd hackathon_site/dashboard/frontend + nvm use 16 # If using nvm + yarn run start + ``` -#### React -React tests are handled by [Jest](https://jestjs.io/). To run the full suite of React tests: -```bash -$ cd hackathon_site/dashboard/frontend -$ yarn test -``` -## File Structure -The top level [hackathon_site](hackathon_site) folder contains the Django project that encapsulates this template. +4. **Access the applications**: + - Main site: http://localhost:8000 + - HSS Dashboard: http://localhost:3000 + - Admin interface: http://localhost:8000/admin -The main project configs are in [hackathon_site/hackathon_site](hackathon_site/hackathon_site), including the main settings file [settings/\_\_init__.py](hackathon_site/hackathon_site/settings/__init__.py) and top-level URL config. +## πŸ’» Development -The [dashboard](hackathon_site/dashboard) app contains the React project for the inventory management and hardware sign-out platform. +### Creating Users -The [event](hackathon_site/event) app contains the public-facing templates for the landing page. +1. **Create a superuser**: -The [registration](hackathon_site/registration) app contains models, forms, and templates for user registration, including signup and application templates. Since these templates are similar to the landing page, they may extend templates and use static files from the `event` app. + ```bash + python manage.py createsuperuser + ``` -### Templates and Static Files -Templates served from Django can be placed in any app. We use [Jinja 2](https://jinja.palletsprojects.com/en/2.11.x/) as our templating engine, instead of the default Django Template Language. Within each app, Jinja 2 templates must be placed in a folder called `jinja2//` (i.e., the full path will be `hackathon_site//jinja2//`). Templates can then be referenced in views as `/your_template.html`. +2. **Add additional users** via the admin interface at http://localhost:8000/admin -Static files are placed within each app, in a folder named `static//` (same convention as templates). For example, SCSS files for the Event app may be in `hackathon_site/event/static/event/styles/scss/`. They can then be referenced in templates as `/`, for example `event/styles/css/styles.css` (assuming the SCSS has been compiled to CSS). +3. **User profiles**: Create profiles for accepted/waitlisted participants through the admin interface -To compile the SCSS automatically when you save, run following task running while you work: +### Testing -```bash -$ cd hackathon_site -$ yarn run scss-watch -``` -To compile all SCSS files at once, run: +#### Django Tests ```bash -$ yarn run scss +cd hackathon_site +python manage.py test --settings=hackathon_site.settings.ci ``` -Django can serve static files automatically in development. In a production environment, static files must be collected: +#### React Tests ```bash -$ python manage.py collectstatic +cd hackathon_site/dashboard/frontend +yarn test ``` -This will place static files in `hackathon_site/static/`. These must be served separately, for example using Nginx, as Django cannot serve static files in production. [Read more about how Django handles static files](https://docs.djangoproject.com/en/3.0/howto/static-files/). +### Static Files & Styling -## Using this Template -This repository is setup as a template. To read more about how to use a template and what a template repository is, see [GitHub's doc page](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template). +#### SCSS Compilation -Before you begin, note that the [main workflow file](https://github.com/ieeeuoft/hackathon-template/blob/develop/.github/workflows/main.yml) uses the `pull_request_target` trigger. This means that pull requests from forks will run workflows in the base branch, **and will have access to repository secrets**. For the base template repo, this is not a security concern since the only secret used in tests is `DJANGO_SECRET_KEY`, and is meaningless in this repository. However, an instance of this repository will likely have other secrets set. **Unless you are absolutely sure that code run by workflows for pull requests, such as tests, does not have access to important secrets, you should change this trigger type back to `pull_request`**. This means that pull requests from forks (of your fork) will not run actions. Alternatively, if tests only need access to secret keys so they don't complain, use a different secret in the workflow files for running tests. +- **Compile once**: `yarn run scss` +- **Watch for changes**: `yarn run scss-watch` -### Forking -If you are interested in receiving updates to this template in your project, we recommend that you fork this repository into your own account or organization. This will give you the entire commit history of the project, and will allow you to make pull requests from this repository into your own to perform updates. +#### Static File Management -Unfortunately, GitHub does not allow you to fork your own repository. As a result, the forking option is not available to the owner account or organization. This means that IEEE UofT cannot use this template by forking it, and if you choose to fork your own generic copy of this template for instantiating, you will not be able to fork that fork. +- **Development**: Django serves static files automatically +- **Production**: Run `python manage.py collectstatic` to collect files -Note: `develop` is our default branch, but it should not be considered the most stable branch. If you want only the most stable releases, we recommend that you apply your customizations on top of the `master` branch. +## πŸ“ Project Structure -### From the Template -This is our recommended approach to instantiate this template, if forking is unavailable to you. In the end, this gives a similar result to [copying the repository](#copy-the-repository) (below), but maintains the "generated from ieeeuoft/hackathon-template" message on GitHub. If you don't care about that, then copying is simpler. +``` +hackathon-template/ +β”œβ”€β”€ hackathon_site/ # Main Django project +β”‚ β”œβ”€β”€ dashboard/ # React frontend app +β”‚ β”‚ └── frontend/ # React application +β”‚ β”œβ”€β”€ event/ # Public landing page templates +β”‚ β”œβ”€β”€ registration/ # User registration system +β”‚ β”œβ”€β”€ hardware/ # Hardware management models +β”‚ β”œβ”€β”€ review/ # Application review system +β”‚ └── hackathon_site/ # Project settings & config +β”œβ”€β”€ development/ # Development Docker setup +β”œβ”€β”€ deployment/ # Production deployment configs +└── environment.yml # Conda environment specification +``` -1. Create an instance of the template by clicking "Use this template". -![image](https://user-images.githubusercontent.com/26036279/90323566-e153a100-df30-11ea-82b5-11a5effb1fd7.png) +### Key Components - Note: By default, using a template creates a new repository based off only the default branch, which for this repository is `develop`. We recommend that you apply your customizations on top of the more stable `master` branch. To do so, make sure you check "Include all branches". +- **`dashboard/`**: React-based hardware sign-out system with Material-UI +- **`event/`**: Public-facing templates using Jinja2 and Materialize CSS +- **`registration/`**: User registration, application forms, and email templates +- **`hardware/`**: Database models for inventory management +- **`review/`**: Application review and decision management - Creating a repository from a template flattens all commits into a single initial commit. If you never plan on merging updates from the upstream template, you may proceed in customizing your instance from here and ignore all of the following steps. - -2. Clone your new instance locally via the method of your choosing. +## πŸ”§ Using This Template -3. In order to pull history and updates, you will need to add the original template as a remote on the git repository. Note that this only happens on your cloned instance, changing remotes has no effect on the repository you created on GitHub. +This repository is configured as a GitHub template. Choose the method that best suits your needs: - ```bash - $ git remote add upstream git@github.com:ieeeuoft/hackathon-template.git - ``` +### Forking (Recommended for Updates) - If you do not have git configured to clone over SSH, you may use the HTTPS url instead: `https://github.com/ieeeuoft/hackathon-template.git` - -4. Merge in whichever branch you would like to base your customizations off from upstream right away to get the history. For the rest of this example, we assume you are using `master`. - - ```bash - $ git fetch upstream - $ git merge upstream/master master --allow-unrelated-histories - $ git push origin master - ``` -5. Use the repository as you see fit, by creating feature branches off of `master`. We recommend a [Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). +If you want to receive updates from the original template: -6. When you want to pull an update from the upstream template, we recommend merging it into a new branch so that you can review the changes, resolve any conflicts, and merge it into your base branch by a pull request for added visibility. +1. Fork this repository to your account/organization +2. Clone your fork locally +3. Add the original as upstream: + ```bash + git remote add upstream git@github.com:ieeeuoft/hackathon-template.git + ``` - ```bash - $ git checkout master - $ git checkout -b update-from-upstream-template - $ git fetch upstream - $ git merge upstream/master update-from-upstream-template - $ git push -u origin update-from-upstream-template - ``` - -7. Make a PR on your repo to merge `update-from-upstream-template` into your base branch. +**Note**: GitHub doesn't allow forking your own repository, so this option isn't available to the original owners. -### Copy the Repository -This approach is very similar to using the template, but you lose the "generated from ..." text. You gain the added benefit of keeping the entire commit history of the repository, and not having to deal with fetching it upfront. +### From Template (Recommended for New Projects) -1. Import a new repository at [https://github.com/new/import](https://github.com/new/import). Set the old repository's clone URL to `https://github.com/ieeeuoft/hackathon-template.git`. +1. Click "Use this template" on GitHub +2. Check "Include all branches" for complete history +3. Clone your new repository +4. Add upstream remote for future updates -2. Clone your new instance locally via the method of your choosing. +### Copy Repository -3. Add the original template as a remote on the git repository. +1. Use GitHub's import feature at https://github.com/new/import +2. Set source URL to: `https://github.com/ieeeuoft/hackathon-template.git` +3. Clone and add upstream remote - ```bash - $ git remote add upstream git@github.com:ieeeuoft/hackathon-template.git - ``` +## 🎨 Customization - If you do not have git configured to clone over SSH, you may use the HTTPS url instead: `https://github.com/ieeeuoft/hackathon-template.git` - -4. Use the repository as you see fit, by creating feature branches off of `master`. We recommend a [Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). +### Event Configuration -5. When you want to pull an update from the upstream template, we recommend merging it into a new branch so that you can review the changes, resolve any conflicts, and merge it into your base branch by a pull request for added visibility. +Key settings are located in `hackathon_site/hackathon_site/settings/__init__.py`: - ```bash - $ git checkout master - $ git checkout -b update-from-upstream-template - $ git fetch upstream - $ git merge upstream/master update-from-upstream-template - $ git push -u origin update-from-upstream-template - ``` - -6. Make a PR on your repo to merge `update-from-upstream-template` into your base branch. +```python +# Essential settings to customize +HACKATHON_NAME = "Your Hackathon Name" +DEFAULT_FROM_EMAIL = "your-email@domain.com" +CONTACT_EMAIL = "contact@domain.com" +REGISTRATION_OPEN_DATE = datetime(2024, 1, 1) +REGISTRATION_CLOSE_DATE = datetime(2024, 2, 1) +EVENT_START_DATE = datetime(2024, 3, 1) +EVENT_END_DATE = datetime(2024, 3, 3) +``` -## Customization -This project was designed to be generic and customizable. At minimum, you will want to update templates to include your event's name and logo, but you may customize them to whatever degree you wish. See [file structure](#file-structure) for more details about templates. +### Branding & Styling -Core event settings and constants, such as cutoff dates, are kept at the bottom of the [settings](hackathon_site/hackathon_site/settings/__init__.py) file. These settings can be imported and used in any view, form, or in general any other python file. See the [Django docs on settings](https://docs.djangoproject.com/en/3.1/topics/settings/#using-settings-in-python-code) to read more about how to use them. +#### Event App Styling -Some settings you will definitely want to change are: -- `HACKATHON_NAME` - The name of your hackathon, for use in templates -- `DEFAULT_FROM_EMAIL` - This can be used in templates, and it will also be used by [Django's email system](https://docs.djangoproject.com/en/3.1/topics/email/)) -- `CONTACT_EMAIL` - By default, the same as `DEFAULT_FROM_EMAIL`. The email users should contact you at, for use in templates -- `REGISTRATION_OPEN_DATE` - When registration opens -- `REGISTRATION_CLOSE_DATE` - When registration closes -- `EVENT_START_DATE` - When the event starts -- `EVENT_END_DATE` - When the event ends -- `MEDIA_ROOT` - The path on the server where user-uploaded files will end up, including resumes +- **Framework**: Materialize CSS +- **SCSS Files**: Located in `hackathon_site/event/static/event/styles/scss/` +- **Key Files**: + - `styles.scss`: Main stylesheet + - `_variables.scss`: Colors, fonts, and sizes + - `_mixins.scss`: Reusable SCSS mixins -You will also need to set the necessary settings for your email server, so that Django can send emails to users. [Read about those settings here](https://docs.djangoproject.com/en/3.1/topics/email/). +#### Dashboard App Styling -Near the top of the settings file, you must also set `ALLOWED_HOSTS` and `CORS_ORIGIN_REGEX_WHITELIST` for your domain. +- **Framework**: Material-UI (MUI) +- **Location**: `hackathon_site/dashboard/frontend/src/` -For convenience, some constants have been passed into the context of all Jinja templates by default, so they can be used right away. See the [Jinja2 config file](hackathon_site/hackathon_site/jinja2.py) for full details. +#### Customization Guidelines +- **Colors & Fonts**: Edit maps in `_variables.scss` +- **Responsive Design**: Use the `@mixin responsive` mixin +- **Flexbox Layouts**: Use the `@mixin flexPosition` mixin -### Branding and Styling -Both the Event App and Dashboard App are styled by seperate SCSS files found in their respective directories. -#### Event App -**Warning: Deleting items in `styles.css`, `_mixins.scss`, and `_variables.scss` will mess up styling throughout all template pages.** Please read the following carefully and make sure you know what you're doing when you're modifying the aforementioned files. +## πŸš€ Deployment -[Materialize](https://materializecss.com/) is the CSS framework that the Event App uses. Review their documentation to get a further understanding of how the template is styled. +### Recommended Stack -In order to determine the original source of a class, class names in kebab notation are from Materialize and class names in camel case are found in `styles.scss`. We recommend you follow this convention when adding your own classes. +- **WSGI Server**: Gunicorn (included in requirements.txt) +- **Reverse Proxy**: Nginx +- **Database**: PostgreSQL +- **Cache**: Redis -[SCSS mixins](https://sass-lang.com/documentation/at-rules/mixin) are stored in `_mixin.scss`. Currently, there are 2 mixin functions: `@mixin flexPosition` to be used if you want to style a class with CSS Flexbox and `@mixin responsive` to be used in place of Media Queries. If you are not familiar with mixins, example usages of both mixins are in `styles.scss`. +### Production Checklist -Color, font family, and font size variables are stored in `_variables.scss`. Edit the values in the map to customize for your hackathons branding. For further organization, the variables are stored into maps and called using [SCSS functions](https://sass-lang.com/documentation/at-rules/function). +1. Set `DEBUG = False` in settings +2. Configure `ALLOWED_HOSTS` and `CORS_ORIGIN_REGEX_WHITELIST` +3. Set up email server configuration +4. Configure `MEDIA_ROOT` for file uploads +5. Run `python manage.py collectstatic` +6. Set up proper SSL certificates -For example: -``` -$fonts: ( - body: "Nunito", - header: "Roboto", -); - -@function font($fonts-name) { - @return map-get($fonts, $fonts-name); //(name of map, key) -} -``` -Instead of calling... -``` -h1 { font-family: $header; } -``` -...you should get the `$header` variable through the `font` function: -``` -h1 { font-family: font(header); } -``` +### File Serving Strategy + +- **Public files**: Serve from `media/uploads/` via web server +- **Private files**: Serve through Django views with permission checks +- **Static files**: Serve from `static/` directory via web server + +## 🀝 Contributing + +We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. + +### Development Workflow + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Run tests: `python manage.py test` and `yarn test` +5. Submit a pull request + +### Code Style -## Deploying -This template may be deployed however you wish, we recommend you read [Django's documentation on deploying](https://docs.djangoproject.com/en/3.1/howto/deployment/). +- **Python**: Black formatter (included in environment) +- **JavaScript/TypeScript**: Prettier (configured in package.json) +- **SCSS**: Follow existing patterns in `_variables.scss` and `_mixins.scss` -[Gunicorn](https://gunicorn.org/) is included in `requirements.txt` already, and deploying through gunicorn with a reverse proxy such as [Nginx](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) is our recommended approach. The template is fully configured to be deployed under a subdirectory of your website through a reverse proxy, provided that the `SCRIPT_NAME` header is set. You may also set the path prefix explicitly in the settings file with [`FORCE_SCRIPT_NAME`](https://docs.djangoproject.com/en/2.2/ref/settings/#force-script-name). +## πŸ“š Additional Resources -### Serving static files -Static files are configured to be served under the `static/` path, and are expected to be in a folder called `static` in the django project root (adjacent to `manage.py`). In production, you should run `python manage.py collectstatic` to move all static files into the `static` folder, and configure your web server to serve them directly. Read more about [managing static files in Django in the docs](https://docs.djangoproject.com/en/3.1/howto/static-files/). +- [Django Documentation](https://docs.djangoproject.com/) +- [React Documentation](https://reactjs.org/docs/) +- [Material-UI Documentation](https://mui.com/) +- [Materialize CSS Documentation](https://materializecss.com/) +- [Docker Documentation](https://docs.docker.com/) -### Serving user uploaded files -User-uploaded files are handled differently in Django than static files. We recommend you read the pages on Django [file uploads](https://docs.djangoproject.com/en/3.1/topics/http/file-uploads/) and [the security of user-uploaded content](https://docs.djangoproject.com/en/3.1/topics/security/#user-uploaded-content-security) before proceeding. +## πŸ“„ License -This template is configured to expect user-uploaded content to be served at `media/`, per the `MEDIA_URL` setting (you are free to change this, for example to an off-domain URL). User-uploaded content will be put in the folder defined by `MEDIA_ROOT`, which defaults to `/var/www/media/` and should almost certainly be configured for your server. Whatever you set it to, make sure the folder exists and is accessible by Django. +This project is licensed under the terms specified in [LICENSE.md](LICENSE.md). -Some user-uploaded content, such as resumes, should not be served to the general public. Others, such as pictures of hardware, should be. Hence, we recommend the following: +--- -- Upload all public-facing files with the prefix `uploads/`, so that they end up at `media/uploads/`. Configure your web server to serve this folder, e.g. `/var/www/media/uploads/`, to `media/uploads/` under your domain. -- Upload all private files to another prefix, e.g. `resumes/`, so that they end up at e.g. `media/resumes/`. For any users that should be able to see these files (such as staff members in this case), have a view that validates the user's permission, then reads in the data from disk and returns it directly in the HTTP response. Keep in mind that there are performance downsides to this approach. +For quick setup instructions, see [Onboard.md](Onboard.md). diff --git a/archive/old_doc.md b/archive/old_doc.md new file mode 100644 index 000000000..e0aad2ebc --- /dev/null +++ b/archive/old_doc.md @@ -0,0 +1,436 @@ +# IEEE Hackathon Website Template + +A website template for hackathons run by [IEEE University of Toronto Student Branch](https://ieee.utoronto.ca/). + +## IEEE Web Team 2023-2024 + +#### Directors + +- Luke Cheseldine +- Mustafa Abdulrahman (PM) + +#### Associates + +- Karandeep Lubana +- Terry Luan +- Dalia Mahidashti +- Carmen Chau +- Samuel Liu +- Daniel Qiu +- Ishika Mittal +- Kenny Cui +- Himanish Jindal +- Abubukker Chaudhary +- Natalie Chan + +## Contents + +- [Requirements](#requirements) +- [Getting Started](#getting-started) + - [Python Environment](#python-environment) + - [Environment Variables](#environment-variables) + - [Running the development server](#running-the-development-server) + - [Creating users locally](#creating-users-locally) + - [Tests](#tests) +- [File Structure](#file-structure) +- [Using this Template](#using-this-template) + - [Forking](#forking) + - [From the Template (Recommended)](#from-the-template) + - [Copy the Repository](#copy-the-repository) +- [Customization](#customization) + - [Branding and Styling](#branding-and-styling) + +## Requirements + +- Python 3.8 or higher +- [Docker](https://docs.docker.com/get-docker/) +- [Docker Compose](https://docs.docker.com/compose/install/) + +## Getting Started + +### Python Environment + +For local development, create a Python virtual environment. + +#### Conda + +We recommend you use [Anaconda](https://www.anaconda.com/products/individual) (or [Miniconda](https://docs.conda.io/en/latest/miniconda.html)), as it makes managing virtual environments with different Python versions easier: + +```bash +$ conda create -n hackathon_site python=3.8 +``` + +This will create a new conda environment named `hackathon_site` (you may choose a different name). Then, activate the environment: + +```bash +$ conda activate hackathon_site +``` + +#### venv + +Alternatively, you can use [venv](https://docs.python.org/3/library/venv.html) provided under the standard library, but note that you must already have Python 3.8 installed first: + +```bash +$ python3.8 -m venv venv +``` + +How you activate the environment depends on your operating system, consult [the docs](https://docs.python.org/3/library/venv.html) for further information. + +#### Installing Requirements + +Install the requirements in `hackathon_site/requirements.txt`. This should be done regularly as new requirements are added, not just the first time you set up. + +```bash +$ cd hackathon_site +$ pip install -r requirements.txt +``` + +### Environment Variables + +In order to run the django and react development servers locally (or run tests), the following environment variables are used. Those in **bold** are required. + +| **Variable** | **Required value** | **Default** | **Description** | +| ---------------------------- | --------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| **DEBUG** | 1 | 0 | Run Django in debug mode. Required to run locally. | +| **SECRET_KEY** | Something secret, create your own | None | Secret key for cryptographic signing. Must not be shared. Required. | +| DB_HOST | | 127.0.0.1 | Postgres database host. | +| DB_USER | | postgres | User on the postgres database. Must have permissions to create and modify tables. | +| DB_PASSWORD | | | Password for the postgres user. | +| DB_PORT | | 5432 | Port the postgres server is open on. | +| DB_NAME | | hackathon_site | Postgres database name. | +| REDIS_URI | | 172.17.0.1:6379/1 | Redis [URI](https://github.com/lettuce-io/lettuce-core/wiki/Redis-URI-and-connection-details#uri-syntax). `:/`. | +| **REACT_APP_DEV_SERVER_URL** | http://localhost:8000 | | Path to the django development server, used by React. Update the port if you aren't using the default 8000. | +| RECAPTCHA_PUBLIC_KEY | Something | A recaptcha public key that will skip the challenge | Key info: https://www.google.com/recaptcha/ | +| RECAPTCHA_PRIVATE_KEY | Something | A recaptcha private key that will skip the challenge | Key info: https://www.google.com/recaptcha/ | + +#### Testing + +Specifying `SECRET_KEY` is still required to run tests, because the settings file expects it to be set. `DEBUG` is forced to `False` by Django. + +In the [GitHub action for Python tests](.github/workflows/pythonchecks.yml), `DEBUG` is set to be `1`. `SECRET_KEY` is taken from the `DJANGO_SECRET_KEY` repository secret. In order to run tests on a fork of this repo, you will need to [create this secret yourself](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets). + +### Running the development server + +#### Database + +Before the development server can be ran, the database must be running. This project is configured to use [PostgreSQL](https://www.postgresql.org/). + +You may install Postgres on your machine if you wish, but we recommend running it locally using docker. A docker-compose service is available in [development/docker-compose.yml](/home/graham/ieee/hackathon-template/README.md). To run all the services, including the database: + +```bash +$ docker-compose -f development/docker-compose.yml up -d +``` + +To shut down the database and all other services: + +```bash +$ docker-compose -f development/docker-compose.yml down +``` + +To run only the database service: + +```bash +$ docker-compose -f development/docker-compose.yml up -d postgres +``` + +The postgres container uses a volume mounted to `development/.postgres-data/` for persistent data storage, so you can safely stop the service without losing any data in your local database. + +A note about security: by default, the Postgres service is run with [trust authentication](https://www.postgresql.org/docs/current/auth-trust.html) for convenience, so no passwords are required even if they are set. You should not store any sensitive information in your local database, or broadcast your database host publicly with these settings. + +#### Database migrations + +[Migrations](https://docs.djangoproject.com/en/3.0/topics/migrations/) are Django's way of managing changes to the database structure. Before you run the development server, you should run any unapplied migrations; this should be done every time you pull an update to the codebase, not just the first time you set up: + +```bash +$ cd hackathon_site +$ python manage.py migrate +``` + +#### Cache + +This application also relies on a cache, for which we use [Redis](https://redis.io/). + +You may install Redis on your machine if you wish, but we recommend running it locally using docker. A Redis service is available in [development/docker-compose.yml](/home/graham/ieee/hackathon-template/README.md). To run all the services, including the database: + +```bash +$ docker-compose -f development/docker-compose.yml up -d +``` + +To run only the redis service: + +```bash +$ docker-compose -f development/docker-compose.yml up -d redis +``` + +If you run multiple instances of this application in production using Redis through Docker (perhaps in Swarm mode), you should make sure that the Redis databases used between applications do not conflict. The easiest way to do this is to change the database id in the [Redis URI environment variable](#environment-variables), eg to `172.17.0.1:6379/2`. + +#### Run the development server + +Finally, you can run the development server, by default on port 8000. From above, you should already be in the top-level `hackathon_site` directory: + +```bash +$ python manage.py runserver +``` + +If you would like to run on a port other than 8000, specify a port number after `runserver`. + +### Creating users locally + +In order to access most of the functionality of the site (the React dashboard or otherwise), you will need to have user accounts to test with. + +To start, create an admin user. This will give you access to the admin site, and will bypass all Django permissions checks: + +```bash +$ python manage.py createsuperuser +``` + +Once a superuser is created (and the Django dev server is running), you can log in to the admin site at `http://localhost:8000/admin`. Note that creating a superuser does not give it a first or last name, so you should set those from the admin site otherwise some parts of the site may behave weird. Our regular sign up flow also assumes that username and email are the same, so we recommend creating your superuser accordingly. + +#### Adding additional users + +The easiest way to add new users is via the admin site, through the "Users" link of the "Authentication and Authorization" panel. When adding a user, you will be prompted for only a username and a password. The react site uses email to log in, so _make sure_ to click "Save and continue editing" and add a first name, last name, and email address. + +#### Giving a user a profile + +Profiles are used by participants who have either been accepted or waitlisted. Some features of the React dashboard require the user to have a profile. This can be done through the "Profiles" link of the "Event" panel on the admin site. Click "Add profile", select a user from the dropdown, either add them to an existing team (if you have any) or click the green "+" to create a team, pick a status, fill out any other required fields, and click save. + +### Tests + +#### Django + +Django tests are run using [Django's test system](https://docs.djangoproject.com/en/3.0/topics/testing/overview/), based on the standard python `unittest` module. + +A custom settings settings module is available for testing, which tells Django to use an in-memory sqlite3 database instead of the postgresql database and to use an in-memory cache instead of Redis. To run the full test suite locally: + +```bash +$ cd hackathon_site +$ python manage.py test --settings=hackathon_site.settings.ci +``` + +##### Fixtures + +Django has fixtures which are hardcoded files (YAML/JSON) that provide initial data for models. They are placed in a fixtures folder under each app. + +More information at [this link](https://docs.djangoproject.com/en/3.0/howto/initial-data/). + +To load fixtures into the database, use the command `python manage.py loaddata ` where `` is the name of the fixture file you’ve created. Each time you run loaddata, the data will be read from the fixture and re-loaded into the database. Note this means that if you change one of the rows created by a fixture and then run loaddata again, you’ll wipe out any changes you’ve made. + +#### React + +React tests are handled by [Jest](https://jestjs.io/). To run the full suite of React tests: + +```bash +$ cd hackathon_site/dashboard/frontend +$ yarn test +``` + +## File Structure + +The top level [hackathon_site](hackathon_site) folder contains the Django project that encapsulates this template. + +The main project configs are in [hackathon_site/hackathon_site](hackathon_site/hackathon_site), including the main settings file [settings/\_\_init\_\_.py](hackathon_site/hackathon_site/settings/__init__.py) and top-level URL config. + +The [dashboard](hackathon_site/dashboard) app contains the React project for the inventory management and hardware sign-out platform. + +The [event](hackathon_site/event) app contains the public-facing templates for the landing page. + +The [registration](hackathon_site/registration) app contains models, forms, and templates for user registration, including signup and application templates. Since these templates are similar to the landing page, they may extend templates and use static files from the `event` app. + +### Templates and Static Files + +Templates served from Django can be placed in any app. We use [Jinja 2](https://jinja.palletsprojects.com/en/2.11.x/) as our templating engine, instead of the default Django Template Language. Within each app, Jinja 2 templates must be placed in a folder called `jinja2//` (i.e., the full path will be `hackathon_site//jinja2//`). Templates can then be referenced in views as `/your_template.html`. + +Static files are placed within each app, in a folder named `static//` (same convention as templates). For example, SCSS files for the Event app may be in `hackathon_site/event/static/event/styles/scss/`. They can then be referenced in templates as `/`, for example `event/styles/css/styles.css` (assuming the SCSS has been compiled to CSS). + +To compile the SCSS automatically when you save, run following task running while you work: + +```bash +$ cd hackathon_site +$ yarn run scss-watch +``` + +To compile all SCSS files at once, run: + +```bash +$ yarn run scss +``` + +Django can serve static files automatically in development. In a production environment, static files must be collected: + +```bash +$ python manage.py collectstatic +``` + +This will place static files in `hackathon_site/static/`. These must be served separately, for example using Nginx, as Django cannot serve static files in production. [Read more about how Django handles static files](https://docs.djangoproject.com/en/3.0/howto/static-files/). + +## Using this Template + +This repository is setup as a template. To read more about how to use a template and what a template repository is, see [GitHub's doc page](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template). + +Before you begin, note that the [main workflow file](https://github.com/ieeeuoft/hackathon-template/blob/develop/.github/workflows/main.yml) uses the `pull_request_target` trigger. This means that pull requests from forks will run workflows in the base branch, **and will have access to repository secrets**. For the base template repo, this is not a security concern since the only secret used in tests is `DJANGO_SECRET_KEY`, and is meaningless in this repository. However, an instance of this repository will likely have other secrets set. **Unless you are absolutely sure that code run by workflows for pull requests, such as tests, does not have access to important secrets, you should change this trigger type back to `pull_request`**. This means that pull requests from forks (of your fork) will not run actions. Alternatively, if tests only need access to secret keys so they don't complain, use a different secret in the workflow files for running tests. + +### Forking + +If you are interested in receiving updates to this template in your project, we recommend that you fork this repository into your own account or organization. This will give you the entire commit history of the project, and will allow you to make pull requests from this repository into your own to perform updates. + +Unfortunately, GitHub does not allow you to fork your own repository. As a result, the forking option is not available to the owner account or organization. This means that IEEE UofT cannot use this template by forking it, and if you choose to fork your own generic copy of this template for instantiating, you will not be able to fork that fork. + +Note: `develop` is our default branch, but it should not be considered the most stable branch. If you want only the most stable releases, we recommend that you apply your customizations on top of the `master` branch. + +### From the Template + +This is our recommended approach to instantiate this template, if forking is unavailable to you. In the end, this gives a similar result to [copying the repository](#copy-the-repository) (below), but maintains the "generated from ieeeuoft/hackathon-template" message on GitHub. If you don't care about that, then copying is simpler. + +1. Create an instance of the template by clicking "Use this template". + ![image](https://user-images.githubusercontent.com/26036279/90323566-e153a100-df30-11ea-82b5-11a5effb1fd7.png) + + Note: By default, using a template creates a new repository based off only the default branch, which for this repository is `develop`. We recommend that you apply your customizations on top of the more stable `master` branch. To do so, make sure you check "Include all branches". + + Creating a repository from a template flattens all commits into a single initial commit. If you never plan on merging updates from the upstream template, you may proceed in customizing your instance from here and ignore all of the following steps. + +2. Clone your new instance locally via the method of your choosing. + +3. In order to pull history and updates, you will need to add the original template as a remote on the git repository. Note that this only happens on your cloned instance, changing remotes has no effect on the repository you created on GitHub. + + ```bash + $ git remote add upstream git@github.com:ieeeuoft/hackathon-template.git + ``` + + If you do not have git configured to clone over SSH, you may use the HTTPS url instead: `https://github.com/ieeeuoft/hackathon-template.git` + +4. Merge in whichever branch you would like to base your customizations off from upstream right away to get the history. For the rest of this example, we assume you are using `master`. + + ```bash + $ git fetch upstream + $ git merge upstream/master master --allow-unrelated-histories + $ git push origin master + ``` + +5. Use the repository as you see fit, by creating feature branches off of `master`. We recommend a [Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). + +6. When you want to pull an update from the upstream template, we recommend merging it into a new branch so that you can review the changes, resolve any conflicts, and merge it into your base branch by a pull request for added visibility. + + ```bash + $ git checkout master + $ git checkout -b update-from-upstream-template + $ git fetch upstream + $ git merge upstream/master update-from-upstream-template + $ git push -u origin update-from-upstream-template + ``` + +7. Make a PR on your repo to merge `update-from-upstream-template` into your base branch. + +### Copy the Repository + +This approach is very similar to using the template, but you lose the "generated from ..." text. You gain the added benefit of keeping the entire commit history of the repository, and not having to deal with fetching it upfront. + +1. Import a new repository at [https://github.com/new/import](https://github.com/new/import). Set the old repository's clone URL to `https://github.com/ieeeuoft/hackathon-template.git`. + +2. Clone your new instance locally via the method of your choosing. + +3. Add the original template as a remote on the git repository. + + ```bash + $ git remote add upstream git@github.com:ieeeuoft/hackathon-template.git + ``` + + If you do not have git configured to clone over SSH, you may use the HTTPS url instead: `https://github.com/ieeeuoft/hackathon-template.git` + +4. Use the repository as you see fit, by creating feature branches off of `master`. We recommend a [Gitflow workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow). + +5. When you want to pull an update from the upstream template, we recommend merging it into a new branch so that you can review the changes, resolve any conflicts, and merge it into your base branch by a pull request for added visibility. + + ```bash + $ git checkout master + $ git checkout -b update-from-upstream-template + $ git fetch upstream + $ git merge upstream/master update-from-upstream-template + $ git push -u origin update-from-upstream-template + ``` + +6. Make a PR on your repo to merge `update-from-upstream-template` into your base branch. + +## Customization + +This project was designed to be generic and customizable. At minimum, you will want to update templates to include your event's name and logo, but you may customize them to whatever degree you wish. See [file structure](#file-structure) for more details about templates. + +Core event settings and constants, such as cutoff dates, are kept at the bottom of the [settings](hackathon_site/hackathon_site/settings/__init__.py) file. These settings can be imported and used in any view, form, or in general any other python file. See the [Django docs on settings](https://docs.djangoproject.com/en/3.1/topics/settings/#using-settings-in-python-code) to read more about how to use them. + +Some settings you will definitely want to change are: + +- `HACKATHON_NAME` - The name of your hackathon, for use in templates +- `DEFAULT_FROM_EMAIL` - This can be used in templates, and it will also be used by [Django's email system](https://docs.djangoproject.com/en/3.1/topics/email/)) +- `CONTACT_EMAIL` - By default, the same as `DEFAULT_FROM_EMAIL`. The email users should contact you at, for use in templates +- `REGISTRATION_OPEN_DATE` - When registration opens +- `REGISTRATION_CLOSE_DATE` - When registration closes +- `EVENT_START_DATE` - When the event starts +- `EVENT_END_DATE` - When the event ends +- `MEDIA_ROOT` - The path on the server where user-uploaded files will end up, including resumes + +You will also need to set the necessary settings for your email server, so that Django can send emails to users. [Read about those settings here](https://docs.djangoproject.com/en/3.1/topics/email/). + +Near the top of the settings file, you must also set `ALLOWED_HOSTS` and `CORS_ORIGIN_REGEX_WHITELIST` for your domain. + +For convenience, some constants have been passed into the context of all Jinja templates by default, so they can be used right away. See the [Jinja2 config file](hackathon_site/hackathon_site/jinja2.py) for full details. + +### Branding and Styling + +Both the Event App and Dashboard App are styled by seperate SCSS files found in their respective directories. + +#### Event App + +**Warning: Deleting items in `styles.css`, `_mixins.scss`, and `_variables.scss` will mess up styling throughout all template pages.** Please read the following carefully and make sure you know what you're doing when you're modifying the aforementioned files. + +[Materialize](https://materializecss.com/) is the CSS framework that the Event App uses. Review their documentation to get a further understanding of how the template is styled. + +In order to determine the original source of a class, class names in kebab notation are from Materialize and class names in camel case are found in `styles.scss`. We recommend you follow this convention when adding your own classes. + +[SCSS mixins](https://sass-lang.com/documentation/at-rules/mixin) are stored in `_mixin.scss`. Currently, there are 2 mixin functions: `@mixin flexPosition` to be used if you want to style a class with CSS Flexbox and `@mixin responsive` to be used in place of Media Queries. If you are not familiar with mixins, example usages of both mixins are in `styles.scss`. + +Color, font family, and font size variables are stored in `_variables.scss`. Edit the values in the map to customize for your hackathons branding. For further organization, the variables are stored into maps and called using [SCSS functions](https://sass-lang.com/documentation/at-rules/function). + +For example: + +``` +$fonts: ( + body: "Nunito", + header: "Roboto", +); + +@function font($fonts-name) { + @return map-get($fonts, $fonts-name); //(name of map, key) +} +``` + +Instead of calling... + +``` +h1 { font-family: $header; } +``` + +...you should get the `$header` variable through the `font` function: + +``` +h1 { font-family: font(header); } +``` + +## Deploying + +This template may be deployed however you wish, we recommend you read [Django's documentation on deploying](https://docs.djangoproject.com/en/3.1/howto/deployment/). + +[Gunicorn](https://gunicorn.org/) is included in `requirements.txt` already, and deploying through gunicorn with a reverse proxy such as [Nginx](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) is our recommended approach. The template is fully configured to be deployed under a subdirectory of your website through a reverse proxy, provided that the `SCRIPT_NAME` header is set. You may also set the path prefix explicitly in the settings file with [`FORCE_SCRIPT_NAME`](https://docs.djangoproject.com/en/2.2/ref/settings/#force-script-name). + +### Serving static files + +Static files are configured to be served under the `static/` path, and are expected to be in a folder called `static` in the django project root (adjacent to `manage.py`). In production, you should run `python manage.py collectstatic` to move all static files into the `static` folder, and configure your web server to serve them directly. Read more about [managing static files in Django in the docs](https://docs.djangoproject.com/en/3.1/howto/static-files/). + +### Serving user uploaded files + +User-uploaded files are handled differently in Django than static files. We recommend you read the pages on Django [file uploads](https://docs.djangoproject.com/en/3.1/topics/http/file-uploads/) and [the security of user-uploaded content](https://docs.djangoproject.com/en/3.1/topics/security/#user-uploaded-content-security) before proceeding. + +This template is configured to expect user-uploaded content to be served at `media/`, per the `MEDIA_URL` setting (you are free to change this, for example to an off-domain URL). User-uploaded content will be put in the folder defined by `MEDIA_ROOT`, which defaults to `/var/www/media/` and should almost certainly be configured for your server. Whatever you set it to, make sure the folder exists and is accessible by Django. + +Some user-uploaded content, such as resumes, should not be served to the general public. Others, such as pictures of hardware, should be. Hence, we recommend the following: + +- Upload all public-facing files with the prefix `uploads/`, so that they end up at `media/uploads/`. Configure your web server to serve this folder, e.g. `/var/www/media/uploads/`, to `media/uploads/` under your domain. +- Upload all private files to another prefix, e.g. `resumes/`, so that they end up at e.g. `media/resumes/`. For any users that should be able to see these files (such as staff members in this case), have a view that validates the user's permission, then reads in the data from disk and returns it directly in the HTTP response. Keep in mind that there are performance downsides to this approach. diff --git a/environment.yml b/environment.yml new file mode 100644 index 000000000..6aac12202 --- /dev/null +++ b/environment.yml @@ -0,0 +1,73 @@ +name: ieee-template +channels: + - conda-forge + - defaults + +dependencies: + # Core language and C‑library deps + - python=3.9 + - libpq + - psycopg2 # pre‑built, with libpq + - pip # so we can install the rest via pip + + # All remaining packages come from PyPI + - pip: + - appdirs==1.4.3 + - asgiref==3.8.1 + - attrs==19.3.0 + - black==19.10b0 + - certifi==2020.4.5.1 + - chardet==3.0.4 + - click==7.1.2 + - confusable-homoglyphs==3.3.1 + - coreapi==2.3.3 + - coreschema==0.0.4 + - defusedxml==0.7.1 + - diff-match-patch==20241021 + - dj-rest-auth==1.0.6 + - Django==3.2.15 + - django-client-side-image-cropping==0.1.9 + - django-cors-headers==3.3.0 + - django-debug-toolbar==2.2.1 + - django-filter==2.4.0 + - django-import-export==2.5.0 + - django-recaptcha==2.0.6 + - django-redis==4.12.1 + - django-registration==3.1.2 + - djangorestframework==3.11.2 + - dotenv==0.9.9 + - drf-yasg==1.17.1 + - et_xmlfile==2.0.0 + - gunicorn==20.0.4 + - idna==2.9 + - inflection==0.5.0 + - itypes==1.2.0 + - Jinja2==2.11.3 + - MarkupSafe==1.1.1 + - odfpy==1.4.1 + - openpyxl==3.1.5 + - packaging==20.4 + - pathspec==0.8.0 + - Pillow==9.0.1 + - psycopg2-binary==2.9.10 # optional: you can remove this since conda’s psycopg2 is already installed + - pyparsing==2.4.7 + - python-dateutil==2.8.2 + - python-dotenv==1.1.0 + - pytz==2020.1 + - PyYAML==5.3 + - qrcode==7.3.1 + - redis==3.5.3 + - regex==2021.4.4 + - requests==2.25.1 + - ruamel.yaml==0.16.10 + - ruamel.yaml.clib==0.2.12 + - six==1.15.0 + - sqlparse==0.3.1 + - tablib==3.7.0 + - toml==0.10.0 + - typed_ast==1.4.1 + - typing_extensions==4.12.2 + - uritemplate==3.0.1 + - urllib3==1.26.5 + - xlrd==2.0.1 + - xlwt==1.3.0 From e3e0410fbaf314e65ba0cd6581efc8d16faae9b8 Mon Sep 17 00:00:00 2001 From: guaaaaa <63753679+guaaaaa@users.noreply.github.com> Date: Wed, 13 Aug 2025 21:12:00 -0400 Subject: [PATCH 3/3] Delete .github/workflows/sync-forks.yml --- .github/workflows/sync-forks.yml | 58 -------------------------------- 1 file changed, 58 deletions(-) delete mode 100644 .github/workflows/sync-forks.yml diff --git a/.github/workflows/sync-forks.yml b/.github/workflows/sync-forks.yml deleted file mode 100644 index 5dd210015..000000000 --- a/.github/workflows/sync-forks.yml +++ /dev/null @@ -1,58 +0,0 @@ -name: Sync Template Changes to Forks - -on: - push: - branches: - - develop # Trigger only when develop branch is updated - -jobs: - sync-forks: - runs-on: ubuntu-latest - - steps: - - name: Checkout Template Repo - uses: actions/checkout@v3 - - - name: Set up Git identity - run: | - git config --global user.name "IEEEAutomationBot" - git config --global user.email "webmaster@ieee.utoronto.ca" - - - name: Install GitHub CLI - uses: cli/cli-action@v2 - - - name: Sync to Forked Repos - env: - GH_TOKEN: ${{ secrets.GH_PAT }} - run: | - TEMPLATE_REPO=https://github.com/ieeeuoft/hackathon-template.git - FORKS=( - "ieeeuoft/newhacks" - # Add other forked repos here, like: - # "ieeeuoft/hardware" - # "ieeeuoft/devday" - ) - - for FORK in "${FORKS[@]}"; do - REPO_NAME=$(basename $FORK) - BRANCH_NAME=sync-from-template-$(date +%s) - - echo "πŸ” Syncing to $REPO_NAME" - - git clone https://x-access-token:${GH_TOKEN}@github.com/${FORK}.git - cd $REPO_NAME - - git remote add upstream $TEMPLATE_REPO - git fetch upstream develop - git checkout -b $BRANCH_NAME - git merge upstream/develop --allow-unrelated-histories -m "πŸ”„ Auto-sync from hackathon-template (develop)" - git push origin $BRANCH_NAME - - gh pr create --repo $FORK \ - --title "πŸ”„ Sync from hackathon-template" \ - --body "Automated sync from the template repo (develop branch)" \ - --base develop \ - --head $BRANCH_NAME || echo "⚠️ PR may already exist or failed" - - cd .. - done