Project Installation

Table of Contents

• Preface
• Prerequisites
• Recommendations
  • MacOS/Unix-like (recommended)
  • Windows
• Installation Instructions
  • Server (Django)
    • With Docker (recommended)
    • Without Docker
  • Application (Next.JS)
    • Without Docker (recommended)
    • With Docker

Preface

The project consists of a frontend application running Next.js, and a Python server running Django. In this document, you will find detailed instructions for setting up the project on MacOS/Unix-like operating systems, and Windows.

There are multiple ways of running the project locally, our recommendations depend on which operating system you're running.

Code blocks prefixed with $ are meant to be run in Terminal (MacOS) and CMD (Windows). Do not include the $ when copying the code.

Recommendations

MacOS/Unix-like (recommended)

Click to expand

Running the project locally with MacOS or other Unix-like operating systems is comparatively straight forward, and the most straightforward approach is to run the server with Docker, and the frontend locally.

Server

Running Server with Docker

Frontend

Running Nextjs (frontend)

Windows

Click to expand

Unfortunately, running the server with Docker on Windows effectively requires you to run the entire project using Windows Subsystem for Linux (WSL). While it requires some configuration initially, it enables you to easily run the project using Docker, which also more closely mirrors the production environment.

If WSL is not an alternative for you, we recommend that you run the project without Docker.

Server

Running Server with Docker (prerequisite: WSL)

Running Server without Docker

Frontend

Running Nextjs (frontend)

Prerequisites

MacOS

Click to expand

Homebrew 🍺

Homebrew is a package manager, which greatly simplifies and manages the installation of packages on your behalf. While it is not required, the installation instructions for MacOS will assume that you have Homebrew.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Windows

Click to expand

To run the project with Docker, refer to Microsoft's documentation for setting up WSL.

Git

MacOS

brew install git

Windows (contributions welcome)

See https://git-scm.com/download/win

Github Configuration

Refer to Getting started with Git.

Installation Instructions

Server (Django)

With Docker (Recommended)

Click to expand

1. Download, install, and start Docker Desktop. Refer to Docker Desktop for installation instructions.

   • With Homebrew

   brew install --cask docker

2. Using the command line (e.g. Terminal or CMD) navigate to the folder where you want to store the project on your computer, e.g. mkdir -p dev/rubberdok && cd dev/rubberdok.

3. Clone the project and navigate to the project folder

   git clone https://github.com/rubberdok/indok-web.git
   cd indok-web

4. Build the project

   docker compose build backend

5. Run the project

   docker compose up backend

6. Migrate the database (i.e. create the tables needed for the server)

   docker compose exec backend python manage.py migrate

7. Seed the database, which sets up some test users and example data.

   docker compose exec backend python manage.py loaddata initial_data

8. The server is now accessible on localhost:8000/admin and localhost:8000/graphql for the admin pages and GraphQL API, respectively.

Without Docker

Click to expand

Disclaimer

This method requires you to manually keep your project structure up-to-date and similar to the environment in Docker. If you are running MacOS, see Running the Server With Docker instead. For Windows, consider setting up WSL. Support for this setup is not actively maintained. Since this method is only recommended for Windows userse without WSL, MacOS specific instructions are not included.

Instructions

1. Using PowerShell navigate to the folder where you want to store the project on your computer, e.g. mkdir -p dev/rubberdok && cd dev/rubberdok.

2. Clone the project and navigate to the project folder

   git clone https://github.com/rubberdok/indok-web.git
   cd indok-web

Setting up the PostgreSQL Database

The project uses PostgreSQL as its database. Even when running the frontend and backend outside of Docker, we still recommend running Postgres through Docker, since you don't need hot reloading there and it makes the setup simpler.

To set up PostgreSQL in Docker, follow these steps:

1. Download, install and start Docker Desktop
2. Open the indok-web folder in VSCode
3. Make a new file called .env inside backend
4. Paste the following line in that file, and save:

DB_HOST=localhost

5. Navigate to indok-web in the terminal (cd indok-web)
6. Type docker compose up postgres

Now Postgres should be up and running! Leave the terminal window open to keep the database running in the background.

If you want to close the database, press Ctrl + C in the terminal running Postgres, or type docker compose down inside the indok-web folder in another terminal. To start Postgres again, type docker compose up postgres, also in the indok-web folder (and make sure Docker Desktop is running!). If you want to clear the database, go to the Volumes tab in Docker Desktop, and delete indok-web_postgres_data.

If you still want to run Postgres without Docker, download and install it from here instead: https://www.postgresql.org/download/. Then follow steps 2-4 as above.

Django

1. Navigate to the project folder, indok-web.

2. (recommended) Download and install pyenv-win, a Python version manager . Refer to their documentation for installation instructions.

3. Install the project's Python version

   pyenv install 3.9:latest
   pyenv local 3.9:latest

4. Set up and activate a virtual environment, a way of scoping Python packages so that you do not install them globally on your computer, which could lead to conflicts with other projects.

   python -m venv .venv
   source .\.venv\bin\activate

5. Install dependencies

   1. Install the GTK3 runtime using the .exe from here: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases

   2. Install Python packages

      pip install -r backend/requirements/local.txt

6. Set environment variables

7. Start the Django server

   python backend/manage.py runserver

8. Open a new shell (leaving the one running the server open), activate the virtual enviroment using source .\.venv\bin\activate and migrate the database.

   python backend/manage.py migrate

9. Load example data and local users

   python backend/mangage.py loaddata initial_data

10. The server should now be running on localhost:8000. The admin page is accessible at localhost:8000/admin, and the GraphQL API at localhost:8000/graphql.

11. To stop the server, press CTRL + C in the shell where it runs (i.e. the same place you ran runserver).

Application (Next.js)

Without Docker (Recommended)

Click to expand

Unlike the server, our frontend application does not use Docker in production, and installing the project locally is required for code completion, so these steps are required regardless, and it's not a pain to get it running on Windows. Therefore, it is easier to run the frontend outside Docker.

1. (Recommended) Install a version manager for Node, see their respective documentation for installation instructions.

   • MacOS/Unix-like: nvm
   • Windows: nvm-windows
     • Scroll down on that page to find nvm-setup.exe, and download it
     • Open the terminal as administrator (PowerShell/Command Prompt/Windows Terminal)
     • Use cd to navigate to where you downloaded the .exe file (e.g. cd downloads)
     • Type .\nvm-setup.exe, and go through the installer

2. Install and use the most recent long-term support (LTS) version of Node

   nvm install --lts
   nvm use --lts

3. Install yarn, the package manager we use.

   npm i -g yarn

4. Nagivate to indok-web/frontend

5. Install dependencies

   yarn

6. Run the application

   yarn dev

7. The application should now be running at localhost:3000. To stop the application, press CTRL/CMD + C in the same shell.

With Docker

Click to expand

1. Refer to steps 1-3 in Running the Server with Docker

2. Build the Docker image

   docker compose build frontend

3. Start the Docker container

   docker compose up frontend

4. The application should now be running at localhost:3000. To stop the application, press CTRL/CMD + C in the same shell.

Next Steps

Refer to local development setup and workflow

Troubleshooting

If you encounter issues during the project setup, please create a new issue and describe the problem in detail, including the steps you took, the error messages you received, and the operating system you are using.

We aim to make the project setup as seamless as possible, if you encounter steps that are unclear, please reach out or create a new issue describing the problem.