Repository navigation
docs: make Aspire the recommended server setup path - #889
withinfocus wants to merge 1 commit into
Conversation
🤖 Bitwarden Claude Code ReviewOverall Assessment: APPROVE This docs-only PR makes Aspire the recommended way to set up a local server. It splits the Setup Guide into shared steps, "Run with Aspire", "Run manually" and "Local services", and adds Aspire guidance to the advanced setup, EF, MSSQL, Events, Portal, SCIM, self-hosted, SSO, troubleshooting and tunnel pages. Every new internal anchor ( |
Deploying contributing-docs with
|
| Latest commit: |
fd7a0c5
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://f1bab865.contributing-docs.pages.dev |
| Branch Preview URL: | https://docs-server-aspire-setup.contributing-docs.pages.dev |
eliykat
left a comment
eliykat
left a comment
There was a problem hiding this comment.
Excited to see Aspire become our official recommendation for DX.
|
|
||
| 3. Set the `MSSQL_PASSWORD` variable. This will be the password for your MSSQL database server. | ||
| <Bitwarden> | ||
| - Copy the user secrets file from the shared Development collection (Your Bitwarden Vault) into |
There was a problem hiding this comment.
pre-existing capitalization/phrasing:
| - Copy the user secrets file from the shared Development collection (Your Bitwarden Vault) into | |
| - Copy the user secrets file from the shared Development collection (in your Bitwarden vault) into |
| ### Aspire | ||
|
|
||
| Debug the `AppHost` project from your IDE. Visual Studio and Rider attach the debugger to each | ||
| service that the AppHost starts, so breakpoints in Api, Identity, and the other services work | ||
| without launching them separately. Rider requires the Aspire plugin. | ||
|
|
||
| ### Visual Studio | ||
|
|
||
| To debug: | ||
|
|
||
| - On Windows, right-click on each project > click **Debug** > click **Start New Instance** | ||
| - On macOS, right-click each project > click **Start Debugging Project** | ||
|
|
||
| ### Rider | ||
|
|
||
| Launch the Api project and the Identity project by clicking the "Play" button for each project | ||
| separately. |
There was a problem hiding this comment.
Heading groups are inconsistent: Aspire is a setup option, but Visual Studio and Rider are IDEs and are implicitly for the manual setup option. Also, while we're here, Visual Studio for MacOS was deprecated in 2024 :)
I suggest this is split up and folded into the respective sections for Run with Aspire and Run manually.
| - **[Manual setup](#run-manually):** you start the Docker Compose containers, run the helper | ||
| scripts, and launch each service yourself. Use this if you need an | ||
| [Entity Framework database](./database/ef/index.mdx) or another container that Aspire doesn't | ||
| manage. |
There was a problem hiding this comment.
It's unfortunate that we need to preserve the manual setup instructions at all. I prefer to have a single opinionated recommendation.
Does manually starting EF also mean that you have to manually start the rest of your server? They're just Docker containers that I assume an Aspire-started server could still talk to.
Alternatively:
- could the Apphost project be updated to start these on request? (maybe out of scope here)
- could the manual setup instructions be demoted to a sub-page - to de-clutter this page and focus on the recommended instructions?
My assumption is that running Bitwarden with an EF database is exceedingly rare, even in a dev environment. Most developers would be using MSSQL for their dev server, and only run the other database containers for integration test purposes (which doesn't affect the server setup).
| :::note | ||
|
|
||
| The emulator connects to the Docker Compose `mssql` container, so it doesn't work with the SQL | ||
| Server that Aspire starts. Use the [manual setup](./guide.md#run-manually) for Azure Service Bus. | ||
|
|
||
| ::: |
There was a problem hiding this comment.
Doesn't Aspire also start azurite though? Why won't it work here?
| With Aspire, set a new `Parameters:sso-org-id` user secret in the `AppHost` folder, then restart the | ||
| AppHost and start the `idp` resource again. |
There was a problem hiding this comment.
This can also be configured through the AppHost UI (Parameters tab) which I think is a better DX.
| After that, rerun the docker compose command from Step 5. | ||
| ```bash | ||
| cd ../AppHost | ||
| dotnet user-secrets set "Database:Password" "<your SQL Server password>" |
There was a problem hiding this comment.
This can also be set via the Parameters tab in the UI.
2 participants
🎟️ Tracking
Follows bitwarden/server#6775, which added the Aspire
AppHost, and its follow-ups: bitwarden/server#7646, bitwarden/server#7670, bitwarden/server#7731, bitwarden/server#7803, bitwarden/server#8082 and bitwarden/server#8319.📔 Objective
The server setup guides only described the manual setup: start Docker Compose, run the helper scripts, then launch each service yourself. This PR documents Aspire as the recommended way to run the server locally and keeps the manual setup as the alternative.
Setup Guide
Azmodule, trusting the dev certificate, theDatabase:Passworduser secret, starting the AppHost, the dashboard, resources you start by hand, and common settings.#mailcatcher,#azuriteand#create-databasestill resolve.setup_secrets.ps1 -clearon every start, so the guide tells readers to put changes indev/secrets.jsonrather than on individual projects.Other pages
SelfHostandDatabase:SelfHostPassword.Parameters:sso-org-iduser secret instead of.env.Broken anchors
The build flagged
#install-licensing-certificateon the Setup Guide and#authorizationon the Portal page. Both headings sat inside<Bitwarden>blocks, and SSR renders community mode, so the table of contents linked to headings that weren't in the HTML. The licensing certificate is now a Bitwarden-only part of the user secrets step. The Authorization heading moved outside the block, with a short<Community>note.🤖 AI-assisted review
code-review-local). It raised one IMPORTANT finding, a wrongcdpath in the Aspire setup steps, which is fixed. No findings were deferred.AppHost/anddev/on servermain, and the AppHost builds there. It wasn't run end to end, because thesetup-secretsresource clears the local per-project user secrets on start.