add devcontainer setup docs #154
Conversation
|
No New Or Fixed Issues Found |
|
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. |
Deploying with
|
| Latest commit: |
f3909e0
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://a768163d.contributing-docs.pages.dev |
| Branch Preview URL: | https://vscode-devcontainers.contributing-docs.pages.dev |
docs/getting-started/server/guide.md
Outdated
| @@ -22,6 +22,13 @@ Before you start: make sure you’ve installed the recommended | |||
|
|
|||
| ::: | |||
|
|
|||
| :::info | |||
|
|
|||
| A guide for developing in VS Code Dev containers can be found [here](./guide-vscode) if you prefer | |||
There was a problem hiding this comment.
⛏️ 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.
| Changing `MSSQL_SA_PASSWORD` variable after first running the Dev Containers will require a | ||
| re-creation of the storage volume. | ||
|
|
||
| **Warning: this will delete your development database.** |
There was a problem hiding this comment.
There's a warn decorator you can use here, but not sure if it works within a surrounding block.
There was a problem hiding this comment.
I updated the language and formatting for this process to hopefully make it more clear.
|
@tangowithfoxtrot my other comment may have been missed -- link errors are blocking the build. |
|
@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 |
Whoops. That was incorrect 😁 Looking into it now... |
| you can run `dotnet format` from the command line when convenient (e.g. before requesting a PR | ||
| review). | ||
|
|
||
| ## Configure Env File |
There was a problem hiding this comment.
💭 Can we start this documentation right here? The prior two steps are a repeat of the main setup guide.
There was a problem hiding this comment.
⛏️ Would be nice to use .env instead of "Env".
| :::caution | ||
|
|
||
| Your MSSQL password must comply with the following | ||
| [password complexity guidelines](https://docs.microsoft.com/en-us/sql/relational-databases/security/password-policy?view=sql-server-ver15#password-complexity) | ||
|
|
||
| - It must be at least eight characters long. | ||
| - It must contain characters from three of the following four categories: | ||
| - Latin uppercase letters (A through Z) | ||
| - Latin lowercase letters (a through z) | ||
| - Base 10 digits (0 through 9) | ||
| - Non-alphanumeric characters such as: exclamation point (!), dollar sign ($), number sign (#), or | ||
| percent (%). | ||
|
|
||
| ::: |
There was a problem hiding this comment.
❓ Can we include this somewhere more general, or on the setup guide itself?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
On second thought, perhaps that call-out from both guides could be moved here?
|
|
||
| 4. You can change the other variables or use their default values. Save and quit this file. | ||
|
|
||
| ### SQL Server |
There was a problem hiding this comment.
💭 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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| @@ -1,2 +1,2 @@ | |||
| label: "Databases" | |||
| position: 2 | |||
| position: 3 | |||
There was a problem hiding this comment.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
|
With bitwarden/server#3080 landed should we look at this again? |
Objective
This adds documentation for VS Code Dev Containers, added by the associated PR in server.