Skip to content

Windows Environment Configuration

Jump to bottom
Gabriel Jacoby-Cooper edited this page Jan 30, 2024 · 10 revisions
  1. Install Ubuntu in the Windows Subsystem for Linux (WSL).
    1. Install Ubuntu from the Microsoft Store.
      • The latest version of the “main” Ubuntu store listing should be 22.04. If it isn’t, then use the dedicated 22.04 LTS store listing.
    2. Open the newly installed Ubuntu app.
    3. Complete the guided Ubuntu set-up process.
  2. Download and unpack Swift.
    1. Go to the Swift download page.
    2. Copy the download link for Swift 5.9.2 (or whatever the latest version is) for Ubuntu 22.04 on your processor architecture (either “x86_64” or “aarch64”).
    3. Open an Ubuntu terminal as root.
    4. Run apt-get install binutils gh git gnupg2 libc6-dev libcurl4 libedit2 libgcc-9-dev libpython2.7 libsqlite3-dev libsqlite3-0 libstdc++-9-dev libxml2 libz3-dev pkg-config postgresql tzdata uuid-dev wget zlib1g-dev.
    5. Run cd ~/.
    6. Run wget [swift-link], where [swift-link] is the link that you copied in step 2.ii.
    7. Run tar -xvzf [swift-archive], where [swift-archive] is the path to the archive file that you dowloaded in step 2.vi.
    8. Run rm [swift-archive] to remove the downloaded archive file.
    9. Run mv [swift-directory] swift, where [swift-directory] is the Swift directory that was created in step 2.vii.
      • [swift-directory] should be the same as [swift-archive], minus the .tar.gz suffix.
    10. Run echo 'export PATH="$PATH":/root/swift/usr/bin' >> ~/.bashrc.
    11. Close the Ubuntu terminal.
  3. Set up PostgreSQL.
    1. Open an Ubuntu terminal as root.
    2. Run service postgresql start.
    3. Run su postgres.
    4. Run psql.
    5. Run CREATE DATABASE shuttle_tracker;.
      • Make sure to include the semicolon!
    6. Run ALTER USER postgres PASSWORD '[sql-password]';, where [sql-password] is a new password of your choice.
      • Make sure to include the semicolon!
      • [sql-password] doesn’t have to be secure because your local PostgreSQL server won’t be accessible over the Internet. However, the password will be stored in plain text, so don’t reuse a different password that does need to remain secure.
    7. Type \q and press Return.
    8. Close the Ubuntu terminal.
  4. Install and configure Visual Studio Code.
    1. Install Visual Studio Code from the Microsoft Store.
    2. Open Visual Studio Code.
    3. Select the “Extensions” sidebar.
      • The sidebar picker should be on the left side of the window.
    4. Search for “Swift”.
    5. Install the extension in the search results that’s named “Swift” and that’s published by “Swift Server Work Group”.
      • Make sure to install the right extension; other extensions might not offer the features that you’ll need to work on Shuttle Tracker Server.
    6. Search for “Remote - WSL”.
    7. Install the extension in the search results that’s named “Remote - WSL” and that’s published by “Microsoft”.
    8. Close Visual Studio Code.
  5. Clone the Shuttle Tracker Server repository.
    1. Open an Ubuntu terminal as root.
    2. Run cd /home/[ubuntu-username]/, where [ubuntu-username] is your Ubuntu username.
      • You can use a different path if you prefer to keep your local Shuttle Tracker working copy elsewhere.
    3. Run gh auth login and follow the prompts to sign in to your GitHub account.
      • It’s recommended that you select the HTTPS protocol because some tools don’t work well with Git authentication over SSH.
      • Make sure to respond with Y to the prompt that asks if you want to authenticate Git with your GitHub credentials.
      • You’ll probably find it easiest to authenticate with a Web browser instead of a token when you’re prompted to choose between those two options.
    4. Run gh repo clone wtg/Shuttle-Tracker-Server.
    5. Close the Ubuntu terminal.
  6. Build and run the server.
    1. Open Visual Studio Code.
    2. In the bottom-left corner of the window, click the green button with two opposing arrowheads.
    3. Select “Open Folder in WSL…”.
    4. Navigate to and select your local Shuttle Tracker Server folder.
    5. If prompted, select “Yes, I trust the authors”.
    6. Select the “Extensions” sidebar.
      • The sidebar picker should be on the left side of the window.
    7. Click “Install in WSL: Ubuntu” for “Swift”.
      • This should automatically install both “Swift” and “CodeLLDB” in WSL.
    8. If prompted, select “Global”.
    9. Click the gear icon for “Swift” and select “Extension Settings” from the drop-down menu.
    10. Set the “Swift: Path” setting to “/root/swift/usr/bin”.
    11. Press Ctrl-Shift-P.
    12. Type “Reload Window” and press Return.
    13. In the “Run” menu, select “Open Configurations”
      • If the “Open Configurations” menu item is disabled, then select “Add Configuration…” instead. Select “LLDB” in the prompt that follows.
    14. In the launch.json file that’s opened, add the following JSON snippet to all existing configurations: 
      "env": {
    "POSTGRES_HOSTNAME": "localhost",
    "POSTGRES_USERNAME": "postgres",
    "POSTGRES_PASSWORD": "[sql-password]"
}
    15. Replace all instances of <executable file> with .build/debug/Server
    16. In the “Run” menu, select “Start Debugging”.
      • The first build might take a while. Future builds should be much faster.
      • If the first build fails, then try again. Sometimes, the build system unexpectedly exits too early.
      • If a connection failure is reported in the console, then open a new Ubuntu terminal as root and run service postgresql start.

