docs: Create documentation on development

[joshzcold]

Fixes: #115

[theredwillow]

When you get to the part about the makefile, you mention docker\docker-compose-dev-wsl.yaml for windows users. As someone who is not familiar with docker yet, I don't know what this file does. I also don't know how to run it (or even access it) within the Linux kernel.

If these files need to be downloaded onto the linux virtual machine thingee, maybe the installation should mention that so people don't have to clone the repo and then move it.

ChatGPT is also saying I need to set up some variables in an env file, such as docker_registry and game_store.

[karlromets]

When you get to the part about the makefile, you mention docker\docker-compose-dev-wsl.yaml for windows users. As someone who is not familiar with docker yet, I don't know what this file does. I also don't know how to run it (or even access it) within the Linux kernel.

If these files need to be downloaded onto the linux virtual machine thingee, maybe the installation should mention that so people don't have to clone the repo and then move it.

ChatGPT is also saying I need to set up some variables in an env file, such as docker_registry and game_store.

Creating documentation that others understand the same way I or @joshzcold do can definitely be a challenge.

Regarding the docker-compose-dev-wsl.yaml file, it exists because WSL handles networking a bit differently. The makefile script should automatically handle this by checking if you're using WSL, so ideally, it shouldn’t require any additional configuration on your part. This will be checked in the future though, since I think it isn't necessary.

The documentation will need improving, but here’s what worked for me (I’m using Windows):

• I don’t have Docker installed on Windows; everything runs in my WSL instance (wsl has docker)
• once you have all the dependencies installed, running make dev should start the dev environment
• however, I had to make some changes, because I couldn't access the website on Windows (it was running, windows just couldn't reach it). I had to add some firewall rules on Windows through powershell:

# Add outbound rules  
netsh advfirewall firewall add rule name="WSL2 HTTPS Out" dir=out action=allow protocol=TCP localport=443
netsh advfirewall firewall add rule name="WSL2 HTTP Out" dir=out action=allow protocol=TCP localport=80
# Add inbound rules
netsh advfirewall firewall add rule name="WSL2 HTTPS" dir=in action=allow protocol=TCP localport=443 
netsh advfirewall firewall add rule name="WSL2 HTTP" dir=in action=allow protocol=TCP localport=80

• As for the environment variables, like docker_registry, you shouldn’t need to manually configure them. If make dev runs successfully and the site is accessible, everything should already be set up correctly.

nginx proxies back-end and front-end to 443, which means once it is running, it should be accessible on https://localhost/

[joshzcold]

For switching the game_store its done like this, but I think you wouldn't need to interact with that unless you are fixing a bug for that specific game_store.

game_store=sqlite make dev

If your dev environment is ready to go then it should just be
make dev

@karlromets would you want to update this branch with your details for getting this working on Windows?
I had to make assumptions about your setup when writing the doc.

[karlromets]

Yes, once I get the time. I'll mark this as a draft for now.

[theredwillow]

I don’t have Docker installed on Windows; everything runs in my WSL instance (wsl has docker)

I wondered if it mattered where Docker was installed, but after reading this https://docs.docker.com/desktop/features/wsl/#turn-on-docker-desktop-wsl-2 I thought that I could use the one on Windows. It would be nicer too, because VS Code's Docker extension goes looking for that one.

I tried running wsl from cmd to enter the Linux kernel. I seem to have entered it in the command line, so I tried following along with https://learn.microsoft.com/en-us/windows/wsl/tutorials/linux to install Docker on WSL, but even sudo doesn't seem to work https://unix.stackexchange.com/questions/679457/wsl2-why-am-i-unable-to-sudo. I can't run apt-get either.

once you have all the dependencies installed, running make dev should start the dev environment

I'm not sure if I can just cd into /temp/docker-desktop-root/mnt/host/c/users etc... to reach my windows' files, but it allows me. not sure if it's just mkdir in the background or something and I'm royally confused. But either way, the make command's not found, so I wouldn't be able to do much anyways.

---

I'm definitely missing fundamentals with this new tech stack (last time I contributed in v1, this repo was a simple frontend). I'll probably need to dive into GoLang, WSL, and Docker Hello World projects or something.

[karlromets]

Yeah you will definitely need some fundamentals, this makes me think, maybe we should just make a guide on how to setup the project on Windows, WSL might not be required...

WSL is Linux, usually its Ubuntu, usually its Ubuntu 22.04 or newer 24.04 or older 20.04

• sudo should work -- this is weird -- apt-get as well, are you on Ubuntu 22.04 -- 24.04 would work and maybe even 20.04?
• I have project on wsl /home/username/Friendly-Feud/ -- not on Windows, as it seems VS Code/Windows doesn't handle the read/writes windows->wsl->windows well enough, there were some latency issues

