AdventureLog/documentation/docs/install/dev_container_wsl.md

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/

  Docker Desktop must be configured to use WSL 2

• WSL 2 with a Linux distribution installed Ubuntu is recommended.

  wsl --install -d Ubuntu
  

• Visual Studio Code 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/<user>), 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:

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:

git clone https://github.com/<your-username>/AdventureLog.git

2. Create the Development .env File

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.

3. Open the Project in VS Code (via WSL)

From the project directory:

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:

docker compose up

Accessing the App

• Frontend (Web UI) http://localhost:8015

• Backend (API) 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:

/home/<user>/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.

Enjoy contributing to AdventureLog! 🎉 If you run into issues not covered here, please open a discussion or issue so the docs can be improved.