add devcontainer setup docs

[tangowithfoxtrot]

Objective

This adds documentation for VS Code Dev Containers, added by the associated PR in server.

[bitwarden-bot]

Checkmarx One – Scan Summary & Details – c548a728-0cec-409b-85b0-bfad51289246

Great job! No new security vulnerabilities introduced in this pull request

[tangowithfoxtrot]

I am not sure why the build workflow is having issues with the link used in the docs; the link works locally and is a direct copy from the standard "Setup Guide" steps.

[cloudflare-workers-and-pages]

Deploying contributing-docs with    Cloudflare Pages

Latest commit:	62b8baf
Status:	✅  Deploy successful!
Preview URL:	https://a2704a4e.contributing-docs.pages.dev
Branch Preview URL:	https://vscode-devcontainers.contributing-docs.pages.dev

View logs

[withinfocus]

Only jumped around for a moment and not a full review, but I think you have link path issues it can't resolve so the build's failing.

Once this renders and we can see a preview it'll be easier to read.

[withinfocus]

⛏️ Capital "C" for "Containers".

This is more of my style I suppose, but I try to future-proof this a bit with something like a list format. This could instead be reworded as a collection of guides available, and then you might want to have this in a subfolder of "guides". We have VS Code and VS material here and perhaps they should follow your pattern here so it isn't unique and on its own.

I realize that's easy to ask, but it'd be a nice structure change.

[withinfocus]

There's a warn decorator you can use here, but not sure if it works within a surrounding block.

[tangowithfoxtrot]

I updated the language and formatting for this process to hopefully make it more clear.

[withinfocus]

@tangowithfoxtrot my other comment may have been missed -- link errors are blocking the build.

[tangowithfoxtrot]

@withinfocus My bad. I did miss your comment there. I can look into an alternative link format, but I'm confused as to why the build workflow would claim that it's broken, as it's a direct copy from the existing "Setup Guide" doc and works with my local build.

[tangowithfoxtrot]

as it's a direct copy from the existing "Setup Guide" doc and works with my local build.

Whoops. That was incorrect 😁 Looking into it now...

[withinfocus]

I think it'd be a good idea to pull the repeated content and see how we can thin this new documentation down.

I am definitely interested in using this!

[withinfocus]

💭 Can we start this documentation right here? The prior two steps are a repeat of the main setup guide.

[withinfocus]

⛏️ Would be nice to use .env instead of "Env".

[withinfocus]

❓ Can we include this somewhere more general, or on the setup guide itself?

[tangowithfoxtrot]

It actually exists in the standard setup guide as well. I could remove this call-out entirely from the dev container, but I think I'd still run into the issue described here.

[tangowithfoxtrot]

On second thought, perhaps that call-out from both guides could be moved here?

[withinfocus]

💭 As I read down here I am seeing more repeated content. How can we better push this all upward and just focus on the Dev Containers content? Keeps it DRY.

[tangowithfoxtrot]

I started this guide as a copy of the server setup guide and took the approach of removing mention of setup steps that the containers handle for us now. There's definitely still some repeating content that I left in, as there are a few things that couldn't be fully automated without a ton of workarounds (mostly for Windows hosts) that still require some user interaction.

I could try to link back to the standard server setup guide for some of the repeating sections, but many of them have just one or two steps that vary just based on the fact that the parts of the setup that require manual interaction (env and secrets) is largely the same, but the way you have to interact with things like that and starting the DB, Azurite, and other containers varies slightly.

As an example, the step that follows step #\4 from the above section in the standard setup guide instructs the user to run docker compose up ... to start the container stack, but doing so using the dev container approach would be redundant, and possibly confusing. I'm unsure of how I might utilize existing parts of the standard setup guide for things like this.

I'd definitely appreciate your thoughts though. I'd love to simplify the docs for this as much as possible and reuse what we can.

[tangowithfoxtrot]

The first thought that comes to mind if we wanted to have slight variance in the steps that do still manually require some user interaction would be to add a "Dev Container" option to the top-right dropdown menu, or something like that.

Doing so might also be weird though because that menu currently distinguishes between internal engineering and external community dev configuration guides. The dev containers also have their own community/internal configurations, so we'd have to further subdivide that in a way that makes sense.

[withinfocus]

⚠️ As I read through all this I started to feel like the guide in this PR is a sub-page of the server's getting started page since there's repeated content. I think this needs some organizing and you wouldn't need this move.

[Hinton]

I agree, maintaining the cloud and self-hosted configs are already confusing enough without adding a third document. It would be nice to have a single guide that gives you two options towards the end.

[tangowithfoxtrot]

I'd love to integrate the container setup into the standard setup guide, but I am not sure how to do so, as even the sections that are shared between the two setups have a few steps that vary slightly.

Is there some way to indicate variance of the setup process at the step level without adding new "Dev Container - Bitwarden Dev" "Dev Container - Community Dev" options in the dropdown menu?

