Quickstart

Development

To get started with development of this project, clone the repository from GitHub:

git

git clone https://github.com/twangodev/uw-coursemap.git \
  --recurse-submodules

Next, create a .env file in the root directory of the project. This project contains an .env.example, which may be copied and modified for each environment.

sh

cp .env.example .env

.env.example

# This is an example .env file used for uw-coursemap-web, uw-coursemap-search, elasticsearch, and generation.
# Please change the values to your own settings, especially the ELASTIC_PASSWORD in production for security reasons.

# Where generated files are stored
DATA_DIR='./data'

# uw-coursemap-web
PUBLIC_API_URL='https://static.uwcourses.com'
PUBLIC_SEARCH_API_URL='https://search.uwcourses.com'

# uw-coursemap-search and elasticsearch
ELASTIC_HOST='https://elasticsearch:9200' # This points to the elasticsearch service
ELASTIC_USERNAME='elastic'
ELASTIC_PASSWORD='CHANGEME' # Change this to a secure password
ELASTIC_VERIFY_CERTS='false' # Since we are using self-signed certificates, set this to false unless you have valid certs
DISCOVERY.TYPE='single-node'

# generation
SITEMAP_BASE='https://uwcourses.com'
MADGRADES_API_KEY='CHANGEME' # Change this to your MadGrades API key
CUDA_DEVICE='' # If applicable, specify the CUDA device to use for generation, e.g., '0' for the first GPU.

Next, determine whether you want to run the frontend, search, generation, or all. If you're not sure what you want to run, you should read up on the architecture to get a better understanding of the project.

Frontend is the easiest to get started with, so we recommend starting there.

Frontend

To begin development on the frontend, ensure you have Node.js installed. Then, navigate into the project directory and install the dependencies:

npm

npm install

You can now run the development server for the frontend, which should be accessible within your browser at the specified URL.

npm

npm run dev

How do I preview documentation?

We use VitePress to generate the documentation for this project, as it runs alongside the frontend. To preview the documentation, you can run the following command:

npm

npm run docs:dev

Search

First, you will need to initialize the git submodules if you have not done so already.

git

git submodule update --init --recursive

Setup Elasticsearch

Next, you will need to install Elasticsearch on your machine. We recommend using Docker to run Elasticsearch, as it is the easiest way to get started. If you don't have Docker installed, it can be easily downloaded with Docker Desktop

docker

docker compose up -d

At this point, you will need to reconfigure your environment variables to point to the Elasticsearch instance. As specified in the docker-compose.yml, the Docker container binds to localhost:9200, so you can use the following configuration:

ELASTIC_HOST=https://localhost:9200

docker-compose.yml

services:
  elasticsearch:
    image: elasticsearch:9.0.2
    container_name: elasticsearch
    env_file: ".env"
    ports:
      - "9200:9200"
      - "9300:9300"

  search:
    container_name: uw-coursemap-search
    image: ghcr.io/twangodev/uw-coursemap-search:v1.3.3
    build:
      context: search
    restart: unless-stopped
    env_file: ".env"
    ports:
      - "3001:8000"
    volumes:
      - ./data:/data
    depends_on:
      - elasticsearch

  web:
    container_name: uw-coursemap-web
    image: ghcr.io/twangodev/uw-coursemap-web:v1.3.3
    build:
      context: .
    env_file: ".env"
    restart: unless-stopped
    ports:
      - "3000:3000"

IMPORTANT

Ensure that your DATA_DIR environment variable is correctly configured. During local development, this should point to a directory on your local machine where the data will be stored. The default is ./data.

In Docker Compose, we mount the data directly onto the root directory of the container, so you can use /data as the value for DATA_DIR.

Setup Flask

Finally, ensure you have Python installed. Follow the documentation to setup a virtual environment with Pipenv

Install the dependencies for the search service:

pipenv

pipenv install

We recommend running the service from the project root directory, as that is likely where your environment variables are set up. You can run the search service with the following command:

pipenv

pipenv run python ./search/app.py

This spins up a development server that listens for requests.

CAUTION

This server is not intended for production use. It is only meant for development and testing purposes. For production, you should use a WSGI server like Gunicorn, which is already configured through the uw-coursemap-search Docker image.

Generation

The generation process requires the same Python setup as the search. Install Pipenv and the dependencies as specified above, just in the generation directory.

TIP

Ideally, you should create separate virtual environments for the search and generation processes.

pipenv

pipenv run python ./generation/main.py --help

For full details on how to run the generation process, see the Generation documentation.

Deployment

We recommend deploying this application using Docker for ease of use. We publish both the frontend and search images to Docker Hub and the GitHub Container Registry, which docker-compose.yml will pull from by default.

To deploy the application, you will need to create a .env file in the root directory of the project, just like in development. You can use the .env.example file as a template and copy it to create your own .env file.

sh

cp .env.example .env

CAUTION

Ensure that you change ELASTIC_PASSWORD in the .env file to a secure password. This is the password for the elastic user in Elasticsearch, and it is used to authenticate the search server to Elasticsearch.

To run the application, run the following command:

docker

docker compose up -d

This will start the application in detached mode. You can view the logs with the following command:

docker

docker compose logs -f

To stop the application, run the following command:

docker

docker compose down

To expose your application to the internet, you can use a production grade reverse proxy like NGINX, Caddy, or Traefik.