Improve readme #54

eliykat · 2024-07-17T04:45:59Z

🎟️ Tracking

N/A

📔 Objective

I set up the Splunk app for local development today and hit a few pain points, possibly because I'm not familiar with the Python ecosystem. In particular:

forcing Docker to use the linux/amd64 version of the Splunk image (on a Mac Silicon)
finding the right Python version and telling Poetry to use it
installing libmagic, which is not installed by default on Mac

I've added these to the instructions, and also restructured them to be more step-by-step.

Two follow-up questions:

are there any objections to me moving these instructions to https://contributing.bitwarden.com where the rest of our documentation lives?
pyproject.toml specifies the python version as python = ">=3.7.17", however these instructions refer to Python 3.8 specifically. I received syntax errors when trying to use 3.12, which is what I already had installed on my system. I suggest we probably need to specify ^3.8 - what do you think @WaciX ?

⏰ Reminders before review

Contributor guidelines followed
All formatters and local linters executed and passed
Written new unit and / or integration tests where applicable
Protected functional changes with optionality (feature flags)
Used internationalization (i18n) for all UI strings
CI builds passed
Communicated to DevOps any deployment requirements
Updated any necessary documentation (Confluence, contributing docs) or informed the documentation team

🦮 Reviewer guidelines

👍 (:+1:) or similar for great changes
📝 (:memo:) or ℹ️ (:information_source:) for notes or general info
❓ (:question:) for questions
🤔 (:thinking:) or 💭 (:thought_balloon:) for more open inquiry that's not quite a confirmed issue and could potentially benefit from discussion
🎨 (:art:) for suggestions / improvements
❌ (:x:) or ⚠️ (:warning:) for more significant problems or concerns needing attention
🌱 (:seedling:) or ♻️ (:recycle:) for future improvements or indications of technical debt
⛏ (:pick:) for minor or nitpick changes

github-actions · 2024-07-17T04:48:32Z

Checkmarx One – Scan Summary & Details – 2b06cd54-ccbc-4387-91a3-932036b34ac1

No New Or Fixed Issues Found

mzieniukbw

Great changes! I have added few comments from me that makes it even better.

Answers to the follow-up questions:

I am fine with moving the contributing instructions to https://contributing.bitwarden.com/.
The 3.7 is EOL, so from development perspective it make sense to upgrade it, but we can't. Python version have to be locked to 3.7, because Splunk Enterprise works for 3.7 only at this moment and there are at least 2 more years of support for the app on those versions. Their newer release (in beta) brings support to 3.9, but it might take a while. I have not tested newer versions of python. We allow for ranges from 3.7, because it's easier from development perspective and we prepare for the Splunk Enterprise new release that brings 3.9 support. Making it easier from development perspective, so using 3.10 or never is a separate initiative.

mzieniukbw · 2024-07-17T07:24:01Z

README.md


-### Local development
+1. Clone the Github repository: `git clone https://github.com/bitwarden/splunk.git`
+2. Install Python 3.8


it's actually 3.7 or newer, but since 3.7 is EOL it might be hard to install. I have tested 3.7, 3.8 and 3.9:

Suggested change

2. Install Python 3.8

2. Install Python 3.8 or 3.9

mzieniukbw · 2024-07-17T07:25:25Z

README.md

+1. Clone the Github repository: `git clone https://github.com/bitwarden/splunk.git`
+2. Install Python 3.8
+3. Install [Poetry][poetry]
+4. If you're using a Mac, install libmagic: `brew install libmagic`


Suggested change

4. If you're using a Mac, install libmagic: `brew install libmagic`

4. If you're using a macOS, install libmagic: `brew install libmagic`

mzieniukbw · 2024-07-17T07:27:20Z

README.md


-Activate shell: `poetry shell`
+1. Install Docker
+2. If you're using an Apple Silicon Mac, open *Docker* -> *Settings* -> *Features in development* -> enable "Use Rosetta for x86/amd64 emulation on Apple Silicon"


I newer Docker Desktop, it got moved from features in development to General

Suggested change

2. If you're using an Apple Silicon Mac, open *Docker* -> *Settings* -> *Features in development* -> enable "Use Rosetta for x86/amd64 emulation on Apple Silicon"

2. If you're using an Apple Silicon Mac, open *Docker Desktop* -> *Settings* -> *General* -> enable "Use Rosetta for x86_64/amd64 emulation on Apple Silicon"

mzieniukbw · 2024-07-17T07:36:45Z

README.md

+2. Install Python 3.8
+3. Install [Poetry][poetry]


Prerequisites should be first in order, before cloning or navigating to directory

mzieniukbw · 2024-07-17T07:37:15Z

README.md

+2. Install Python 3.8
+3. Install [Poetry][poetry]
+4. If you're using a Mac, install libmagic: `brew install libmagic`
+4. Navigate to your local repository


Please correct the numbers, we have two 4s. Also it could be more explicit:

Suggested change

4. Navigate to your local repository

4. Navigate to your local repository: `cd splunk`

mzieniukbw · 2024-07-17T07:38:16Z

README.md

+4. If you're using a Mac, install libmagic: `brew install libmagic`
+4. Navigate to your local repository
+5. Activate the poetry shell: `poetry shell`
+6. Tell poetry to use Python 3.8: `poetry env use python3.8`


Or 3.9, depends on what is installed.
Also it's worth to mention that the python version executable needs to be present in PATH. Otherwise absolute path to the python executable have to be specified.

