diff --git a/docs/getting-started/server/guide-vscode.md b/docs/getting-started/server/guide-vscode.md new file mode 100644 index 000000000..d6277af35 --- /dev/null +++ b/docs/getting-started/server/guide-vscode.md @@ -0,0 +1,270 @@ +--- +sidebar_position: 2 +--- + +# VS Code Dev Containers + +This page will show you how to set up a local Bitwarden server for development purposes utilizing +Visual Studio Code Dev Containers. You can read more about this in the +[Visual Studio Code Dev Containers documentation](https://code.visualstudio.com/docs/devcontainers/containers). + +The Bitwarden server is comprised of several services that can run independently. For a basic +development setup, you will need the **Admin**, **Api**, and **Identity** services. + +:::info + +Before you start: make sure you’ve installed the recommended +[Tools and Libraries](../tools/index.md). Namely, the following: + +- Docker Desktop +- [Visual Studio Code](https://code.visualstudio.com/) +- Azure Data Studio + +::: + +## Clone the repository + +1. Clone the Bitwarden Server project: + + ```bash + git clone https://github.com/bitwarden/server.git + ``` + +2. Open a terminal and navigate to the root of the cloned repository. + +:::caution + +When first opening the repository in Visual Studio Code, you will be prompted to reopen the folder +in a Dev Container. If you have not completed the steps in the +[Configure Env File](#configure-env-file) section below, the creation of the Dev Container will +fail. + +::: + +## Configure Git + +1. Configure Git to ignore the Prettier revision: + + ```bash + git config blame.ignoreRevsFile .git-blame-ignore-revs + ``` + +2. _(Optional)_ Set up the pre-commit `dotnet format` hook: + + ```bash + git config --local core.hooksPath .git-hooks + ``` + + Formatting requires a full build, which may be too slow to do every commit. As an alternative, + you can run `dotnet format` from the command line when convenient (e.g. before requesting a PR + review). + +## Configure Env File + +The Dev Container will automatically load the environment variables from the values in `dev/.env`. +To get started, copy the example file: + +1. ```bash + cd dev + cp .env.example .env + ``` + +2. Open `.env` with your preferred editor. + +3. Set the `MSSQL_SA_PASSWORD` variable. This will be the password for your MSSQL database server. + +:::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 (%). + +::: + +4. You can change the other variables or use their default values. Save and quit this file. + +### SQL Server + +In order to support ARM based development environments such as the M1 Macs, we use the +[Azure SQL Edge](https://hub.docker.com/_/microsoft-azure-sql-edge) docker container instead of a +normal [Microsoft SQL Server](https://hub.docker.com/_/microsoft-mssql-server) container. It behaves +mostly identical to a regular SQL Server instance and runs on port 1433. + +You can connect to it using Azure Data Studio using the following credentials: + +- Server: localhost +- Username: sa +- Password: (the password you set in `dev/.env`) + +### Mailcatcher + +The server uses emails for many user interactions. We provide a pre-configured instance of +[MailCatcher](https://mailcatcher.me/), which catches any outbound email and prevents it from being +sent to real email addresses. You can open its web interface at +[http://localhost:1080](http://localhost:1080). + +## Configure User Secrets + +[User secrets](https://docs.microsoft.com/en-us/aspnet/core/security/app-secrets?view=aspnetcore-6.0) +are a method for managing application settings on a per-developer basis. They override the settings +in `appSettings.json` of each project. Your user secrets file should match the structure of the +`appSettings.json` file for the settings you intend to override. + +We provide a helper script which simplifies setting user secrets for all projects in the server +repository. + +1. Get a template `secrets.json`. We need to get an initial version of `secrets.json`, which you + will modify for your own secrets values. + + + + - Copy the user secrets file from the shared Development collection into the `dev` folder. + - If you don't have access to the Development collection, contact our IT Manager to arrange + access. Make sure you have first set up a Bitwarden account using your company email address. + - This `secrets.json` is configured to use the dockerized Azurite and MailCatcher instances and + is recommended for this guide. + + + +2. Update `secrets.json` with your own values: + + - `sqlServer` > `connectionString`: insert your password where indicated + - `identityServer` > `certificateThumbprint`: insert your Identity certificate thumbprint from + the previous step + - `dataProtection` > `certificateThumbprint`: insert your Data Protection certificate thumbprint + from the previous step + + + + - `installation` > `id` and `key`: + [request a hosting installation Id and Key](https://bitwarden.com/host/) and insert them here + - `licenseDirectory`: set this to an empty directory, this is where uploaded license files will + be stored. + + + +3. Once you have your `secrets.json` complete, proceed to + [Starting the Dev Container Environment](#starting-the-dev-container-environment). + +## Starting the Dev Container Environment + +You are now ready to build and run your development server. + +1. Start the Dev Container by opening the Command Palette (Ctrl/Command+Shift+P) and selecting + **Dev Containers: Reopen in Container**: + + ![Reopen in Container](reopen-in-container.png) + +2. Select the appropriate dev container configuration: + + ![Select container configuration](select-container-configuration.png) + +3. Wait for the container to build and start. The first time you open the container, it will take a + few minutes to build. + +4. Once the container has finished building for the first time, you will be greeted with the + `postCreateCommand` script, which will walk you through generating and applying any additional + secrets or certificates required for the server to run. + +5. Follow the on-screen prompts to finish setting up the server. Then, proceed to + [Build and Run the Server](#build-and-run-the-server). + +## Build and Run the Server + +You are now ready to build and run your development server. + +1. Open a new terminal window in the root of the repository. +2. Restore the nuget packages required for the Identity service: + + ```bash + cd src/Identity + dotnet restore + ``` + +3. Start the Identity service: + + ```bash + dotnet run + ``` + +4. Test that the Identity service is alive by navigating to + [http://localhost:33656/.well-known/openid-configuration](http://localhost:33656/.well-known/openid-configuration) +5. In another terminal window, restore the nuget packages required for the Api service: + + ```bash + cd src/Api + dotnet restore + ``` + +6. Start the Api Service: + + ```bash + dotnet run + ``` + +7. Test that the Api service is alive by navigating to + [http://localhost:4000/alive](http://localhost:4000/alive) +8. Connect a client to your local server by configuring the client’s Api and Identity endpoints. + Refer to + [https://bitwarden.com/help/article/change-client-environment/](https://bitwarden.com/help/article/change-client-environment/) + and the instructions for each client in the Contributing Documentation. + +:::info + +If you cannot connect to the Api or Identity projects, check the terminal output to confirm the +ports they are running on. + +::: + +:::note + +We recommend continuing with the [Web Vault](../clients/web-vault) afterwards, since many +administrative operations can only be performed in it. + +::: + +## Debugging + +You can use the debugger in Visual Studio Code to debug the server by following these steps: + +1. Click the "Debug and Run" button in the left sidebar of Visual Studio Code. + +2. Select the desired debug configuration from the dropdown menu. + +3. Click the "Start Debugging" button to start the debugger. + +## Managing and updating the Dev Containers + +After you’ve run the deployed the Dev Containers, you can use the +[Docker Dashboard](https://docs.docker.com/desktop/dashboard/) or `docker` CLI to manage your +containers. You should see your containers running under the `bitwarden_common` group. + +### Changing the DB Password + +Changing `MSSQL_SA_PASSWORD` variable after first running the Dev Containers will require a +re-creation of the storage volume. + +:::warning + +**The following will delete your development database.** + +To do this, stop any running server processes and run the following commands from the +`./.devcontainer/bitwarden_common` directory: + +```bash +docker compose down +docker volume rm bitwarden_common-bitwarden_mssql-1 +``` + +::: + +After destroying the DB volume, you can rebuild the Dev Containers in Visual Studio Code and the +database using the VS Code Command Palette (Ctrl/Command+Shift+P) and selecting **Dev Containers: +Rebuild Container**. diff --git a/docs/getting-started/server/guide.md b/docs/getting-started/server/guide.md index 3430b8897..a04ca064a 100644 --- a/docs/getting-started/server/guide.md +++ b/docs/getting-started/server/guide.md @@ -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 +developing in a containerized environment. + +::: + ## Clone the repository Clone the Bitwarden Server project and navigate to the root of the cloned repository: diff --git a/docs/getting-started/server/reopen-in-container.png b/docs/getting-started/server/reopen-in-container.png new file mode 100644 index 000000000..a1d1bf806 Binary files /dev/null and b/docs/getting-started/server/reopen-in-container.png differ diff --git a/docs/getting-started/server/select-container-configuration.png b/docs/getting-started/server/select-container-configuration.png new file mode 100644 index 000000000..b66cad054 Binary files /dev/null and b/docs/getting-started/server/select-container-configuration.png differ