Windows Setup

This guide will go through all the steps for setting up the CSM repository on Windows. Development on Windows is kind of sucky, but WSL makes it a lot easier, and is what we will be using here. Even so, this is a very lengthy process, and I've tried to make the instructions as clear and simple as possible.

WSL Installation

Go to the Windows docs and follow the instructions to install WSL2. For the Linux distribution, it is recommended that you install Ubuntu 20.04.

Note: This will take a while; be patient.

After WSL2 is installed, you should have gotten a prompt to create a new user. If you have successfully created the new user, you should see a prompt that looks like user@ComputerName:~$; this means that you can skip the next part.

If it does not, you should see a prompt that looks like root@ComputerName:~#. This means that you are logged in to the root user, which is highly inadvisable because it has unlimited access to your filesystem. You will need to follow the steps below to set up a new administrator user:

• Run adduser <username> with your preferred username. This will give you a series of prompts; the only important one is the password. You can leave the rest blank by pressing enter.
• Run adduser <username> sudo, with the same username as before. This will allow the new user to run sudo commands (i.e. run commands as root).
• Quit out of WSL for now; run exit to quit.
• In a Windows command prompt or Powershell window, run wsl -l to get a list of all WSL distributions. This should only list one distribution; copy down the name.
• Run <dist-name> config --default-user <username>, where <dist-name> is the name of the WSL distribution in the previous step, and <username> is the username you chose earlier. This will set the default user to be the one you just created.
• Open the WSL terminal again (either through the app, or just by running <dist-name> in a Windows command prompt/Powershell), and you should find that you are now logged in to the new user you just created.

Aside: WSL Tips

• You can access the WSL filesystem from Windows by going to \\wsl$ in File Explorer. That is, open File Explorer and type \\wsl$ into the address bar at the top. All of your WSL distributions will be shown, and you can browse the filesystem with Windows tools.

• Visual Studio Code has excellent support for WSL; see the official docs. Install the Remote Development extension pack and follow the instructions.

• For quick editing, get used to command-line editors like vim. There are many tutorials online (ex. https://www.openvim.com), though you'll get most of your learning done from experience.

Install Required Packages

Run the following commands in WSL to install and configure the required packages.

• Get and apply all pending updates:

  sudo apt-get update && sudo apt-get upgrade

  After the new WSL distribution is set up, you will need to do some preliminary updating in order to install the required packages. This command will get and apply all pending updates; this may take a while.

• Install NPM and Python 3:

  sudo apt-get install npm python3 python3-pip

• Install PostgreSQL:

  sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
  wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
  sudo apt-get update
  sudo apt-get -y install postgresql postgresql-contrib gcc libpq-dev postgresql-client-common postgresql-common openssl

  PostgreSQL takes a little bit more to install; this was taken from the PostgreSQL install docs, but additional packages are added here because of potential errors that may arise when setting up the repo.

• Install Heroku:

  curl https://cli-assets.heroku.com/install.sh | sh

  This was taken from the Heroku installation docs.

PostgreSQL Setup

You will need to do some additional configuration with PostgreSQL before we begin the repository setup.

• Start the PostgreSQL service:

  sudo service postgresql start

  Note that you will need to run this command every single time you want to run the repo.

• Login to postgres and start the PostgreSQL shell:

  sudo -u postgres psql

  You should now see a different command prompt that looks like postgres=#.

• Create a new PostgreSQL user:

  CREATE USER <username>;

  Here, <username> is the same username that you are logged into WSL with.

• Add a password for the postgres user:

  ALTER USER postgres PASSWORD 'postgres';

  You can choose any password you want, but we will be putting this password in plain-text later locally, so choose a simple password.

• Create a new CSM development database:

  CREATE DATABASE csm_web_dev;

• Quit the psql shell by typing \q.

Clone the Repository

To clone the csm_web repository into WSL, navigate to where you want to clone the repository to and run

git clone https://github.com/csmberkeley/csm_web.git

We clone the repository in the WSL filesystem rather than the Windows filesystem because of better performance and an easier experience with WSL tools.

Now, cd into the project root. The rest of the guide will assume that you are in the project root---that is, inside the csm_web folder you just cloned.

Setup the CSM Repository

• First, we need to create a Python virtual environment:

  pip3 install virtualenv
  python3 -m virtualenv venv

• Activate the virtual environment:

  source venv/bin/activate

  (venv) should now appear in your command prompt.

  Note: you can deactivate the virtual environment later just by running deactivate.

• Next, we need to edit the file at ./csm_web/csm_web/settings.py (this is assuming you are currently within the project root csm_web; yes, this file will be three csm_web's deep).

  You should see the following, from line 104 to line 113:

  if DEBUG:
      DATABASES = {
          'default': {
              'ENGINE': 'psqlextra.backend',
              'NAME': 'csm_web_dev',
              'USER': 'postgres',
              'HOST': 'localhost',
              'PORT': '5432',
          }
      }

  Add a line below 'USER': 'postgres' to supply the password you set earlier with ALTER ROLE:

  if DEBUG:
      DATABASES = {
          'default': {
              'ENGINE': 'psqlextra.backend',
              'NAME': 'csm_web_dev',
              'USER': 'postgres',
              'PASSWORD': 'postgres',  # add this line with your postgres password
              'HOST': 'localhost',
              'PORT': '5432',
          }
      }

  Keep in mind that you should not push this change when developing in the repo.

• Run the setup script

  ./setup.sh

Start the server

Start the Django server with the following:

python3 csm_web/manage.py localhost:8000

You may change the port (currently 8000) to whatever you wish.

If you're working on the frontend, start the npm server with npm run watch, or use npm run dev to update manually.

Remember that every time you close out of WSL and want to run the server again, you need to start the PostgreSQL server with sudo service postgresql start.