Skip to content

Windows Setup

Jump to bottom
Alec Li edited this page Jun 19, 2022 · 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.

  • Run the setup script

    ./setup.sh

Start the server

Start the Django server with the following:

python3 csm_web/manage.py runserver 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.

Potential issues

  • When running ./setup.sh, If you get the error

    django.core.exceptions.ImproperlyConfigured: The SECRET_KEY setting must not be empty

    try running

    export SECRET_KEY='temp'

    and then run ./setup.sh again. A fix has been made as of now, and should be reflected in the master branch when it is merged.

  • If localhost:8000 does not work in your browser, try going to 127.0.0.1:8000 instead. (Not entirely sure why this error occurs; perhaps check /etc/hosts and make sure 127.0.0.1 localhost is uncommented in the file.)

  • When running the server, if you get the rror

    django.db.utils.OperationalError: connection to server at "localhost" (127.0.0.1), port 5432 failed: fe_sendauth: no password supplied

    there's a few things you can try to do.

    • Firstly, make sure that you've restarted the PostgreSQL service after updating the pg_hba.conf file with sudo service postgresql restart. Also try completely shutting down WSL (in a Windows command prompt or Powershell, run wsl --shutdown and reopen your WSL terminal), and trying again after starting up the services again.

    • If that does not work, then one workaround is to give Django the password to the postgres user anyways.

      In commit f93c29b, I've updated how the setup.sh script modifies your venv/bin/activate script to update the environment variables. If you have done your repository setup before pulling this commit, the easiest way to update is to remove your virtual environment (i.e. delete your venv folder and recreate it), and then run the setup.sh script again. If you've done the repository setup after this commit, you can continue on.

      After doing that, go to your .env file in the repository root and add the line

      POSTGRES_PASSWORD=your_password_here

      with the password you specified when creating the postgres user earlier. This file will never be committed, nor shared with anybody when you use git, but it will still be in plaintext on your computer; keep this in mind if you've set your password already. I typically just set the password to be postgres (same as the username), since this is a development database local to your computer.

      Once you've added this line, deactivate the virtual environment and then reactivate it by source venv/bin/activate. This should update your environment variables (you can check with echo $POSTGRES_PASSWORD to make sure the password is printed), and now the error should be resolved.

Clone this wiki locally