Skip to content

Latest commit

 

History

History
276 lines (177 loc) · 16.3 KB

setting-up-for-development.md

File metadata and controls

276 lines (177 loc) · 16.3 KB

Setting Up for Development

CourseLore has been designed to be welcoming to new developers. It’s an excellent first project for people who are new to contributing to open-source software.

Note: If you get stuck, please open an issue including as much information as possible: What you tried, what you expected to happen, what really happened, what error messages you ran into, and so forth.

Running a Pre-Compiled Binary Locally

The best way to get started is to run a pre-compiled CourseLore binary on your machine. You may download CourseLore from two channels: The latest development versions, which are available as Actions Artifacts; and stable versions, which are available as Releases. After you downloaded CourseLore, extract it and run the courselore binary.

Note: You must be signed in to GitHub to download GitHub Actions Artifacts.

Note: CourseLore needs some network ports to be available: 80, 443, 4000, and 4001. Stop other applications you may have running on those ports. In macOS and Linux you may find if an application is running on a network port using, for example, lsof -i:80.

Note: Most Linux distributions prevent regular users from binding to network ports lower than 1024. This is a setting that you should disable.

Note: CourseLore may ask for your password before running. This happens because it runs with HTTPS—not HTTP—in development to reduce confusion around some browser features that work differently under HTTPS. To accomplish this, it needs to install local TLS certificates on your operating system’s trust store. CourseLore relies on Caddy to manage this process.

Note: Firefox may have issues with the local TLS certificate used by CourseLore because by default it uses its own trust store. There are two possible solutions for this:

  1. Use NSS to install the TLS certificate into Firefox’s trust store.

  2. Configure Firefox to use the operating system’s trust store by visiting about:config and setting security.enterprise_roots.enabled to true.

Running from Source

Windows

Option 1: Windows Subsystem for Linux (WSL)

If you’re using WSL, follow the Linux instructions.

Option 2: Native Windows Development Environment

  1. Install Chocolatey and the following packages:

    > choco install nvm python visualstudio2022-workload-vctools vscode git

    Note: You must run PowerShell as administrator for Chocolatey to work.

    Note: You may have to close and reopen PowerShell after installing programs such as Chocolatey and NVM for Windows before you’re able to use them.

    Note: Instead of using Chocolatey, you could go to the websites for the development tools and install them by hand, but Chocolatey makes installation and updates more straightforward.

    Package Breakdown

    • NVM for Windows (nvm): A manager of multiple Node.js installations. While in theory you could install just the latest Node.js version directly from Chocolatey, in practice you’ll often need to test something in different versions of Node.js, particularly when you contribute to the packages on which CourseLore depends, so it’s better to use NVM for Windows from the beginning.

    • Python (python) and Visual Studio C++ Build Tools (visualstudio2022-workload-vctools): These tools are necessary to build native Node.js extensions written in C/C++.

    • Visual Studio Code (vscode): A text editor with excellent support for the programming languages used in CourseLore.

    • Git (git): The version control system used by CourseLore.

  2. Setup Git:

  3. Install the latest version of Node.js with NVM for Windows:

    > nvm install latest

  4. Install the following Visual Studio Code extensions:

  5. Clone the codebase, install the dependencies, and run CourseLore:

    > git clone git@github.com:courselore/courselore.git
> cd courselore
> npm install
> npm start
macOS

  1. Install Homebrew and the following packages:

    $ brew install nvm visual-studio-code git

    Note: Instead of using Homebrew, you could go to the websites for the development tools and install them by hand, but Homebrew makes installation and updates more straightforward.

    Package Breakdown

    • Node Version Manager (nvm): A manager of multiple Node.js installations. While in theory you could install just the latest Node.js version directly from Homebrew, in practice you’ll often need to test something in different versions of Node.js, particularly when you contribute to the packages on which CourseLore depends, so it’s better to use Node Version Manager from the beginning.

    • Visual Studio Code (visual-studio-code): A text editor with excellent support for the programming languages used in CourseLore.

    • Git (git): The version control system used by CourseLore.

  2. Setup Git:

  3. Install the latest version of Node.js with Node Version Manager:

    $ nvm install node

  4. Install the following Visual Studio Code extensions:

  5. Clone the codebase, install the dependencies, and run CourseLore:

    $ git clone git@github.com:courselore/courselore.git
$ cd courselore
$ npm install
$ npm start

    Note: macOS imposes a limit on the number of files a process can open, but in development CourseLore needs to open more files than the default setting allows because it reloads code as soon as you change it. Increase the limit by following these instructions.

Linux (Ubuntu)

  1. Install Homebrew on Linux and the following packages:

    $ brew install nvm git
