-
Notifications
You must be signed in to change notification settings - Fork 121
Local Development with Docker Compose
BloodHound CE contains a development Docker Compose setup that focuses on making it easy to validate changes to the application in development mode. The following features are available:
- Running the entire application stack with hot reloading of source files (HMR for TypeScript and Air rebuilds for Go)
- Running pieces of the application stack with hot reloading (ability to run
api-only
to spin up only the API and databases, not the UI) - Running the application stack with
dlv
debugging enabled (default port is3456
and the API won't start up until you connect, allowing for debugging of application setup) - Running a separate bank of databases as targets for project integration tests
The following is a map of where you can find the configuration files that govern this system:
-
docker-compose.dev.yml
: this is the primary entrypoint for running our containers and all development services are defined here, with environment variables to allow for easy customization locally -
docker-compose.testing.yml
: this is the entrypoint used to run our testing databases (they autorestart by default, so they're a set and forget configuration) -
.air.toml
: defines how to run the API with hot reloading enabled usingcosmtrek/air
-
.air.debug.toml
: defines how to run the API in debugging mode with hot reloading enabled usingcosmtrek/air
-
tools/docker-compose/
: contains our Dockerfiles used to build the development images and any supporting files they need -
local-harnesses/
: contains templates for configuration files compatible with this system (as well as local only copies of the actual configuration files you use)
If you're getting started for the first time, or want to reset your configuration files, you can use just init
to get everything setup with defaults. No manual configuration should be required unless you want to change how the system runs in some way.
We have a .env.example
file available that enumerates the environment variables that the docker compose services support. This includes options like service port forwards (in case you have other things running on the default ports), changing the service hostnames, changing which build.config.json
file you would like to have read when starting up (allows you to have multiple config files and easily switch which is being read on each run), and changing database credentials.
It can be used by copying any values you want to .env
and modifying as needed. Note that you don't need to keep all the environment variables in your local copy, and can instead allow docker compose to use the defined defaults for anything you don't want to change. The defaults in .env.example
should generally be kept in sync with the defaults defined in docker-compose.dev.yml
.
BloodHound supports configuring many options through either environment variables or a configuration json file. The template local-harnesses/build.config.json.template
contains defaults that work out of the box with our docker compose system, with some helpful development options set (not requiring password reset on initial login, setting a static password, etc). The just init
command will copy this template for you by default, but you can create additional *.config.json
files if you want to have multiple configurations set up for different scenarios you want to develop against, and change the BH_CONFIG_FILE
env var in your local .env
file to point at the config you wish to use at any given time.
BloodHound has many integration/E2E tests in its suite. These can either be exercised through your IDE or using beagle
. However, you'll need to define real databases for these integration tests to run against and pass a configuration as an environment variable. The configuration that gets used by default (when using VS Code or just
) is local-harnesses/integration.config.json
which is made from the corresponding template when you run just init
. Normally you shouldn't need to alter this file, but if you need to pass different API config values, this is the file to change.
The testing databases are defined in docker-compose.testing.yml
and there's a useful just
recipe to get them started up.
The best way to interact with our dev environment is using just
. There are a number of just
commands tailored to different development needs, including:
-
just init
: ensures that your environment is initialized, including your defaultbuild.config.json
andintegration.config.json
files -
just bh-dev
: runs services in development mode with hot reloading enabled- By default, the application is available at
bloodhound.localhost
- By default, Neo4J’s web interface can be accessed at
neo4j.localhost
with the default user:password being neo4j:bloodhoundcommunityedition - This recipe allows running other
docker compose
commands, such asbuild
anddown
. Use it rather than invokingdocker compose
directly to ensure the right profiles are being selected
- By default, the application is available at
-
just bh-debug
: runs services in debug mode with hot reloading enabled- Works pretty much exactly like
bh-dev
, except that the API container is run withdlv
and it will not start the actual API service until you attach a debugger (to ensure it’s easy to debug the startup sequence or other items that might try to race you). - BHCE’s debug port is
3456
and there’s a built in configuration for debugging in VS Code under the nameDocker Compose Debug
- Hot reloading will cause the debugger to detach, which is an unfortunate limitation. However, the API still won't start back up until you reattach and doing so is usually pretty fast, so it shouldn't interrupt flows too much (you don't want to be changing code while a debugger is active anyway)
- Works pretty much exactly like
-
just bh-clear-volumes
: runsdocker compose down -v
against your development containers, removing all data from the database and caching volumes- Useful when something breaks and you need a clean start
-
just bh-testing
: runs the integration testing containers for you- Defaults to running
up -d
, so will run in the background - This recipe allows running other
docker compose
commands, such asbuild
anddown
. Use it rather than invokingdocker compose
directly to ensure the right profiles are being selected
- Defaults to running
-
just bh-testing-clear-volumes
: runsdocker compose down -v
against the testing containers, removing all data from the database volumes- Useful when you just need your testing databases wiped clean
Q: I'm getting an error related to writing the go.work.sum
file, how do I fix it?
A: Run just build -v
to do a local build of the system. This will update your local go.work.sum
file for you. Since the container uses the same go.work.sum
that you have locally, it needs to be up to date. A better solution is in the works, but making the volume not read-only brings a lot of headaches so this needs to be fixed with better tooling outside of Docker.
Q: My dev databases are broken, how can I rebuild them?
A: Run just bh-clear-volumes
to reset all your volumes and then start your dev back up
Q: I've made a change to yarn (dependencies, configuration, vite, etc). How do I get those changes in the UI container?
A: If you use just yarn
when doing yarn actions, the default is to also rebuild the UI container for you. If you've made changes without using just yarn
and would like to just rebuild the containers, you can do just bh-dev build bh-ui
to rebuild the UI container. You'll need to restart your containers after rebuilding to see the effect.