Improve Docker documentation for 5.0.0+ and MacOS users #7407

gonzaarancibia · 2025-04-22T11:59:14Z

Description

This PR improves the Docker documentation for setting up the Wazuh development environment, with a focus on MacOS-specific instructions and clarifying behavior differences between versions. It adds detailed explanations for setting vm.max_map_count on MacOS, updates the jq installation instructions, and includes information about accessing the dashboard via HTTPS in version 5.0.0+.

A key improvement is documenting that in version 5.0.0 and later, the Wazuh Dashboard container automatically installs dependencies and starts the server with yarn start --no-base-path, eliminating the need for developers to manually enter the container to run these commands.

Additionally, this PR documents the --no-start flag which allows developers to prevent automatic startup and manually control the initialization process when needed for debugging or custom configurations.

Issues Resolved

Lack of clear MacOS-specific instructions for setting up the development environment
Missing information about automatic startup behavior in version 5.0.0+
Unclear troubleshooting steps for common issues like "Wazuh dashboard server is not ready yet"
Incomplete host file configuration instructions for MacOS users
Confusion about manual vs. automatic dashboard startup in different versions
No documentation for preventing automatic startup when manual control is needed

Evidence

Automatic startup in version 5.0.0+

Video showing the dashboard automatically starting without manual intervention
Container logs showing automatic dependency installation and server startup

without.flag.mov

Manual control with --no-start flag

Video demonstration showing:
- Starting the environment with ./dev.sh --no-start -a up
- Container running but dashboard service not starting automatically
- Manually connecting to the container, install dependencies and starting the service
- Dashboard becoming accessible after manual startup

--no-start-redorc.mov

MacOS-specific vm.max_map_count configuration

Screenshot showing successful execution of the Docker command to set vm.max_map_count on MacOS:

MacOS-specific vm max_map_count configuration

MacOS user permissions setup

Terminal screenshot showing successful execution of the MacOS-specific commands:

Test

To test this PR:

Follow the updated MacOS instructions to set up a new development environment
Verify that the vm.max_map_count command works correctly on MacOS
Confirm that the documentation accurately describes the behavior of version 5.0.0+ containers (automatic dependency installation and server startup)
Test accessing the dashboard via HTTPS as described in the documentation
Verify that developers no longer need to manually run yarn start in version 5.0.0+

Check List

New functionality includes testing.
New functionality has been documented.
Update CHANGELOG.md
Commits are signed per the DCO using --signoff

Signed-off-by: gonzaarancibia <[email protected]>

guidomodarelli · 2025-04-22T17:52:01Z

docker/osd-dev/README.md

+Use the `--no-start` flag if you want to prevent the automatic startup of the dashboard service. This keeps the container running without starting the service, allowing you to connect to it and run commands manually:
+
+``bash
+  For example:


Add ### before the text to avoid confusion with command scripts.

Fixed in commit SHA

docker/osd-dev/README.md

guidomodarelli · 2025-04-22T18:03:44Z

docker/README.md

@@ -107,11 +118,34 @@ This brings up a Dev environment for the `wazuh-dashboard-plugins` development b
 ```bash
 ./dev.sh $WZ_HOME up
 ```
+### Important Note for Version 5.0.0 and Later


It's not exclusive to version 5.0.0. The part about installing dependencies and starting the server with the command yarn start --no-base-path applies to any version of Wazuh.

Fixed in commit [SHA] (7f0c033)

guidomodarelli · 2025-04-22T18:04:35Z

docker/README.md

+If you need to prevent automatic startup and manually control the initialization process, use the `--no-start` flag:
+
+```bash
+./dev.sh --no-start -a up
+```
+This will keep the container running without starting the dashboard service, allowing you to connect to it and run commands manually.


This part is repeated in osd-dev/README.md.

Fixed in commit [SHA] (7f0c033)

guidomodarelli · 2025-04-22T18:06:32Z

docker/README.md