$ sudo snap install code --classic

    Note: Instead of using Homebrew, you could go to the websites for the development tools and install them by hand, but Homebrew makes installation and updates more straightforward.

    Package Breakdown

    • Node Version Manager (nvm): A manager of multiple Node.js installations. While in theory you could install just the latest Node.js version directly from Homebrew, in practice you’ll often need to test something in different versions of Node.js, particularly when you contribute to the packages on which CourseLore depends, so it’s better to use Node Version Manager from the beginning.

    • Git (git): The version control system used by CourseLore.

    • Visual Studio Code (code): A text editor with excellent support for the programming languages used in CourseLore.

    Why Homebrew for Linux instead of apt (a package manager that comes with Ubuntu)? The packages available from apt prioritize stability, so they run behind on the latest releases. This is desirable for long-running servers, but not for development.

    Why Homebrew for Linux instead of Snap (another package manager that comes with Ubuntu)? Snaps use a constrained permissions system that doesn’t work well with native Node.js extensions written in C/C++. Note that Snaps are the best option for graphical applications such as Visual Studio Code, which aren’t available in Homebrew for Linux, so in the command above we installed Visual Studio Code from Snap.

  2. Setup Git:

  3. Install the latest version of Node.js with Node Version Manager:

    $ nvm install node

  4. Install the following Visual Studio Code extensions:

  5. Clone the codebase, install the dependencies, and run CourseLore:

    $ git clone git@github.com:courselore/courselore.git
$ cd courselore
$ npm install
$ npm start

Testing on Mobile

You may run CourseLore on your machine and access it from a phone, which is essential to test any user interface changes you may introduce. You may use the same procedure to test on different computers running different operating systems.

Option 1: Using the Local Area Network (Preferred)

  1. Establish a network route between your development machine running CourseLore and your phone. The exact steps for accomplishing this depends on your network, but in general it’s enough to have your development machine and your phone on the same wifi.

    iPhone/iPad + Mac Tip: Connect an iPhone/iPad to a Mac with an USB cable and iOS & macOS will establish a route between them. In macOS you may go to System Preferences… > Sharing to find the address you should use in the browser on the iPhone/iPad.

  2. Send the root TLS certificate created by Caddy to the phone.

    Example: In the author’s development machine running macOS the certificate is found at ~/Library/Application Support/Caddy/pki/authorities/local/root.crt. It’s possible to AirDrop that file to an iPhone/iPad.

    Note: Certificates have a .crt extension. Importantly, .key files are not certificates. These files are signing keys which shouldn’t leave your development machine. Anyone with access to that file could intercept and tamper with any network traffic.

  3. Install & trust the TLS certificate on the phone.

    Note: The exact procedure depends on the operating system you’re running, but typically this process occurs in two steps: First install the certificate, then trust it.

    iPhone/iPad Tip: Install the certificate on Settings > General > VPN & Device Management Certificates, and trust it on Settings > General > About > Certificate Trust Settings.

  4. Run CourseLore with the Local Area Network address, for example:

    $ env BASE_URL=https://leafac.local npm start

    Note: The address must start with https, not http. CourseLore runs with HTTPS—not HTTP—in development to reduce confusion around some browser features that work differently under HTTPS.

  5. Visit the address on the phone.

Option 2: Using an SSH Tunnel through a Server That You Have Access to

  1. Follow the instructions from Option 1 to transfer a certificate to the phone.

  2. On the server that you have access to, open an SSH tunnel, for example, on Ubuntu:

    • Modify /etc/ssh/sshd_config to include GatewayPorts yes.
    • Run ssh -NR 0.0.0.0:4001:localhost:4000 root@YOUR-SERVER.COM and leave the terminal session open.

  3. Run CourseLore with the server’s address, for example:

    $ env BASE_URL=https://YOUR-SERVER.COM:4000 npm start

    Note: The address must start with https, not http. CourseLore runs with HTTPS—not HTTP—in development to reduce confusion around some browser features that work differently under HTTPS.

  4. Connect to the tunnel from your machine, for example:

    ssh -NR 4001:localhost:4000 root@YOUR-SERVER.COM

  5. Visit the server’s address on the phone.

Option 3: Using Localtunnel

  1. Install & run Localtunnel following the instructions on the website.

  2. Run CourseLore with the Localtunnel address, for example:

    $ env BASE_URL=https://THE-LOCAL-TUNNEL-ADDRESS npm start

    Note: The address must start with https, not http. CourseLore runs with HTTPS—not HTTP—in development to reduce confusion around some browser features that work differently under HTTPS.

  3. Visit the Localtunnel address on the phone.