defguard
  • Introduction
  • User documentation (help)
    • Configuring VPN
      • Defguard Desktop Client
        • Update instance
      • Other WireGuard® Clients
        • Configuring a device for new VPN Location manually
    • Password change / Reset
    • Enrollment & Onboarding
      • With internal Defguard SSO
      • With external SSO (Google/Microsoft/Custom)
    • Setting up 2FA/MFA
    • Desktop Client
    • CLI Client
  • Admin & features
    • Deploying your instance
      • One-line install script
      • Standalone package based installation
      • Docker images and tags
      • Docker Compose
      • Kubernetes
      • Upgrading
      • Gateway
        • Running gateway on MikroTik routers
      • Securing gRPC communication
      • OpenID RSA key
      • Configuration
      • Pre-production and development releases
      • High Availability and Failover
      • Health check
    • Features & configuration
      • Zero-Trust VPN with 2FA/MFA
        • Create/manage VPN Location
        • Network overview
        • Executing custom gateway commands
        • Multi-Factor Authentication (MFA/2FA)
          • MFA Architecture
        • Remote desktop client configuration
        • DNS and domains
      • Remote user enrollment
        • User onboarding after enrollment
      • SSO (OpenID Connect)
        • Portainer
        • Grafana setup
        • Proxmox
        • Matrix / Synapse
        • Django
        • MinIO
        • Vault
      • SMTP for email notifications
      • YubiKey Provisioning
      • Webhooks
      • Forward auth
      • SSH Authentication
      • Network devices
      • Gateway notifications
      • New version notifications
  • Troubleshooting Guide
    • Sending support information
    • Client Windows installer exit codes
    • Client "All traffic" connection issues
    • WebAuthn security keys
  • Enterprise Features
    • License
    • Enteprise features
      • Automatic (real time) desktop client configuration & sync
      • External OpenID providers
        • Google
        • Microsoft
        • Zitadel
        • Keycloak
        • JumpCloud
        • Okta
        • Custom
      • External OIDC secure enrollment
      • VPN & Client behavior customization
      • REST API
      • Access Control List
        • ACL Aliases
      • LDAP and Active Directory integration
        • Configuration
        • Settings table
        • Two-way LDAP and Active Directory synchronization
  • Tutorials
    • Step by step setting up a VPN server
      • Adding additional VPN locations
  • In depth
    • Roadmap
    • Architecture
      • How do VPN statistics work
      • Security concepts
  • For Developers
    • Contributing
    • Environment setup
    • Translations (core/web)
      • Switching language
      • Adding translations
  • Translations (client)
    • Adding translations
  • Contact us
    • Community & Support
Powered by GitBook
On this page
  • Production release (most stable)
  • Pre-release (latest alpha/beta/release candidate)
  • Latest development builds
  • Prerequisites
  • Tools
  • Environment setup
  • Configuration
  • Environment variables
  • CLI options
  • Securing the setup

Was this helpful?

Edit on GitHub
  1. Admin & features
  2. Deploying your instance

One-line install script

PreviousDeploying your instanceNextStandalone package based installation

Last updated 4 months ago

Was this helpful?

The instance deployed by the script is meant to serve as a starting point and makes some tradeoffs to enable automated setup. Most importantly it assumes that your Web UI is available publicly (to generate SSL certificates with Caddy). In general it's not recommended for production and we strongly encourage you to customize this setup to work better within your own infrastructure.

To simplify the setup and enable automated deployment we prepared a script which will deploy a complete defguard instance, including an enrollment proxy and VPN gateway.

Just by launching this one command there will be an interactive configuration and setup that will guide you step by step and deploy full defguard instance based on Docker Compose setup:

Production release (most stable)

curl --proto '=https' --tlsv1.2 -sSf -L https://raw.githubusercontent.com/DefGuard/deployment/main/docker-compose/setup.sh -O && bash setup.sh

Pre-release (latest alpha/beta/release candidate)

curl --proto '=https' --tlsv1.2 -sSf -L https://raw.githubusercontent.com/DefGuard/deployment/main/docker-compose/setup.sh -O && bash setup.sh --pre-release

If you used the install script before and would like to upgrade to the pre-release version, you can update your .env file (it should be located next to the docker-compose.yml file created by the script) like this:

CORE_IMAGE_TAG=pre-release
PROXY_IMAGE_TAG=pre-release
GATEWAY_IMAGE_TAG=pre-release

Downgrading to the production release may not be trivial afterwards because of the changes made to the database during the upgrade.

Latest development builds

curl --proto '=https' --tlsv1.2 -sSf -L https://raw.githubusercontent.com/DefGuard/deployment/main/docker-compose/setup.sh -O && bash setup.sh --dev

