The aim of this document is to provide instruction on how to setup a functional install of Doubtfire on Windows, via the Windows Subsystem for Linux (WSL). This document will also entail how to properly modify the codebase (using Visual Studio Code), such that no incompatibilities arise between the Windows and Linux filesystems.

Once you have all of these steps complete you should be setup and ready to start using Doubtfire

Requirements

Ensure the following is setup and ready to use:

  1. An updated installation of Windows 10, with the Windows Subsystem for Linux optional feature enabled (follow the instructions here).

  2. WSL Ubuntu distribution (install from the Windows Store here)

  3. Visual Studio Code (download from https://code.visualstudio.com/).

Once these are all activated/installed, proceed to Step 1.

Step 1: Setup WSL & Ubuntu

  1. If you haven't already, enable the Windows Subsystem for Linux optional feature of Windows 10. To do this, launch the “Windows Features” dialog, activate the “Windows Subsystem for Linux” feature, and click “OK”. You may have to restart Windows.

    Activate WSL

  2. Install the WSL Ubuntu distribution if it is not yet installed. This can be downloaded via the Windows Store here.

  3. Launch the Ubuntu terminal, via either the “Ubuntu” entry in the start menu, or ubuntu.exe accessible via the command line (pictured). You will be prompted to enter a Unix username & password upon first launch. Ensure your username consists of lowercase letters.

    Initialise Ubuntu

  4. Update Ubuntu by executing the commands sudo apt update and sudo apt dist-update to update Ubuntu the package lists and upgrade packages respectively.

    Update Ubuntu

Your WSL Ubuntu environment is now setup and ready to install Doubtfire, proceed to the next step!

Step 2: Setup the Doubtfire Backend

Now that your Ubuntu distribution is configured, it's time to install the Doubtfire backend.

  1. First, create the Doubtfire directory and enter the directory. This step is optional, but it is useful keep the codebase in its own directory.

    Create Doubtfire directory

  2. Clone the Doubtfire repositories by cloning from the Doubtfire GitHub repository links below using git clone <repo_link>.

    Note: It is recommended that you first fork the repositories onto your own Github account, and clone from there. Please refer to the CONTRIBUTING.md file of each project for detailed instructions.

    Clone Doubtfire repositories

  3. Enter the doubtfire-api directory, and run the setup script to install the doubtfire-api by typing ./setup.sh. You may be asked at times to interact with the console (such as entering your password, pressing enter etc.) so keep an eye on it. This may take a while.

    Setup doubtfire-api

  4. Ensure that doubtfire-api is installed correctly by starting the backend server with bundle exec rails s.

    Start doubtfire-api

    Confirm that the backend is running by navigating to http://localhost:3000/api/docs/ in your web browser. You should see the Swagger UI and a list of all the API endpoints.

Leave the server running and open a new Ubuntu terminal by opening the Ubuntu app from the start menu again. Continue to step 3 to install the Doubtfire frontend.

Step 3: Setup the Doubtfire Frontend

  1. In the new terminal, run the doubtfire-web setup by changing directory to ~/Doubtfire/doubtfire-web and executing the setup script.

    Doubtfire set up

  2. Start the frontend by executing npm start.

    Start frontend

  3. Verify the frontend is running by navigating to http://localhost:4200/. You should see the Doubtfire login interface (as long as the backend is also running).

    Setup doubtfire-api

    To stop the server, open the terminal window and press Ctrl + C

    Continue to step 4 for information regarding development with WSL.

Step 4: Setup Doubtfire.io

Doubtfire.io is the Doubtfire documentation project. Please refer to the "Getting Started" section of its CONTRIBUTING.md file to setup the project and its development environment, locally.

Step 5: Developing with WSL

To avoid any errors between the Windows filesystem and Linux filesystem when editing, Microsoft has implemented features into Windows and Visual Studio Code itself to prevent corruption of the Linux subsystem, therefore VS Code must be the editor you use. Ensure you have the latest version of Windows 10 and Visual Studio Code before proceeding.

  1. Install VS Code Server on Ubuntu. This is as simple as running the command code inside of the terminal.

    Install Server

  2. Open VS Code in the Doubtfire directory and configure. Running code . will open VS Code in the directory you are currently in.

    Open VS Code

    This will open a new VS Code window in the Doubtfire directory. If prompted to install "WSL – Remote" click the install button (this may require a reload).

    VS Code

    You should now see the Doubtfire codebase! The bottom left hand corner should indicate that you are connected to WSL