docs: add WSL2 Docker-based installation guide

[HimasreeKolathur24]

Description
This PR adds a dedicated guide for installing and running Augur on Windows using WSL2 with Docker.
It documents the recommended Docker-based setup, required prerequisites, common issues, and practices to avoid manual installations that often lead to errors.

This PR fixes #3108

Notes for Reviewers

• This documentation focuses only on Docker-based setups in WSL2.
• Manual (non-Docker) installation steps are intentionally excluded.
• The guide aligns with the existing official Docker installation workflow.

Signed commits

• Yes, I signed my commits.

[sgoggins]

Thanks! This will be helpful to anyone installing WSL.

[sgoggins]

Rerunning CI after failure that seems like a timeout issue on the GH end.

[HimasreeKolathur24]

Rerunning CI after failure that seems like a timeout issue on the GH end.

Thank you. Happy to help if anything is needed.

[MoralCode]

Reformatting this to use the read the docs rst format would help this be seen by more people by adding it to the main docs page

[HimasreeKolathur24]

Reformatting this to use the read the docs rst format would help this be seen by more people by adding it to the main docs page

@MoralCode
Thank you for the suggestion.
I’ve reformatted the WSL documentation using the Read the Docs RST format and updated the PR accordingly so it can be included in the main documentation.

[HimasreeKolathur24]

Hi @sgoggins — I rebased the branch to clean up the commit history and address the review feedback.
All changes are now in a single commit. Thanks!

[MoralCode]

Are there reasons why these things are listed as things not to do? what would the consequences be if someone did them? are they just things you didnt test? or do they cause breakage?

Other people may not have the exact same situation as you, so explaining what happens in these cases can help others decide if this advice applies to them

[HimasreeKolathur24]

These recommendations are based on observed breakage and conflicts.

Manual backend installation inside WSL:
When the backend is installed manually inside WSL while also using Docker, it commonly results in version mismatches, duplicated services, and port conflicts (especially with Python environments, PostgreSQL clients, and dependency versions). This can cause Augur services to fail to start correctly or behave inconsistently between Docker and non-Docker components.

Running PostgreSQL outside Docker:
Running PostgreSQL separately on Windows while also using the Docker-based stack can lead to connection failures and unexpected behavior because the containers are configured to communicate with the PostgreSQL service defined in docker-compose. Using an external instance breaks that expected network configuration and can prevent Augur from initializing or migrating the database correctly.

I will update the documentation to make these consequences explicit so users can better understand when and why these recommendations apply.

[MoralCode]

It sounds like you are trying to essentially run two instances of augur at the same time (which would explain the port conflicts).

is there a reason you were trying to do that, rather than just running things in one of the following ways:

• install docker directly to windows and use the docker stack (the method i would recommend, although that is out of scope for a WSL-specific guide)
• Install augur manually in WSL (i.e. you install and configure each service yourself rather than using the docker compose)
• install docker in WSL and use the docker stack there (this seems really inefficient and unlikely to work properly but could be worth a try)

[HimasreeKolathur24]

Thanks for the clarification.
That’s exactly the situation I encountered. The conflicts happened when parts of Augur were running via Docker while other components were installed manually inside WSL at the same time. That effectively created two partially overlapping environments (Docker-managed services and WSL-host services), which caused port conflicts and inconsistent service behavior.

I wasn’t intentionally trying to run two instances — it was more of an incremental setup attempt where manual installation inside WSL was combined with the Docker stack before realizing how tightly the Docker configuration assumes full control of the backend services.

I agree with your suggested approaches, and the documentation now reflects the recommendation to choose one clean setup path (Docker-based or fully manual) rather than mixing the two. The WSL guide is intentionally scoped to the Docker-based approach since that is the most stable and reproducible option for new users.

[MoralCode]

yeah docker and the manual install are essentially mutually exclusive processes. either you are in charge of managing all the various services that make up augur, or you leave it to the docker compose.

If you run a manual install and choose to run one service, like redis, in docker (without compose, or by making your own custom compose with only that service, custom port numbers, etc) thats fine, but at that point you are largely on your own since you are deviating from the standard docker setup that makes things easier to debug when there are issues.

[HimasreeKolathur24]

Yes, exactly—the docs now emphasize choosing a single setup path and avoiding mixed service management to prevent those conflicts. Thanks again for the guidance on this.

[HimasreeKolathur24]

Thanks for the feedback!
I’ve updated the documentation with explanations describing the consequences of those setups and removed the redundant Markdown version as suggested.

[MoralCode]

As things are currently, we dont officially support windows. If we proceed with adding an install guide like this, i think it should either be on a third-party website (i.e. personal blog post or something that maybe can be linked to from the docs in a "this might work, but your mileage may vary" way, or otherwise clearly marked/separated from official supported documentation.

Anyone have thoughts on which path makes more sense?