If you used the install script before and would like to upgrade to the development version, you can update your .env file (it should be located next to the docker-compose.yml file created by the script) like this:

CORE_IMAGE_TAG=dev
PROXY_IMAGE_TAG=dev
GATEWAY_IMAGE_TAG=dev

Downgrading to the production release may not be trivial afterwards because of the changes made to the database during the upgrade.

If you provide all required configuration options after the script finishes you should have a fully functional defguard instance with an enrollment proxy and VPN gateway to connect WireGuard clients to.

The script does the following:

  • reads configuration from environment variables, .env file or user input

  • prepares a docker-compose file

  • prepares an .env file for the compose stack

  • creates a .volumes directory for persistent storage

  • generates secret keys and certificates

  • sets up an initial VPN location and VPN gateway

  • starts the compose stack

Prerequisites

In order to work the script requires some specific tools to be available and also some infrastructure-level settings to be pre-configured.

Tools

  • bash

  • openssl

  • curl

  • sed

  • grep

  • docker-compose - not necessary if using newer Docker versions (20.10+) which include the docker compose command

Environment setup

This setup should be deployed on a bare-metal or a virtual (VM) server - it will not run on a LXC container.

  • server has a public IP address

  • public DNS records for your chosen domain

  • allow Docker to bind on host ports 80 and 443; sometimes this requires setting the net.ipv4.ip_unprivileged_port_start sysctl variable to 80

  • enable IP forwarding (sysctl -w net.ipv4.ip_forward=1)

  • firewall rules

    • allow incoming traffic on chosen WireGuard port and port 443

    • enable MASQUERADE for VPN traffic (for example iptables -t nat -I POSTROUTING 1 -s {vpn_subnet} -o {internet_interface} -j MASQUERADE)

Configuration

There are several options that can be configured to customize your defguard instance. They can be provided to the script in following ways:

  • by setting environment variables in your shell

  • by providing an .env file in the working directory

  • by running the script manually and setting CLI options

  • by providing user input

Environment variables

  • DEFGUARD_DOMAIN - domain for you defguard web UI (e.g. id.example.com)

  • DEFGUARD_ENROLLMENT_DOMAIN - (optional) domain for the enrollment service; if not set the service will not be deployed

  • DEFGUARD_USE_HTTPS - (optional) set to any value if you want Caddy to generate SSL certificates and use HTTPS

  • DEFGUARD_VPN_NAME- (optional) name of initial VPN location to create; if not provided the script will not set up the VPN gateway

  • DEFGUARD_VPN_IP- (optional if VPN name not set) gateway address within the VPN network (e.g. 10.0.50.1/24)

  • DEFGUARD_VPN_GATEWAY_IP- (optional if VPN name not set) gateway public IP

  • DEFGUARD_VPN_GATEWAY_PORT- (optional if VPN name not set) gateway public port

  • CORE_IMAGE_TAG- (optional) tag to use for defguard Docker image

  • PROXY_IMAGE_TAG- (optional) tag to use for defguard-proxy Docker image

  • GATEWAY_IMAGE_TAG- (optional) tag to use for defguard-gateway Docker image

CLI options

defguard deployment setup script v1.1.0
Copyright (C) 2023 teonite <https://teonite.com>

Usage:  [options]

Available options:

        --help                         this help message
        --non-interactive              run in non-interactive mode (no user input)
        --domain <domain>              domain where defguard web UI will be available
        --enrollment-domain <domain>   domain where enrollment service will be available
        --use-https                    configure reverse proxy to use HTTPS
        --vpn-name <name>              VPN location name
        --vpn-ip <address>             VPN server address & netmask (e.g. 10.0.50.1/24)
        --vpn-gateway-ip <ip>          VPN gateway external IP
        --vpn-gateway-port <port>      VPN gateway external port
        --dev                          use development docker images
        --pre-release                  use pre-release docker images

Securing the setup

After the installation please make sure that only the following ports are open on the server firewall:

  • HTTPS port for the proxy (and/or the defguard core if you want it to be public)

  • VPN server port (eg. WireGuard port)

DO NOT EXPOSE PUBLICLY THE gRPC ports of the core gateway and proxy, which are:

  • 50052

  • 50055

Just copy and paste this command and :

Of course if you feel rightly uneasy about running random shell scripts from the internet feel free to inspect the .

docker - we recommend official (not packages shiped with distros)

Also this setup provides only communication encryption between defguard components, if you additionally like for core/proxy and gateway to have authorization - .

source code
docker engine packages
secure the setup afterwards
please setup a custom SSL CA