Upstream/bitwarden-server
1
0
Fork 0
mirror of https://github.com/bitwarden/server.git synced 2024-11-21 12:05:42 +01:00
Code Issues Projects Releases Wiki Activity
8f7389f153
bitwarden-server/CONTRIBUTING.md

5.2 KiB
Raw Blame History

Contributing: Local Dev Environment Setup

For local development and running the Server (Api, Identity, etc.) you'll need to setup a few things in order to make that work, connect to your own local SQL instance (docker image), as well as have appropriate certificates available for performing encryption, signing, data protection, etc.

User Secrets

You will need to manage user secrets for each site project in the Server solution. This includes predominately the Api and Identity projects, although there are other, lessor used ones that may also need it depending on what you're doing, but these 2 set the foundation.

Self Hosted vs. Not

It is highly recommended that you use the selfHosted: true setting when running locally so the system will not attempt to use cloud services without a valid connection string. Otherwise there are emulators that allow you to run local dev instances of various Azure and/or AWS services such as local-stack, etc. or you can use your own Azure accounts for provisioning the necessary services and set the connection strings accordingly.

Visual Studio on Windows

You can simply right-click on the Project and "View User Secrets" (or something like that), easy peasy.

Visual Studio on macOS

You must open a terminal and go to each project directory. Once there you initiate and create the blank user secrets file by running,

dotnet user-secrets init

You can then view/list any secrets you have set by running, dotnet user-secrets list. For more info see: Safe storage of app secrets in development in ASP.NET Core

Rider

  • Navigate to Preferences -> Plugins and Install .NET Core User Secrets
  • You can now right click on the a project (ex: Api), go to 'tools' and 'Open project user secrets'

User Secrets - Certificates

Once you have your user secrets files setup, you'll need to generate 3 of your own certificates for use in local development.

Generate Certificates

  1. Within a terminal, navigate to ~/Desktop
  2. Run the following command to create an Identity Server (Dev) certificate + key (separate)
openssl req -x509 -newkey rsa:4096 -sha256 -nodes -keyout identity_server_dev.key -out identity_server_dev.crt -subj "/CN=Bitwarden Identity Server Dev" -days 3650
  1. Run the following command to create an Identity Server (Dev) certificate + key pfx file based on the previously created certificate + key
  2. You will be prompted to enter a password - remember this because you’ll need it for your keychain
openssl pkcs12 -export -out identity_server_dev.pfx -inkey identity_server_dev.key -in identity_server_dev.crt -certfile identity_server_dev.crt
  1. Run the following command to create a Data Protection (Dev) certificate + key (separate)
openssl req -x509 -newkey rsa:4096 -sha256 -nodes -keyout data_protection_dev.key -out data_protection_dev.crt -subj "/CN=Bitwarden Data Protection Dev" -days 3650
  1. Once created, do the same process for a Data Protection (Dev) certificate + key pfx file
  2. Again, create a password so you can save the files in your keychain
openssl pkcs12 -export -out data_protection_dev.pfx -inkey data_protection_dev.key -in data_protection_dev.crt -certfile data_protection_dev.crt
  1. Add all of the generated pfx files to your login keychain by double-clicking on the files
    1. You’ll need to enter the respective generated password for each
  2. Update the Trust options for each certificate to always trust - don’t worry, this is secure…. :)
  3. Get the SHA 1 thumbprint for the Identity and Data Protection certificates and them to your Api User Secrets file
  4. Copy + Paste the entire file into the Identity secrets
    1. Access the Identity user secrets the same way Api user

Running and Debugging

Launching the entire bitwarden/server solution for use with the bitwarden/web and other client projects.

Prerequisites

  • Docker MSSQL instance running (and accessible localhost)
  • An ADS connection to the vault_dev database is running
  • Node.js is installed with updated PATH variables for launch
  • User secrets are configured, password updated to MSSQL database

Visual Studio for macOS

You can right click on each project, Identity and then Api, in order, and click Start Debugging Project.

You can also, alternatively if you only need them running locally w/o debugging, open a terminal and navigate to each respective .csproj location and type,

dotnet run

NOTE: when doing this the port number on the URL may be different and you'll need to update any client configuration(s) and/or user secrets accordingly (typically the Api user secrets for the Identity URL).

Rider

  • From within Rider, launch both the Api project and the Identity project
    • This is done by hitting the play button for each project separately

Notes