Skip to content

Development installation on Windows

Jump to bottom
Carlo Beltrame edited this page Mar 6, 2024 · 5 revisions

a.k.a. Usu's opinionated development stack

This guide brings you from 0 to a locally running instance of ecamp3 on Windows. The setup is highly opinionated. Many other development stacks are possible, but this is the one that works best for me.

If you have any problems during the installation, if something doesn't work or if you need more support or explanations, please open a discussion and we will try to help you.

At the end of this guide you will

  • have a running instance of the complete ecamp3 application (running in Docker via WSL2)
  • have VS Code set up as your IDE
  • know how to start coding and contributing to the project
  • know how to test & debug your code

This guide will not go into the details of the application architecture. Check the Wiki for more information on how the code is organized and how individual services are interlinked.

Setting up Docker environment

Why Docker? Docker allows to encapsulate the complete application in separate containers. This ensures every developer runs on the same environment. The time needed to setup the application is minimal. No need to install and setup php, apache / nginx, postgres, node etc. as everything comes preconfigured in the Docker containers.

Install Docker and WSL2

  1. Set up WSL2 as described here: https://docs.microsoft.com/en-us/windows/wsl/install-win10
    For this guide I chose Ubuntu as the WSL distro. Feel free to chose any distro that is suitable for you, however code examples below might change slightly in that case.

  2. Install Docker for Windows: https://docs.docker.com/docker-for-windows/install/

  3. Enable WSL2 support in Docker: https://docs.docker.com/docker-for-windows/wsl/

Optionally:

  1. Install Windows Terminal: https://aka.ms/terminal

Why WSL2? Running Docker natively under Windows without WSL2 brings a huge performance impact for bind-mounted folders. For development, we heavily rely on mounting source-code and dependencies into the docker container, as you don't want to rebuild every container whenever you change the code. And you really don't want to run the provided setup without WSL2.

Download source code

  1. Open Windows terminal and start a new Ubuntu terminal or start Ubuntu directly from Windows start menu. You'll be asked to create a user and password on first startup.

  2. IMPORTANT CAVEAT: If you start Ubuntu from Windows terminal, the current working directory on Windows will automatically be mounted and set as current directory. Avoid to work from the Windows mount point. Switch to the home folder on the Ubuntu filesystem, e.g.

usu@MY-MACHINE:/mnt/c/Users/urban$ cd /home/usu
usu@MY-MACHINE:~$

Why? By default, the Ubuntu terminal starts with the Windows filesystem mounted under /mnt/c as the current directory. You want to avoid your code being placed there. Otherwise you'll encounter the same performance hit that you wanted to avoid by using WSL2 in the first place.

  1. Download source code
git clone https://github.com/ecamp/ecamp3.git
cd ecamp3

In case git is not preinstalled, run sudo apt-get update && sudo apt-get install git

Git

⚠️ WSL and Git on Windows may cause CRLF issues

Git on Windows is normally set with the config core.autocrlf=true. This checks out all files as CRLF and pushes the ones that used to be LF as LF files. If you run linters or anything inside a Dockercontainer they will most likely override those CRLF files to LF since the container is run on Linux which uses LF. This should not break anything but it is kind of inconvenient to have all the files listed as changed. It's recommended to set autoCRLF to false in the git options of WSL and clone over wsl. Try executing the following command in wsl:

git config --global core.autocrlf false

If you continue to have issues with this then find all config files for git on Windows (there may be up to 3), and setting everywhere the following settings:

[core]
autocrlf = false
eol = lf
filemode = false

and/or Add this to a .gitattributes file at the root level

* text=auto eol=lf

Run docker for the first time

The simplest way to jump-start all containers is by running docker compose:

docker compose up

Docker compose will build & start all necessary containers, download & install dependencies and setup & seed the database. This routine can take a while when you start it for the first time. Grab a coffee ☕ and wait for the terminal to calm down!

Check all containers are running healthy

Open Docker Desktop Dashboard from the Windows tray icon. You should find an overview of all running containers where you can check their health status, see logging output or CLI into the container for troubleshooting. All containers should be running (green).

Run application

