Skip to content

Commit

Permalink
docs: Add Dozzle container log viewer documentation to README
Browse files Browse the repository at this point in the history
  • Loading branch information
neumachen committed Feb 26, 2025
1 parent 43f1652 commit 6d75127
Showing 1 changed file with 50 additions and 19 deletions.
69 changes: 50 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,36 +14,40 @@ BloodHound uses graph theory to reveal the hidden and often unintended relations
BloodHound CE is created and maintained by the [BloodHound Enterprise Team](https://bloodhoundenterprise.io). The original BloodHound was created by [@\_wald0](https://www.twitter.com/_wald0), [@CptJesus](https://twitter.com/CptJesus), and [@harmj0y](https://twitter.com/harmj0y).

## Running BloodHound Community Edition

Docker Compose is the easiest way to get up and running with BloodHound CE. Instructions below describe how to install and upgrade your deployment.

### System Requirements
BloodHound CE deploys in a traditional multi-tier container architecture consisting of databases, application, and UI layers.

BloodHound CE deploys in a traditional multi-tier container architecture consisting of databases, application, and UI layers.

**Minimum specifications:**

- 4GB of RAM
- 4 processor cores
- 10GB hard disk space
- 4GB of RAM
- 4 processor cores
- 10GB hard disk space

**For large environments (>50,000 users):**

- 96GB of RAM
- 12 processor cores
- 50GB hard disk space
- 96GB of RAM
- 12 processor cores
- 50GB hard disk space

### Deploy BloodHound CE

Deploying BloodHound CE quickly with the following steps:

1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/). Docker Desktop includes Docker Compose as part of the installation.
2. Download the [Docker Compose YAML file](examples/docker-compose/docker-compose.yml) and save it to a directory where you'd like to run BloodHound. You can do this from a terminal application with `curl -L https://ghst.ly/getbhce`.
> On Windows: Execute the command in CMD, or use `curl.exe` instead of `curl` in PowerShell.
> On Windows: Execute the command in CMD, or use `curl.exe` instead of `curl` in PowerShell.
3. Navigate to the folder with the saved `docker-compose.yml` file and run `docker compose pull && docker compose up`.
4. Locate the randomly generated password in the terminal output of Docker Compose.
5. In a browser, navigate to `http://localhost:8080/ui/login`. Login with a username of `admin` and the randomly generated password from the logs.

*NOTE: The default `docker-compose.yml` example binds only to localhost (127.0.0.1). If you want to access BloodHound outside of localhost, you'll need to follow the instructions in [examples/docker-compose/README.md](examples/docker-compose/README.md) to configure the host binding for the container.*
_NOTE: The default `docker-compose.yml` example binds only to localhost (127.0.0.1). If you want to access BloodHound outside of localhost, you'll need to follow the instructions in [examples/docker-compose/README.md](examples/docker-compose/README.md) to configure the host binding for the container._

### Upgrade BloodHound CE

Once installed, upgrade BloodHound CE to the latest version with the following steps:

1. Navigate to the folder with the saved `docker-compose.yml` file and run `docker compose pull && docker compose up`.
Expand All @@ -55,13 +59,13 @@ The BloodHound team has provided some sample data for testing BloodHound without

## Installation Error Handling

- If you encounter a "failed to get console mode for stdin: The handle is invalid." ensure Docker Desktop (and associated Engine is running). Docker Desktop does not automatically register as a startup entry.
- If you encounter a "failed to get console mode for stdin: The handle is invalid." ensure Docker Desktop (and associated Engine is running). Docker Desktop does not automatically register as a startup entry.

<p align="center">
<img width="302" alt="Docker Engine Running" src="cmd/ui/public/img/Docker-Engine-Running.png">
</p>

- If you encounter an "Error response from daemon: Ports are not available: exposing port TCP 127.0.0.1:7474 -> 0.0.0.0:0: listen tcp 127.0.0.1:7474: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted." this is normally attributed to the "Neo4J Graph Database - neo4j" service already running on your local system. Please stop or delete the service to continue.
- If you encounter an "Error response from daemon: Ports are not available: exposing port TCP 127.0.0.1:7474 -> 0.0.0.0:0: listen tcp 127.0.0.1:7474: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted." this is normally attributed to the "Neo4J Graph Database - neo4j" service already running on your local system. Please stop or delete the service to continue.

```
# Verify if Docker Engine is Running
Expand All @@ -71,19 +75,46 @@ docker info
Stop-Service "Neo4j" -ErrorAction SilentlyContinue
```

- A successful installation of BloodHound CE would look like the below:
- A successful installation of BloodHound CE would look like the below:

https://github.com/SpecterOps/BloodHound/assets/12970156/ea9dc042-1866-4ccb-9839-933140cc38b9

## Development Tools

### Dozzle - Container Log Viewer

The development environment includes [Dozzle](https://github.com/amir20/dozzle), a real-time log viewer for Docker containers that provides a clean web interface for monitoring container logs.

#### Accessing Dozzle

When running the development environment with `docker-compose -f docker-compose.dev.yml up` or `just bh-dev up -d`, Dozzle is available at:

- URL: http://dozzle.localhost
- Default port: 18080 (bound to 127.0.0.1)

#### Configuration

Dozzle can be configured using environment variables:

- `BH_DOZZLE_HOSTNAME`: Hostname for accessing Dozzle (default: `dozzle.localhost`)
- `BH_DOZZLE_PORT`: Port binding for Dozzle (default: `127.0.0.1:18080`)

#### Features

- View logs from all containers in real-time
- Filter logs by container
- Search within logs using text search
- Download logs for sharing or offline analysis

## Useful Links

- [BloodHound Slack](https://ghst.ly/BHSlack)
- [Wiki](https://github.com/SpecterOps/BloodHound/wiki)
- [Contributors](./CONTRIBUTORS.md)
- [Docker Compose Example](./examples/docker-compose/README.md)
- [BloodHound Docs](https://support.bloodhoundenterprise.io/)
- [Developer Quick Start Guide](https://github.com/SpecterOps/BloodHound/wiki/Development)
- [Contributing Guide](https://github.com/SpecterOps/BloodHound/wiki/Contributing)
- [BloodHound Slack](https://ghst.ly/BHSlack)
- [Wiki](https://github.com/SpecterOps/BloodHound/wiki)
- [Contributors](./CONTRIBUTORS.md)
- [Docker Compose Example](./examples/docker-compose/README.md)
- [BloodHound Docs](https://support.bloodhoundenterprise.io/)
- [Developer Quick Start Guide](https://github.com/SpecterOps/BloodHound/wiki/Development)
- [Contributing Guide](https://github.com/SpecterOps/BloodHound/wiki/Contributing)

## Contact

Expand Down

0 comments on commit 6d75127

Please sign in to comment.