This is an example how I enter from terminal (vs code has it different, it enters directly to wsl home, not windows mount)
/mnt is on Windows, anything else is on WSL e.g. /home/username

Now running cd Friendly-Feud and doing make dev would run the server for me from here (this is if everything else is fine :D)

sudo not working makes me think there might be something bigger wrong...

[theredwillow]

Thank you!!!

Ran wsl --list and default was "docker-desktop". Ran wsl --install -d Ubuntu-22.04. Finally saw Linux in File Explorer. Had to prod around a little more, but finally seeing my watch server running.

[theredwillow]

Maybe I spoke too soon. After returning to the project after shutting off the computer, I can get make dev to run, I can see the containers in Docker Desktop, but localhost is refusing a connection (and there doesn't seem to be any ports associated with the containers, does that matter?).

There also aren't any IP4Addresses associated with the containers.

I tried adding ports: to the docker-compose-dev-wsl.yaml like there is in docker-compose-dev.yaml, but localhost:3000 doesn't go anywhere either.

I have tried running the firewall commands you provided over and over again, keep getting okay, but that doesn't do anything either.

I tried step 4 of https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers, adding Ubuntu22.04. That didn't help either.

[joshzcold]

Maybe I spoke too soon. After returning to the project after shutting off the computer, I can get make dev to run, I can see the containers in Docker Desktop, but localhost is refusing a connection (and there doesn't seem to be any ports associated with the containers, does that matter?).

There also aren't any IP4Addresses associated with the containers.

I tried adding ports: to the docker-compose-dev-wsl.yaml like there is in docker-compose-dev.yaml, but localhost:3000 doesn't go anywhere either.

I have tried running the firewall commands you provided over and over again, keep getting okay, but that doesn't do anything either.

I tried step 4 of https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers, adding Ubuntu22.04. That didn't help either.

@theredwillow it seems like on windows/wsl you need to go to 127.0.0.1 instead of localhost.

Atleast thats what why @karlromets had to put 127.0.0.1 in the e2e tests configuration to get it to work.

I wouldn't really expect IP addresses for the containers, but the stack should be accessible at https://127.0.0.1 if the containers have started.

[theredwillow]

This worked for a glorious second when I had just started my computer and spun up WSL (before opening Docker Desktop).

However, I then tried to make the change you suggested on my draft MR. Then headed over to the Host page from the browser to test it again, when it hit this line of code from src/pages/index.jsx...

ws.current = new WebSocket(`wss://${window.location.host}/api/ws`);

I wanted to investigate if my backend was running, so I opened Docker Desktop. I didn't see anything running at all. So I figured it must be using docker inside the WSL. Well, that really upset it because after that, the magical 127.0.0.1 stopped working, localhost continued to not work, etc... It was like I was back to where I was before.

Edit: I wanted to investigate more, but some background process was probably mucking things up, so I restarted my computer again without opening Docker Desktop. This time when I hit the error, I just headed over to http://localhost:8080/api/health for a health check, which was just fine.

localhost:3000 was also working fine, but getting the websocket issue.

Edit (2): Okay, I think maybe the issue was I still had that port code in there. Once I got rid of that, those GoLang errors went away. So I guess I need to just avoid using Docker Desktop.

[karlromets]

I think this would be much easier and faster to resolve over a call. However, due to timezone differences, we’d need to agree on a time. Feel free to add me on Discord if you’d like to arrange a call sometime: karlromets.

A few notes in the meantime:

• To verify that the service is running successfully (even if you can’t access it from Windows), try running curl localhost inside WSL. It should return some HTML.
• The front-end and back-end only communicate through the Nginx proxy. If you access localhost:3000, it won’t connect to the back-end. This is why you noticed localhost:3000 working, but the WebSocket failed (no connection to the back-end).
• For me, both 127.0.0.1 and localhost work, so the issue is unlikely to be related to that.
• Background processes can interfere, as you mentioned. I typically check which services are using ports, terminate them, and try again. (on both Windows and WSL)
• So in conclusion, it’s likely an Nginx issue. Since the front-end and back-end are functioning but localhost/ isn’t working, if curl localhost works inside WSL, it’s probably a problem with Windows not being able to connect to WSL.

WSL (should work for you always):

Windows (likely doesn't work for you right now, but should):

[theredwillow]

Is make dev supposed to update node modules too?

The Papa Parse update seems to have alluded my wsl Dockerfile npm install.

[karlromets]

Is make dev supposed to update node modules too?

Yeah ran into same issue, run make dev-down to clear/delete them and then make dev will properly npm install

[joshzcold]

Going to merge this.

I think the doc is sufficient for most work flows and if we need to update it that can be another quick PR.