# ColdFront: A Step-by-Step Guide

## Making sure your GitHub version control is set up
1. Fork the ColdFront repo
2. Clone the repo on your machine (`git clone https://github.com/YourUsername/coldfront`)
3. Change directories to the ColdFront folder (`cd coldfront`)
4. Add the remote repository to your git (`git remote add upstream https://github.com/ubccr/coldfront`)
5. Run `git remote -v` and ensure that the remote and origin repositories are correct
6. Run the following commands in order to make sure your branch is up-to-date

git checkout main
git fetch main
git merge upstream/main

(the above fetches and merges changes to CCR repo and brings them to your local computer)

git status 

(the above shows the difference, if any, between both repos)

git push origin main 

(the above pushes local changes to your GitHub repo)

EACH time you come back to working on ColdFront, run the following commands to make sure your main branch is up-to-date:

git checkout main
git pull 
git fetch upstream 
git merge upstream/main 
git push origin main

Create a new branch by running

git checkout -b new_branch_name

(if working on a specific issue, a simple naming convention for branches is `issue_number`-`issue_name`)

## Starting the ColdFront server on your machine
###### Note: Running the following in a new terminal tab/ window makes it so you have one tab/ window for Git, and one for running the server. This way, you do not have to close the server or open a new tab/ window to later run commands.
---
1. Install ColdFront on your machine using pip inside a virtual environment
###### Creating your virtual environment within the `coldfront` directory saves you from having to backtrack directories to check out your environment!

python3 -mvenv venv
source venv/bin/activate
pip install --upgrade pip
pip install -e .

(the `-e .` command is used to install all the necessary dependencies)

2. Initialize the ColdFront database

coldfront initial_setup

3. Create a super user account

coldfront createsuperuser

4. Load the test data

coldfront load_test_data

5. Run the server

DEBUG=True coldfront runserver

6. Open ColdFront's UI by pointing your browser to [the localhost page (localhost:8000)](https://localhost:8000)
7. Log in to ColdFront
* Log in as an admin with username **admin**
* Log in as a PI (principal investigator) with username **cgray**
* Log in as a center director using username **csimmons**
* Password for all above usernames is *test1234*

## ColdFront Lingo
* Project
* A project is a container storing users, allocations, publications, grants, and other research output. For details on how projects work, visit the [project docs](https://coldfront.readthedocs.io/en/latest/manual/projects/)
* Allocation
* An allocation is a property that gives a user access to a resource. Allocations can have attributes and interact with plugins for easy automation. Learn more on our [allocation docs](https://coldfront.readthedocs.io/en/latest/manual/allocations/allocations/)
* Resource
* A resource is something a user can request in a quantity specified when allocating. Examples of resources include cloud storage, licenses, and servers. Read more on our [resource docs](https://coldfront.readthedocs.io/en/latest/manual/resources/resources/)
* Principal Investigator (PI)
* A PI can request resources, manage users, give users manager status, receive emails for allocation statuses, and more. View a detailed list of PI permissions on our [PI docs](https://coldfront.readthedocs.io/en/latest/#principal-investigators-pis-or-project-owners)
* Admin
* An admin is in charge of a center and can view all projects, allocations, and resources, along with approving/ denying all requests. An admin can also use the Django admin UI to make these changes. View a detailed list of admin permissions on our [admin docs](https://coldfront.readthedocs.io/en/latest/#hpc-system-administrators)
* Center Director
* A center director sees all the metrics of their center and can view all projects, resource allocations, grants, and publications with read only access. View a detailed list of director permissions on our [center director docs](https://coldfront.readthedocs.io/en/latest/#center-directors)

## ColdFront's Dependencies
When running `pip install -e .` during setup, ColdFront installs several dependencies. Ones that we use often to develop and test include:
* MailHog
* MailHog is used to set up fake email testing, allowing you to see what emails are being sent
* Set up using these [instructions](https://github.com/mailhog/MailHog)
* Create a file in `~/coldfront/.env` with email configs such as:

    DEBUG=TRUE
    EMAIL_ENABLED=TRUE
    EMAIL_HOST=localhost
    EMAIL_PORT=1025
    EMAIL_ADMIN_LIST=your_email
    EMAIL_SENDER=your_email
    EMAIL_TICKET_SYSTEM_ADDRESS=your_email
    EMAIL_DIRECTOR_EMAIL_ADDRESS=your_email
    EMAIL_PROJECT_REVIEW_CONTACT=your_email
    EMAIL_DEVELOPMENT_EMAIL_LIST=your_email

(if you want emails to go to all users, not just the admin, set `DEBUG=FALSE`)
###### To learn more about environment variable configuration, visit [the config docs](https://coldfront.readthedocs.io/en/latest/config/#configuration-files).
* DjangoQ
* DjangoQ is used for things that can't be completed in a short web request, like nightly automated tasks
* Check out [the deployment docs](https://coldfront.readthedocs.io/en/latest/deploy/#create-systemd-unit-file-for-coldfront-qcluster-scheduled-tasks) for more information on how to use DjangoQ
* Redis
* Redis stores the data for DjangoQ tasks in the memory database
* Redis workers monitor DjangoQ for tasks to run
* Run

    apt install redis-server
    systemctl restart redis
    sudo service redis-server start
    DEBUG=True coldfront qcluster

## More Tips
* Check out the [GitHub project kanban board for ColdFront](https://github.com/orgs/ubccr/projects/1) to see the status of tasks across the board
* When editing any .css files, be sure to run `coldfront collectstatic` and frequently hit `Ctrl+Shift+R` to refresh your localhost page and replace cached files
* Run `coldfront test` often to ensure no major changes were made, although these are not comprehensive! They are still a work in progress
* The [Django admin interface](https://docs.djangoproject.com/en/4.1/ref/contrib/admin/) allows you to directly edit the model data and can be accessed directly from the ColdFront website
* When making/ pulling changes to any `models.py` file, which is synonymous to changing the database itself, run `coldfront makemigrations` and `coldfront migrate` to update your local database
* The `base.py` file stores all of the local settings for your install of ColdFront
* How Django works:
###### Image credits: [Mozilla CDN Docs](https://www.google.com/url?sa=i&url=https%3A%2F%2Fdeveloper.mozilla.org%2Fen-US%2Fdocs%2FLearn%2FServer-side%2FDjango%2FIntroduction&psig=AOvVaw1-VhswCSiFM0HL6hgml1JZ&ust=1675459321346000&source=images&cd=vfe&ved=0CBAQjhxqFwoTCMCOzb_i9_wCFQAAAAAdAAAAABAE)

## Useful Links
* [How virtual environments work](https://www.freecodecamp.org/news/how-to-setup-virtual-environments-in-python/) (this will help you install and run packages without interfering with what is already installed on your machine)
* [How to create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) (to present your changes to Dori and Andrew to hopefully merge into the main repo)
###### To link a PR to an issue, include "Resolves issue_number" in the description of your pull request. This way, when the PR is merged, it will close the issue.
* [How to set up the Django Debug Toolbar](https://django-debug-toolbar.readthedocs.io/en/latest/) (displays great info about the queries your page is running and what templates are being displayed)
* [How Crispy Forms works](https://django-crispy-forms.readthedocs.io/en/latest/) (we use this to adjust forms easily, especially since ColdFront uses a lot of forms!)
* [How Bootstrap5 works](https://getbootstrap.com/docs/5.0/getting-started/introduction/) (used for CSS and styling)
* [How to apply custom branding to ColdFront](https://coldfront.readthedocs.io/en/latest/config/#custom-branding) (like Dori and Andrew do on their install!)