mzieniukbw · 2024-07-17T07:52:05Z

README.md

- Access logs:
+### Deploy the app
+
+1. Package the app: `./package.sh`


Maybe it's worth to mention that this script produces a packaged splunk application in this location: output/bitwarden_event_logs.tar.gz

mzieniukbw · 2024-07-17T07:53:34Z

README.md

+### Deploy the app
+
+1. Package the app: `./package.sh`
+2. Deploy the app to Splunk: `./deploy.sh`


This script depends on splunk enterprise dunning in docker.
I think we should move the ### Set up Splunk Enterprise to be before ### Deploy the app but after ### Configure your environment

Also the script have the splunk admin's password hardcoded to password, which we now say you can change to something rlse in the ### Set up Splunk Enterprise. We should change the deploy.sh script to have ability to provide the password as argument (defaults to password).

Also it's worth to mention that the script restarts the splunk and it might become unavailable even after script finishes for few seconds.

mzieniukbw · 2024-07-17T07:57:51Z

poetry.lock

there is no need to do it in this PR, since it would require QA testing. Let's leave this to #50 and revert this change.

This was unintentional as I was messing around with my dependencies 😁

eliykat · 2024-07-17T23:52:37Z

Thanks @mzieniukbw , I've continued these changes here: bitwarden/contributing-docs#386

Once that's merged, we can just update this doc to link there.

Re: the Python version - can we specify that it should be =< 3.9? I was more concerned about limiting the use of newer, incompatible versions (3.12 threw errors) rather than bumping the min version (although I see that is what I wrote).

mzieniukbw · 2024-07-19T08:37:07Z

@eliykat i have just tested other python versions and added a suggestion in https://github.com/bitwarden/contributing-docs/pull/386/files
3.10 works fine, but 3.11 and 3.12 throws errors during package validation (splunk tooling python incompatibility).
I don't want to limit the users to specific python versions, so giving them a range, like 3.7-3.10 is fine.
We could limit it in the poetry pyproject.toml file, i don't mind.

eliykat · 2024-08-15T23:59:14Z

I like specifying it in pyproject.toml, it's an easy thing to miss and it's better to get an explicit error than some random runtime failure. I've done that and regenerated the lockfile as required. Now when I try with 3.12:

Current Python version (3.12.4) is not allowed by the project (>=3.7.17, <=3.10).
Please change python executable via the "env use" command.

I've also updated the README to point to the contributing docs.

eliykat requested a review from a team as a code owner July 17, 2024 04:46

eliykat requested review from r-tome and mzieniukbw July 17, 2024 04:46

mzieniukbw requested changes Jul 17, 2024

View reviewed changes

eliykat mentioned this pull request Jul 17, 2024

Add Splunk documentation bitwarden/contributing-docs#386

Merged

bitwarden deleted a comment from bitwarden-bot Jul 23, 2024

Refer to contributing docs, update python version

6a2550c

eliykat force-pushed the improve-readme branch from a2ff4a3 to 6a2550c Compare August 15, 2024 23:58

eliykat requested a review from mzieniukbw August 15, 2024 23:59

mzieniukbw approved these changes Aug 16, 2024

View reviewed changes

r-tome approved these changes Aug 16, 2024

View reviewed changes

eliykat merged commit 169fc89 into main Aug 18, 2024
8 checks passed

eliykat deleted the improve-readme branch August 18, 2024 21:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve readme #54

Improve readme #54

eliykat commented Jul 17, 2024 •

edited

Loading

github-actions bot commented Jul 17, 2024 •

edited

Loading

mzieniukbw left a comment •

edited

Loading

mzieniukbw Jul 17, 2024

mzieniukbw Jul 17, 2024

mzieniukbw Jul 17, 2024

mzieniukbw Jul 17, 2024

mzieniukbw Jul 17, 2024

mzieniukbw Jul 17, 2024

mzieniukbw Jul 17, 2024

mzieniukbw Jul 17, 2024

mzieniukbw Jul 17, 2024

eliykat Jul 17, 2024

eliykat commented Jul 17, 2024

mzieniukbw commented Jul 19, 2024

eliykat commented Aug 15, 2024

	4. If you're using a Mac, install libmagic: `brew install libmagic`
	4. If you're using a macOS, install libmagic: `brew install libmagic`

	2. If you're using an Apple Silicon Mac, open Docker -> Settings -> Features in development -> enable "Use Rosetta for x86/amd64 emulation on Apple Silicon"
	2. If you're using an Apple Silicon Mac, open Docker Desktop -> Settings -> General -> enable "Use Rosetta for x86_64/amd64 emulation on Apple Silicon"

	4. Navigate to your local repository
	4. Navigate to your local repository: `cd splunk`

Improve readme #54

Improve readme #54

Conversation

eliykat commented Jul 17, 2024 • edited Loading

🎟️ Tracking

📔 Objective

⏰ Reminders before review

🦮 Reviewer guidelines

github-actions bot commented Jul 17, 2024 • edited Loading

No New Or Fixed Issues Found

mzieniukbw left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eliykat commented Jul 17, 2024

mzieniukbw commented Jul 19, 2024

eliykat commented Aug 15, 2024

eliykat commented Jul 17, 2024 •

edited

Loading

github-actions bot commented Jul 17, 2024 •

edited

Loading

mzieniukbw left a comment •

edited

Loading