[Hinton]

Maybe tabs? Docusaurus mdx lets you write & use react components if you want. And we could even look into switching the getting started page into a react page if needed.

[withinfocus]

With bitwarden/server#3080 landed should we look at this again?

[abergs]

I wrote these docs since I didn't know this PR existed: bitwarden/server#6318.

Do you want to continue on with this PR or do you want me to open a new PR? The current status quo is not great since we're currently without documentation on how to properly start the server in devcontainer.

[tangowithfoxtrot]

@abergs, I think this PR has probably fallen very out-of-date with some of the devcontainer setup steps, so feel free to either continue this work on your branch, or take over this PR. Whatever is easiest for you.

[withinfocus]

I'd suggest just committing to that older PR and to apply my direction on the code vs. contributing docs.

[abergs]

@withinfocus When you say "that older PR", do you mean this PR that we're currently commenting on since it predates my PR with >2 years?

To me it seems to most pragmatic way forward would be for me to move the text I wrote in bitwarden/server#6318 into a new PR in contributing-docs.

[withinfocus]

Yes, but I don't see the difference -- the author of the Dev Container feature wrote this PR, so it could be expanded upon and improved. There were a number of comments above and I don't see why they're not still valid or important to keep in mind. It's easier to make a new PR, sure, but then that might lose what this PR was doing.

[claude]

Claude finished @tangowithfoxtrot's task —— View job

---

VS Code Dev Container Documentation Review

I've completed a comprehensive review of the VS Code Dev Container documentation. Here's my detailed analysis:

Overall Assessment

This documentation provides valuable guidance for setting up Bitwarden server development using VS Code Dev Containers. However, there are several areas that need attention before merging.

Major Issues

1. Content Duplication (Addresses previous reviewer feedback)

The guide-vscode.md file duplicates significant content from the main setup guide. This violates the repository's DRY principle and creates maintenance overhead. Consider:

• Using Docusaurus tabs to combine setup methods in one file
• Referencing shared sections instead of duplicating them
• Focusing only on Dev Container-specific steps

2. Repository Guidelines Violations

Several violations of CLAUDE.md guidelines:

• Missing numbered instructions format (uses bullet points instead)
• Some commands not in code blocks (line 67: cd dev)
• Inconsistent capitalization in headings (should be "Dev containers" not "Dev Containers")
• Could benefit from conditional <Community> and <Bitwarden> tags for audience-specific content

3. Structure and Organization

• The guide jumps between setup steps and explanatory content
• Missing clear prerequisite callouts at appropriate steps
• The debugging section (lines 233-242) is very brief and could be expanded

Content Quality Issues

Technical Accuracy

• Line 95: "ARM based development environments such as the M1 Macs" - should be "M1 Macs" or "Apple Silicon Macs" for accuracy
• Line 216: URL formatting could be improved with proper link text instead of showing full URL
• Line 269: "database using the VS Code Command Palette" - grammar issue, should be "database. Using the VS Code Command Palette"

Writing and Style

• Line 7: "utilizing Visual Studio Code" - could be simplified to "using VS Code"
• Line 158: "You are now ready to build and run" appears twice (lines 158 and 181)
• Line 243-247: The section about "Managing and updating" has inconsistent tone
• Missing trailing commas in multi-line lists (violates style guide)

Missing Information

• No mention of system requirements or resource needs for Dev Containers
• Limited troubleshooting guidance
• No performance considerations or differences from standard setup

Image Assets

The two PNG files are clear and helpful:

• reopen-in-container.png - Good screenshot of VS Code command palette
• select-container-configuration.png - Shows container selection options clearly

Both images support the instructions well and are appropriately sized.

Specific Line-by-Line Issues

Lines 44-61: Git configuration section duplicates main guide
Line 78: Password complexity list needs trailing commas
Lines 126-152: User secrets section is nearly identical to main guide
Line 163: Image reference should include alt text for accessibility
Lines 184-211: Build instructions duplicate main guide structure

Recommendations

1. Restructure for DRY compliance: Use tabs or conditional content to reduce duplication
2. Follow numbering format: Convert bullet points to numbered instructions with action verbs
3. Add specific Dev Container benefits: Explain why someone would choose this over standard setup
4. Improve prerequisite organization: Clearly separate what must be done before vs. during container setup
5. Expand troubleshooting: Add common Dev Container issues and solutions
6. Consider the repository's audience targeting: Use <Community> and <Bitwarden> tags where appropriate

Previous Review Context

The 2023 review feedback about content duplication and link issues remains valid. This documentation would benefit from the suggested restructuring to focus specifically on Dev Container differences rather than repeating the entire setup process.

Recommendation: Consider implementing the tabs approach suggested in previous reviews or significantly reduce duplication by referencing shared setup steps from the main guide.