Skip to content

Windows Setup

Jump to bottom
Alec Li edited this page Sep 8, 2021 · 7 revisions

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. (This is no longer the case; see the last bullet below.)

  • Create a new CSM development database:

    CREATE DATABASE csm_web_dev;

  • Quit the psql shell by typing \q.

  • We will now set up the permissions for the postgres user so that we can login without any password. Locate the pg_hba.conf file in your WSL instance. This is generally inconsistent, but for me it is at /etc/postgresql/13/main/pg_hba.conf (with the 13 replaced by your PostgreSQL version). Feel free to google for other possible locations if it is not there.

    Now, edit the file so that the bottom entries are as follows. The only things that you should be changing are the items in the right-most column; most of them should be set to trust, while the bottom three should be md5. This allows access to all users of the database without a password (if you have multiple other PostgreSQL databases that you'd rather keep the password authentication to, feel free to make these more specific).

    # Database administrative login by Unix domain socket
local   all             postgres                                trust

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     trust
# IPv4 local connections:
host    all             all             127.0.0.1/32            trust
# IPv6 local connections:
host    all             all             ::1/128                 trust
# Allow replication connections from localhost, by a user with the
# replication privilege.
local   replication     all                                     md5
host    replication     all             127.0.0.1/32            md5
host    replication     all             ::1/128                 md5

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.

Clone this wiki locally