From c53eb6b2fe5f0c3e2ff86631d5f859435cb828bb Mon Sep 17 00:00:00 2001 From: Nick Petrushin Date: Wed, 7 Jan 2026 19:15:38 +0100 Subject: [PATCH] Add Dev Container + WSL install docs and link in install guide (#944) (#951) --- documentation/.vitepress/config.mts | 1 + .../docs/install/dev_container_wsl.md | 167 ++++++++++++++++++ documentation/docs/install/getting_started.md | 3 +- 3 files changed, 170 insertions(+), 1 deletion(-) create mode 100644 documentation/docs/install/dev_container_wsl.md diff --git a/documentation/.vitepress/config.mts b/documentation/.vitepress/config.mts index e0a6c12b..243eb690 100644 --- a/documentation/.vitepress/config.mts +++ b/documentation/.vitepress/config.mts @@ -138,6 +138,7 @@ export default defineConfig({ link: "/docs/install/kustomize", }, { text: "Unraid ๐Ÿงก", link: "/docs/install/unraid" }, + { text: "Dev Container + WSL ๐Ÿงฐ", link: "/docs/install/dev_container_wsl" }, { text: "With A Reverse Proxy", diff --git a/documentation/docs/install/dev_container_wsl.md b/documentation/docs/install/dev_container_wsl.md new file mode 100644 index 00000000..07e91800 --- /dev/null +++ b/documentation/docs/install/dev_container_wsl.md @@ -0,0 +1,167 @@ +# Dev Container + WSL ๐Ÿงฐ + +Running AdventureLog in a **Dev Container** allows you to contribute to the project or work on features locally in a fully reproducible development environment with hot reloading, debugging, and tooling isolated inside Docker. + +This guide focuses on **Windows using WSL 2**, but the workflow is similar on other platforms. + +## Prerequisites + +Before starting, ensure you have the following installed: + +* **Docker Desktop** + Download from: [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/) + + > Docker Desktop must be configured to use **WSL 2** + +* **WSL 2 with a Linux distribution installed** + Ubuntu is recommended. + + ```bash + wsl --install -d Ubuntu + ``` + +* **Visual Studio Code** + [https://code.visualstudio.com/](https://code.visualstudio.com/) + +* **VS Code Extensions** + + * Dev Containers + * WSL + +## โš ๏ธ Important Notes (Read First) + +> **TIP** +> Do not use the `docker-desktop` WSL distribution for development. +> Always use a real Linux distro such as **Ubuntu**. + +> **TIP** +> Avoid working in `/mnt/c/...`. +> Clone and work inside your Linux home directory (`/home/`), otherwise file watching and container mounts may behave incorrectly. + +> **TIP** +> Docker must be available *inside* WSL. Make sure WSL integration is enabled in Docker Desktop: +> +> **Docker Desktop โ†’ Settings โ†’ Resources โ†’ WSL Integration โ†’ Enable Ubuntu** + +## Getting Started + +### 1. Clone the Repository (inside WSL) + +Open **Ubuntu (WSL)** and run: + +```bash +cd ~ +git clone https://github.com/seanmorley15/AdventureLog.git +cd AdventureLog +``` + +> **TIP** +> If you plan to contribute changes, fork the repository on GitHub and clone your fork instead: +> +> ```bash +> git clone https://github.com//AdventureLog.git +> ``` + +### 2. Create the Development `.env` File + +```bash +cp .env.example .env +``` + +This creates the `.env` file required for the containers to start. + +> **NOTE** +> The application will start without modifying `.env`. The default values provided in `.env.example` are sufficient for running the project. + +#### Environment Variables + +The Dev Container setup uses the same `.env` configuration as the standard Docker installation. + +For a full list of available environment variables and optional configuration options, see the +[**Docker ๐Ÿ‹ installation guide**](docker.md#configuration). + +### 3. Open the Project in VS Code (via WSL) + +From the project directory: + +```bash +code . +``` + +VS Code should indicate that the folder is opened **in WSL**. + +### 4. Reopen the Project in a Dev Container + +In VS Code: + +1. Press **Ctrl + Shift + P** +2. Select **Dev Containers: Reopen in Container** + +VS Code will: + +* Build the development containers +* Install dependencies +* Attach the editor to the running container + +The first build may take a few minutes. + +## Running the Application + +Once the Dev Container is running, the services are started using Docker Compose. + +If not started automatically, run: + +```bash +docker compose up +``` + +## Accessing the App + +* **Frontend (Web UI)** + [http://localhost:8015](http://localhost:8015) + +* **Backend (API)** + [http://localhost:8016](http://localhost:8016) + +Admin credentials are taken from your `.env` file. + +## Common Issues + +### Docker Not Found Inside WSL + +If you see: + +``` +The command 'docker' could not be found in this WSL 2 distro +``` + +Ensure: + +* Docker Desktop is running +* WSL integration is enabled for **Ubuntu** +* Docker Desktop has been restarted after enabling integration + +### Accidentally Using `/mnt/c` + +If the project lives under `/mnt/c/...`, move it to: + +```bash +/home//AdventureLog +``` + +This avoids performance issues and file watcher bugs. + +## Dev vs Production + +| Feature | Docker Install | Dev Container | +| ------------ | --------------- | ------------------ | +| Intended use | Running the app | Developing the app | +| Hot reload | โŒ | โœ… | +| Debugging | โŒ | โœ… | +| Code editing | โŒ | โœ… | + +For production or personal hosting, follow the standard +[**Docker ๐Ÿ‹ installation guide**](docker.md). + +Enjoy contributing to AdventureLog! ๐ŸŽ‰ +If you run into issues not covered here, please open a discussion or issue so the docs can be improved. diff --git a/documentation/docs/install/getting_started.md b/documentation/docs/install/getting_started.md index b494c71a..cf17154f 100644 --- a/documentation/docs/install/getting_started.md +++ b/documentation/docs/install/getting_started.md @@ -22,6 +22,7 @@ Perfect for Docker beginners. ## โš™๏ธ Advanced & Alternative Setups -- [Nginx Proxy Manager](nginx_proxy_manager.md) โ€” Easy reverse proxy config +- [Dev Container + WSL](dev_container_wsl.md) - Windows dev environment with WSL 2 + Dev Containers +- [Nginx Proxy Manager](nginx_proxy_manager.md) - Easy reverse proxy config - [Traefik](traefik.md) โ€” Dynamic reverse proxy with automation - [Caddy](caddy.md) โ€” Automatic HTTPS with a clean config