Currently, the server is configured to use the default PostgreSQL database, not the shuttle_tracker database that you created while following the above instructions. This could cause issues in the future if we change the database schema, so you might want to edit configure.swift to refer to the custom database. Don’t commit the change, though.

Common Issues

If, while following the steps above, you run into either the CREATE DATABASE shuttle_tracker; command hanging or tar -xvzf [swift-archive] returning error messages, then you might need to update WSL to version 2. (This solution only works for Windows users.)

  1. Enable Windows Features.
    1. Open “Turn windows features on or off” by searching for it in the Start menu.
    2. Enable the following features:
      • “Virtual Machine Platform”
      • “Windows Hypervisor Platform/Hyper V”
      • “Windows Subsystem for Linux”
    3. Select “OK” and restart your computer.
  2. Upgrade from WSL 1 to WSL 2.
    1. Download and install the WSL kernel update.
    2. Open the Windows Command Prompt as administrator.
    3. Run wsl -l -v.
      • This will show you a list of installed Linux distributions.
    4. Run wsl --set-version [distribution] 2, where [distribution] is the distribution listed in step 2.iii that you want to update.
    5. Run wsl -l -v again to verify that the WSL version has been updated.

Setting Up pgAdmin

This section is optional. It will install pgAdmin, a GUI tool for managing PostgreSQL servers. You will still need to use WSL to start the local PostgreSQL server.

  1. Download pgAdmin.
    1. Go to the pgAdmin download page.
    2. Select the relevant distribution (Windows).
    3. Select the newest version to download it.
      • If it takes you to another page, then select pgadmin4-….exe to download.
    4. Run the installer and follow the directions, selecting default options if you’re unsure.
  2. Set up pgAdmin.
    1. Open Ubuntu and run service postgresql start as root.
    2. Open pgAdmin
      • If it’s your first time opening pgAdmin, then it will ask that you set a master password to protect your server passwords.
    3. Create the new server and give it an appropriate name.
    4. Go to the connection tab and put localhost as the hostname/address, making sure that postgres is the username and that the password is set to the password that you chose when first setting up environment (“[sql-password]”).
    5. Save the server.
    6. If you haven’t already created the database using CREATE DATABASE shuttle_tracker;, then you can do the same here.
      1. Right-click “Databases” under your server.
      2. Select “Create” and then “Database…”.
      3. Name it shuttle_tracker.
      4. Select “Save”.
Clone this wiki locally