<!-- # build:1  -->
## ToDo

* [ ] Develop a more robust integration system for complex network setups. [Not planned]
* [ ] Enhance logging and monitoring capabilities for better observability. []
* [ ] Explore security enhancements and vulnerability checks.

## Disclaimer 

Headscale, as a self-hosted control server, does not inherently solve all network security challenges. It's intended to simplify the management of Tailscale nodes within a private network. Network administrators should still apply best practices for security and monitor their network's activity.

## Considerations

Running Headscale as a Docker container provides certain advantages, such as ease of deployment and isolation. However, as with any network component, it should be deployed carefully within the context of your network's security architecture.

# Usage
First, create a directory for the Headscale container configuration:

```bash
mkdir -p ./headscale/
```

Then, edit the Docker Compose file:

```bash
nano ./headscale/docker-compose.yml
```

## Environment Variables and Defaults

| Variable                | Description                            | Default Value                   |
|-------------------------|----------------------------------------|---------------------------------|
| `SERVER_URL`            | URL that clients will connect to       | `http://127.0.0.1:8080`         |
| `LISTEN_ADDR`           | Address for the server to listen on    | `127.0.0.1:8080`                |
| `METRICS_LISTEN_ADDR`   | Address for listening to metrics       | `127.0.0.1:9090`                |
| `GRPC_LISTEN_ADDR`      | Address for listening for gRPC         | `127.0.0.1:50443`               |
| `DB_TYPE`               | Type of database to use                | `sqlite3`                       |
| `DB_PATH`               | Path to the database file              | `/var/lib/headscale/db.sqlite`  |

#### Extended Variables and Defaults

| Variable Name                  | Description                                          | Example Value                           |
| ------------------------------ | ---------------------------------------------------- | --------------------------------------- |
| `SERVER_URL`                   | The URL that clients will connect to                 | `http://127.0.0.1:8080`                 |
| `LISTEN_ADDR`                  | Address for the server to listen on                  | `127.0.0.1:8080`                        |
| `METRICS_LISTEN_ADDR`          | Address for listening to metrics                     | `127.0.0.1:9090`                        |
| `GRPC_LISTEN_ADDR`             | Address for listening for gRPC                       | `127.0.0.1:50443`                       |
| `GRPC_ALLOW_INSECURE`          | Allow gRPC to run in INSECURE mode                   | `false`                                 |
| `NOISE_PRIVATE_KEY_PATH`       | Path to the Noise private key                        | `/var/lib/headscale/noise_private.key`  |
| `IP_PREFIXES`                  | List of IP prefixes to allocate tailaddresses from   | `["fd7a:115c:a1e0::/48", "100.64.0.0/10"]` |
| `DERP_ENABLED`                 | Whether to enable DERP server                        | `false`                                 |
| `DERP_REGION_ID`               | Region ID for the DERP server                        | `999`                                   |
| `DERP_STUN_LISTEN_ADDR`        | Address for the DERP STUN server to listen on        | `0.0.0.0:3478`                          |
| `DERP_PRIVATE_KEY_PATH`        | Path to the DERP server private key                  | `/var/lib/headscale/derp_server_private.key` |
| `ACME_URL`                     | URL to ACME directory for Let's Encrypt              | `https://acme-v02.api.letsencrypt.org/directory` |
| `ACME_EMAIL`                   | Email to register with ACME provider                 | `example@email.com`                     |
| `TLS_LETSENCRYPT_HOSTNAME`     | Domain name for TLS certificate                      | `mydomain.com`                          |
| `TLS_LETSENCRYPT_CACHE_DIR`    | Path to store certificates and metadata for Let's Encrypt | `/var/lib/headscale/cache`           |
| `DB_TYPE`                      | Database type (e.g., sqlite3, postgres)              | `sqlite3`                               |
| `DB_PATH`                      | Path to the database file (for sqlite3)              | `/var/lib/headscale/db.sqlite`          |

To use these variables in your `config-example.yaml`, you would format them like this:

```yaml
server_url: ${SERVER_URL}
listen_addr: ${LISTEN_ADDR}
metrics_listen_addr: ${METRICS_LISTEN_ADDR}
...
```

### Note:
These variables can be customized to fit your network setup. Ensure that they align with your network's configuration and security policies.

## docker-compose.yml

```yaml
version: '3.8'

services:
  headscale:
    image: headscale/headscale:latest
    volumes:
      - ./headscale/config:/etc/headscaled
    environment:
      - SERVER_URL=${SERVER_URL}
      - LISTEN_ADDR=${LISTEN_ADDR}
      - METRICS_LISTEN_ADDR=${METRICS_LISTEN_ADDR}
      - GRPC_LISTEN_ADDR=${GRPC_LISTEN_ADDR}
      - DB_TYPE=${DB_TYPE}
      - DB_PATH=${DB_PATH}
```

### Notes:

- Customize the environment variables in the `docker-compose.yml` file as needed.
- You may need to adjust port mappings based on your specific network setup.
- Ensure that the Headscale container's configuration aligns with your security policies and network architecture.