Environment setup

Clone Defguard Core repository recursively (including Git submodules like protos and UI):

git clone --recursive [email protected]:DefGuard/defguard.git

With docker-compose

Using Docker Compose you can setup a simple stack with:

• Defguard Core

• PostgreSQL database

• Defguard Gateway

• example device connected to the gateway

This way you'll have some live stats data to work with.

To do so follow these steps:

1. Migrate database and insert test network and device:

docker compose run core init-dev-env

1. Run the application:

docker compose up

Switching images

To use different versions of Defguard images, edit docker-compose.yaml file, replacing image: sections. Consult Defguard Package versions to browse for available image tags.

For example, to use current development version, change this section in docker-compose.yaml:

core:
  image: ghcr.io/defguard/defguard:dev

Running local code

To run local code you will need to build core image from local changes:

docker compose build core

Then just run the compose normally.

docker compose up

Cargo

To run Defguard Core without Docker, you'll need:

• PostgreSQL database

• Protobuf compiler (protoc)

• NodeJS

• environment variables set

The procedure to start Defguard Core:

1. Launch PostgreSQL database, for example using Docker:

docker-compose up -d db

1. Install pnpm

sudo npm i -g pnpm

or use another method described in pnpm installation.

1. Build front-end

pushd web
pnpm install
pnpm build
popd

1. Start Defguard Core in development mode

You'll find environment variables in .env file. Source them however you like (we recommend direnv).

Once that's done, you can run backend with:

cargo run

1. Use a web browser to connect to Defguard. For example, when using the default configuration the web site should be accessible under this address:

http://localhost:8000/

Minimum required settings

Consult Configuration manual for a list of all available configuration settings.

• DEFGUARD_COOKIE_INSECURE=true - running HTTP server locally does not need secured cookies

• DEFGUARD_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - 64-character long security key

• DEFGUARD_LOG_LEVEL=debug - increase logging level

Frontend

The domain used to access the frontend instance has to match with the cookie domain address (which can be set using DEFGUARD_COOKIE_DOMAIN).

For example, if the cookie domain is set to the default value of localhost, you should access frontend using localhost domain.