# Docker Installation

Source: https://docs.netbird.io/get-started/install/docker

---

# Docker Installation

The NetBird client (agent) allows a peer to join a pre-existing NetBird deployment. If a NetBird deployment is not yet available, there are both managed and [self-hosted](https://docs.netbird.io/selfhosted/selfhosted-quickstart) options available.

## Docker Run Command

Set the ```NB_SETUP_KEY``` environment variable and run the command.

> **Note:** You can pass other settings as environment variables. See [Environment variables](/get-started/cli#environment-variables) for details.

NetBird makes use of eBPF and raw sockets, therefore to guarantee the client software functionality, we recommend adding the flags `--cap-add=SYS_ADMIN` and `--cap-add=SYS_RESOURCE` for docker clients.
The experience may vary depending on the docker daemon, operating system, or kernel version.

```bash
docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN --cap-add=SYS_ADMIN --cap-add=SYS_RESOURCE -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/var/lib/netbird netbirdio/netbird:latest
```

See [Docker example](/use-cases/examples#net-bird-client-in-docker) for details.

### IPv6 overlay

If you are using [IPv6 overlay addressing](/manage/settings/ipv6) and the container is not running with `--network=host`, add the IPv6 sysctls so the kernel forwards v6 traffic inside the container:

```bash
docker run ... \
  --sysctl net.ipv6.conf.all.disable_ipv6=0 \
  --sysctl net.ipv6.conf.all.forwarding=1 \
  netbirdio/netbird:latest
```

Or in Docker Compose:

```yaml
services:
  netbird-client:
      sysctls:
          - net.ipv6.conf.all.disable_ipv6=0
          - net.ipv6.conf.all.forwarding=1
```

With `network_mode: host` the container inherits the host's sysctls, so the flags can be dropped as long as the host has IPv6 forwarding enabled.

### Troubleshooting
1. If you are using self-hosted version and haven't specified `--management-url`, the client app will use the default URL
which is ```https://api.netbird.io:443```.

2. If you have specified a wrong `--management-url` (e.g., just by mistake when self-hosting)
to override it you can do the following:

```bash
netbird down
netbird up --management-url https://<CORRECT HOST:PORT>/
```

To override it see the solution #1 above.

## Docker Compose
If you prefer to run NetBird as a Docker compose stack below is an example. Configure to your specific needs.
```yaml
services:
  netbird-client:
      container_name: netbird-client
      hostname: <HOSTNAME>
      cap_add:
          - NET_ADMIN
          - SYS_ADMIN
          - SYS_RESOURCE
      devices:
          # Required when using userspace mode or when kernel module is not available
          - /dev/net/tun
      network_mode: host
      environment:
          - NB_SETUP_KEY=<SETUP KEY>
      volumes:
          - netbird-client:/var/lib/netbird
      image: netbirdio/netbird:latest
volumes:
  netbird-client:
      name: netbird-client
```

## Running NetBird with a Setup Key
In case you are activating a server peer, you can use a [setup key](/manage/peers/register-machines-using-setup-keys) as described in the steps below.
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.

1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/manage/peers/register-machines-using-setup-keys)).

```bash
docker run --network host --privileged --rm -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/var/lib/netbird netbirdio/netbird:<TAG>
```

You could also omit the `--setup-key` property. In this case, the tool will prompt for the key.

2. Check connection status:
```bash
  netbird status
```

3. Check your IP:

````bash
  sudo ifconfig utun100
````

## Rootless Image

In some cases you may want to run our [rootless image](https://hub.docker.com/layers/netbirdio/netbird/rootless-latest). Rootless mode operates within a user namespace, reducing the attack surface compared to standard rootful Docker. The rootless mode leverages netstack from the gVisor Go package, enabling the WireGuard stack to run entirely in userspace, circumventing the need for kernel-level access.

```bash
docker run --rm --name PEER_NAME --hostname PEER_NAME -d \
    -e NB_SETUP_KEY=<YOUR_SETUP_KEY> \
    -v netbird-client:/var/lib/netbird \
    netbirdio/netbird:rootless-latest
```

`rootless` is well supported and works without any privileges. However, it will only be useful for inbound access or as routing peer (no outbound connections except via socks proxy)