web

🛠️ Setup

Click to expand

1. Install uv (a Python package manager)
2. Install Git
3. Installing a Git GUI is highly recommended, as they allow for much easier and faster visualization of the commit structure, and interaction with it, which will help you avoid many common mistakes
   • Git Extensions is an excellent choice, with support for pretty much all Git features you'll ever use - though it only runs on Windows, as of time of writing
   • GitHub Desktop works well, but has very limited functionality
4. Clone this repository to your machine
   • Either press a "Clone repository" button in your Git GUI, or run:

     git clone https://github.com/MAKENTNU/web.git

5. Install dev dependencies: (this will create a .venv folder inside your repository folder, by default)

   uv sync --group dev

6. Create an empty .env file directly inside the repository folder, and fill it by copying the contents of .env.example
7. To be able to run commands in the Makefile:
   • If using Windows:
     • Ensure that you have a program installed that can run makefiles. This can be done by e.g. installing GnuWin's Make using WinGet:

       winget install GnuWin32.Make

   • If using Linux/macOS: You don't need to do anything.

PyCharm

We recommend using PyCharm for development, mostly because of its excellent Django support, and because it's able to integrate all the IntelliJ-specific settings in the project's .editorconfig file.

If you decide to use this IDE, open the repo folder cloned as part of the prerequisites, through PyCharm (File → Open...), and set the following settings (File → Settings...):

• Under "Python" → "Django":
  • Make sure the "Enable Django Support" checkbox is checked
  • "Django project root:" <repo folder location>/src
  • "Settings:" web/settings.py
  • "Manage script:" <repo folder location>/manage.py
• Under "Project Structure":
  • Mark the src folder as "Sources"
• Follow these instructions to add the existing uv environment that you created inside the .venv folder

🚀 Starting the webserver

We recommend developing using locally installed dependencies, as it's a lot faster and easier to debug, but if you'd like to use Docker (e.g. for testing stuff in a prod-like environment), follow the instructions under the "Using Docker" section instead.

1. Create an SQLite database file with the proper tables:

   uv run manage.py migrate

2. Create an admin user for local development:

   uv run manage.py createsuperuser

   It's easiest to create one with both the username and the password set to "admin", and with no email address.
3. Run the server:
   • If using PyCharm, just press the green "play" button in the top right corner
     • Make sure that the correct run configuration is selected in the dropdown next to the button, which by default should be named "web" and have a tiny Django logo
   • Otherwise, run:

     uv run manage.py runserver

🐋 Using Docker

1. Install Docker desktop

2. Create a .env.docker file:

   This will contain environment variables that override the ones in .env, which will be used by code running inside Docker.

   The following file contents is a good basis:

   STATIC_AND_MEDIA_FILES__PARENT_DIR='/vol/web/'

3. Build the Docker image and create the database:

   make d-update

4. Create an admin user for local development:

   make d-createsuperuser

5. Run the server:

   • If using PyCharm:
     1. Add a Docker-based Python interpreter with make_ntnu as project name (this should match the -p argument in the Makefile)
     2. Create a "Django Server" run configuration using the newly created Python interpreter, with 0.0.0.0 (instead of localhost) as host (this should match the IP address specified by the command key in compose.dev.yaml)
     3. Press the green "play" button in the top right corner
   • Otherwise, run:

     make d-start

If you encounter any hard-to-fix Docker-related problems, an easy (but drastic) fix can sometimes be to delete the container (make d-down) and follow the steps above again.

🧳 Developing offline

When running uv commands, pass the --offline flag. For example:

uv run --offline manage.py runserver
# Using the make command:
make start uv_args="--offline"

🧑‍💻 Contribution guidelines

See CONTRIBUTING.md for the following topics:

• Code style guides
• Code review guideline: Code smells

📖 Wiki

Visit the wiki to read about various things related to development of this project!

📝 Changelog

View the changelog to see a list of changes made to the website over time, as well as a high-level description of the release process.