+For older versions (before 5.0.0), you'll need to:
+
+1. Once the containers are up, attach a shell to the development container
+2. Move to the kbn\plugins\wazuh-core directory
+3. Run yarn to install dependencies
+4. Move back to the root folder and run yarn start


If this part is no longer applicable, we could remove it for version 5.0, since the instructions for previous versions are already available in other branches or tags.

Fixed in commit SHA

Signed-off-by: gonzaarancibia <[email protected]>

yenienserrano

Test: 🔴

When I execute the line sudo chown -R $USER:staff $WZ_HOME it gives an error

sudo dscl . -create /Groups/docker-desktop 
sudo dscl . -create /Groups/docker-desktop PrimaryGroupID 100999
sudo dscl . -create /Users/docker-desktop
sudo dscl . -create /Users/docker-desktop UniqueID 100999
sudo dscl . -create /Users/docker-desktop PrimaryGroupID 100999
sudo chown -R $USER:staff $WZ_HOME
zsh: bad substitution

yenienserrano · 2025-05-08T19:20:38Z

docker/README.md

+
+- Connection issues between services
+- Problems with Wazuh indexer
+- Initialization still in progress (wait a few minutes)


Maybe I would add that you have to finish optimizing the code. and the console would display the optimize/success message.

Thanks for the suggestion! I've added information about the code optimization process and the success message that appears in the console. commit

gonzaarancibia · 2025-05-08T20:58:48Z

Test: 🔴

When I execute the line sudo chown -R $USER:staff $WZ_HOME it gives an error

sudo dscl . -create /Groups/docker-desktop 
sudo dscl . -create /Groups/docker-desktop PrimaryGroupID 100999
sudo dscl . -create /Users/docker-desktop
sudo dscl . -create /Users/docker-desktop UniqueID 100999
sudo dscl . -create /Users/docker-desktop PrimaryGroupID 100999
sudo chown -R $USER:staff $WZ_HOME
zsh: bad substitution

@yenienserrano Could you please try replace the last command:

sudo chown -R $USER:staff $WZ_HOME

to:

sudo chown -R $(whoami):staff $WZ_HOME

I've identified the bug and fixed it in this commit.

The problem is that in zsh the $USER variable isn't always expanded correctly, causing the "zsh: bad substitution" error. I've modified the command to use $(whoami) instead, which works consistently in all shells, including zsh.

…ation process Signed-off-by: gonzaarancibia <[email protected]>

…ami) instead of $USER Signed-off-by: gonzaarancibia <[email protected]>

yenienserrano · 2025-05-09T15:26:42Z

docker/osd-dev/README.md

+  ./dev.sh -os 2.19.1 -osd 2.19.1-5.0.0 --no-start -a up
+
+  ### Then connect to the container
+  docker exec -it os-dev-2191-osd-1 bash


In the example would be docker exec -it os-dev-2191-500-osd-1 bash

Thanks for the correction. Resolution commit.

yenienserrano · 2025-05-09T15:28:41Z

docker/osd-dev/README.md

+  docker exec -it os-dev-2191-osd-1 bash
+
+  ### Manually install dependencies
+  cd /kbn/plugins/wazuh-core


Already in the kbn folder would be cd plugins/wazuh-core

Here, don't we need to install dependencies in all plugin folders?

I applied the resolution and added comments to install in all folders. Resolution commit.

yenienserrano · 2025-05-09T15:31:05Z

docker/osd-dev/README.md

+  yarn install
+
+  ### And manually start the service
+  cd /kbn


There is no such folder. cd ../.../ or cd /home/node/kbn would be the case.

Resolution commit.

…ashboard in osd-dev documentation Signed-off-by: gonzaarancibia <[email protected]>

github-actions · 2025-05-09T17:17:06Z

Wazuh Fleet Management plugin code coverage (Jest) test	%	values
Statements	40.38%	( 773 / 1914 )
Branches	36.92%	( 353 / 956 )
Functions	38.38%	( 233 / 607 )
Lines	40.2%	( 753 / 1873 )