Open your preferred browser and navigate to http://localhost:3000. The ecamp3 frontend is loading. Login with

  • user: test-user
  • password: test

Open another browser tab and navigate to http://localhost:3001. You'll see the root point of the backend API.

In case you want to register a new account in your local eCamp, the registration email (and all other emails) are not sent out to the actual recipients, but rather end up in mailhog. You can view all of these emails at http://localhost:3007.

Congratulations 🎊 eCamp v3 is running and you can start exploring & coding.

Setting up the IDE

You can use any editor to change the source-code. However, for serious development you probably want to use an IDE at some point. We can strongly recommend VS Code as it

  • is free & simple to use
  • has tons of good extensions
  • works seamlessly with WSL

Install VS Code

  1. Download and install VS Code from https://code.visualstudio.com/download

  2. Run VS Code directly from Ubuntu:

cd backend
code .

This will fire up VS Code on Windows but remotely connected to your code directory on Ubuntu. Check the green WSL status box in the bottom-left corner. For mote details see https://code.visualstudio.com/docs/remote/wsl.

  1. At first start you'll be prompted to install VS Code server on WSL. Press "install".

Install recommended extensions

VS Code has a vast number of extensions that support your development experience. Feel free to use any that are convenient to you. I recommend to install the following extensions as a bare minimum.

Syntax highlighting and code completion:

  • VueJS tooling: Vetur
  • PHP code completion: PHP IntelliSense
    PHP is required as executable on Ubuntu: run sudo apt-get update && sudo apt-get install php && sudo apt-get install php-sqlite3
    Also, as recommended by the extension it's recommend to disable the VS Code built-in PHP suggestions in Settings under Extensions->PHP->Suggest: Basic

Optional extensions that could support development process:

Code auto formatting

Our source code includes rules for code formatting. You probably don't want to learn these rules by heart & automate proper code formatting (e.g. linting). Linters for PHP (php cs fixer) and Javascript (eslint) can be run manually from the console. The linters are also triggered in the test suite. Hence, your pull request tests will fail if your source code is not properly formatted/linted.

However, it's much more convenient to let the IDE do the work automatically. You can install relevant extensions and enable automatic linting whenever you save.

PHP Linting

curl -L https://cs.symfony.com/download/php-cs-fixer-v2.phar -o php-cs-fixer
sudo chmod a+x php-cs-fixer
sudo mv php-cs-fixer /usr/local/bin/php-cs-fixer

Javascript linting

  • Install ESLint extension
  • Disable built-in Javascript formatter in Settings under Extensions->TypeScript->Format: Enable
  • Enable ESLint extension as formatter Extensions->ESLint->Format: Enable

In order for eslint to work proplery, you need to open VS Code from the frontend folder as the current workspace. Otherwise necessary eslint packages are not found and loaded properly.

cd frontend
code .

The extension needs ESLint to be available on Ubuntu. Normally, VS Code should automatically detect that this dependency is already installed in frontend/node_modules/eslint. Simply press "Allow Everywhere" to confirm.

Format on save

  • Enable Format on Save in VS Code under Settings -> Text Editor -> Formatting

Complete settings.json

By now, your VS Code User settings (settings.json) should contain the following:

{
    "editor.formatOnSave": true,
    "php.suggest.basic": false,
    "php.validate.enable": false,
    "javascript.format.enable": false,
    "eslint.format.enable": true
}

Contribute

Check: https://github.com/ecamp/ecamp3/blob/devel/CONTRIBUTING.md

Test & debug your code

See our testing guides.

Debugging Backend / PHP

Postman Setup (or use Swagger)

Debugging Frontend

{
    "configurations": [
        {
            "type": "pwa-chrome",
            "request": "launch",
            "name": "Launch Chrome against localhost",
            "url": "http://localhost:3000",
            "webRoot": "${workspaceFolder}",
            "skipFiles": [
                "${workspaceFolder}/node_modules/**/*"
            ]
        },
        {
            "type": "node",
            "request": "attach",
            "name": "Jest (attach; docker)",
            "port": 9229,
            "localRoot": "${workspaceFolder}",
            "remoteRoot": "/app"
        }
    ]
}
Clone this wiki locally