github-actions · 2025-05-09T17:17:08Z

Wazuh Core plugin code coverage (Jest) test	%	values
Statements	28.24%	( 711 / 2517 )
Branches	28.92%	( 370 / 1279 )
Functions	26.08%	( 186 / 713 )
Lines	28.38%	( 706 / 2487 )

github-actions · 2025-05-09T17:18:57Z

Wazuh Check Updates plugin code coverage (Jest) test	%	values
Statements	76.44%	( 172 / 225 )
Branches	58.65%	( 61 / 104 )
Functions	61.7%	( 29 / 47 )
Lines	76.44%	( 172 / 225 )

yenienserrano

🟢

Improve Docker documentation for 5.0.0+ and MacOS users

8fed0f3

Signed-off-by: gonzaarancibia <[email protected]>

gonzaarancibia force-pushed the enhancement/docker-macos-auto-startup-docs branch from d167f7e to 8fed0f3 Compare April 22, 2025 12:15

gonzaarancibia added 3 commits April 22, 2025 10:27

improve wording in dashboard initialization instructions

4be4260

Signed-off-by: gonzaarancibia <[email protected]>

remove redundant setup instructions from README

bea7a54

Signed-off-by: gonzaarancibia <[email protected]>

add documentation for --no-start flag

0f5222f

Signed-off-by: gonzaarancibia <[email protected]>

gonzaarancibia marked this pull request as ready for review April 22, 2025 17:18

Machi3mfl self-requested a review April 22, 2025 17:26

guidomodarelli reviewed Apr 22, 2025

View reviewed changes

docker/osd-dev/README.md Outdated Show resolved Hide resolved

guidomodarelli reviewed Apr 22, 2025

View reviewed changes

gonzaarancibia added 3 commits April 22, 2025 15:20

improve formatting in --no-start flag example

7f0c033

Signed-off-by: gonzaarancibia <[email protected]>

add --no-base-path flag to manual start example

f645996

Signed-off-by: gonzaarancibia <[email protected]>

improve and delete deprecated doc

685f98f

Signed-off-by: gonzaarancibia <[email protected]>

yenienserrano requested changes May 8, 2025

View reviewed changes

yenienserrano reviewed May 8, 2025

View reviewed changes

gonzaarancibia self-assigned this May 8, 2025

gonzaarancibia added 2 commits May 9, 2025 10:36

docs(docker-readme): Adds detailed information about the code optimiz…

36022aa

…ation process Signed-off-by: gonzaarancibia <[email protected]>

docs(docker-readme): Fixes MacOS user permission setup by using $(who…

38dcf15

…ami) instead of $USER Signed-off-by: gonzaarancibia <[email protected]>

gonzaarancibia requested a review from yenienserrano May 9, 2025 15:12

yenienserrano reviewed May 9, 2025

View reviewed changes

docs(docker-readme): Update paths, commands, comments to OpenSearch D…

ed136d2

…ashboard in osd-dev documentation Signed-off-by: gonzaarancibia <[email protected]>

gonzaarancibia requested a review from yenienserrano May 9, 2025 17:26

yenienserrano approved these changes May 9, 2025

View reviewed changes

Improve Docker documentation for 5.0.0+ and MacOS users #7407

Are you sure you want to change the base?

Improve Docker documentation for 5.0.0+ and MacOS users #7407

Uh oh!

Conversation

gonzaarancibia commented Apr 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Issues Resolved

Evidence

Test

Check List

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yenienserrano left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gonzaarancibia commented May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented May 9, 2025

Uh oh!

github-actions bot commented May 9, 2025

Uh oh!

github-actions bot commented May 9, 2025

Uh oh!

yenienserrano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gonzaarancibia commented Apr 22, 2025 •

edited

Loading

gonzaarancibia commented May 8, 2025 •

edited

Loading