Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ngc7331/docker-derper
An unofficial Tailscale Derp server with built-in acme.sh
https://github.com/ngc7331/docker-derper
docker networking self-hosted tailscale
Last synced: 2 days ago
JSON representation
An unofficial Tailscale Derp server with built-in acme.sh
- Host: GitHub
- URL: https://github.com/ngc7331/docker-derper
- Owner: ngc7331
- Created: 2024-02-21T13:20:56.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-01-08T07:25:06.000Z (15 days ago)
- Last Synced: 2025-01-08T08:27:09.656Z (15 days ago)
- Topics: docker, networking, self-hosted, tailscale
- Language: Dockerfile
- Homepage: https://hub.docker.com/r/ngc7331/derper
- Size: 43.9 KB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Docker-derper
An unofficial s6-overlay based Docker image for custom [Tailscale Derp server](https://tailscale.com/kb/1118/custom-derp-servers) with built-in [acme.sh](https://github.com/acmesh-official/acme.sh)
## Usage
```bash
docker run -d --name=derper \
-p 80:80/tcp \ # Optional, see Note 2
-p 443:443/tcp \
-p 3478:3478/udp \ # Optional, see Note 2
-e DERP_HOSTNAME=derp.example.com \
-e DERP_CERTMODE=letsencrypt \
-v /path/to/data:/data:rw \
-v /path/to/cert:/data/cert:rw \ # Optional, see Note 1
-v /var/run/tailscale/tailscaled.sock:/var/run/tailscale/tailscaled.sock:rw \ # Optional, see Note 3
ngc7331/derper:latest
```
Notes:
1. A standalone `/data/cert` mapping is not necessary, but recommended if you want to use the `DERP_CERTMODE=manual`, by which you can provide your own certificate and key files.
2. If you want to disable HTTP or STUN server, you can remove the corresponding port mapping. Also don't forget to set `DERP_ENABLE_HTTP` or `DERP_ENABLE_STUN` to `false`.
3. If `DERP_VERIFY_CLIENTS` is set to true, derp needs to communicate with the tailscale client via `tailscaled.sock` to verify the clients. So you must have a tailscale daemon running on host and mount `tailscaled.sock` inside the container.
### Derp Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `DERP_HOSTNAME` | | The hostname of the Derp server (**MUST BE SET**) |
| `DERP_CERTMODE` | `acme.sh` | The mode of certificate management, should be `letsencrypt`, `acme.sh` or `manual` |
| `DERP_PORT_HTTP` | `80` | The port of HTTP server |
| `DERP_PORT_HTTPS` | `443` | The port of HTTPS server |
| `DERP_PORT_STUN` | `3478` | The port of STUN server |
| `DERP_ENABLE_HTTP` | `true` | Enable HTTP server |
| `DERP_ENABLE_STUN` | `true` | Enable [STUN](https://en.wikipedia.org/wiki/STUN) server |
| `DERP_VERIFY_CLIENTS` | `false` | Verify client certificate, see [official docs](https://tailscale.com/kb/1118/custom-derp-servers#optional-restricting-client-access-to-your-derp-node) |
### Acme.sh Environment Variables
If `DERP_CERTMODE` is set to `acme.sh`, the following environment variables are also required:
| Variable | Default | Description |
|----------|---------|-------------|
| `ACME_SH_EMAIL` | | The email address for ZeroSSL registration |
| `ACME_SH_DNSAPI` | | The API used to pass DNS challenge, see [official docs](https://github.com/acmesh-official/acme.sh/wiki/dnsapi) |
| `ACME_SH_CA` | letsencrypt | The ACME server, see [official docs](https://github.com/acmesh-official/acme.sh/wiki/Server) |
| `ACME_SH_FORCE_RENEW` | `false` | Force renew certificate |
| Other variables required by API | | See [official docs](https://github.com/acmesh-official/acme.sh/wiki/dnsapi) |
Example using Cloudflare:
```bash
docker run ... \
-e DERP_CERTMODE=acme.sh \
-e [email protected] \
-e ACME_SH_DNSAPI=dns_cf \
-e [email protected] \
-e CF_Zone_ID=0123456 \
-e CF_Token=abcdefg \
...
```
Note that `DERP_CERTMODE=acme.sh` can be used only with a DNS API to handle DNS chanllenge automatically.
Use `DERP_CERTMODE=letsencrypt` if you want to use HTTP challenge (as the standalone mode of acme.sh does).
### Unsafe version
In some cases, tls handshake errors/certificate validation failures may be encountered with the default version (e.g. Using a unregistered domain in China mainland, or using a self-signed certificate).
You may want to just skip the certificate validation to make it work. In this case, you can use the `unsafe` version of the image by appending `-unsafe` to the tag (e.g. `docker pull ngc7331/derper:latest-unsafe`).
**NOTE: As the name suggests, this may break the security of the connection and leave it vulnerable to man-in-the-middle attacks. Please use with caution.**
Also, you may set `InsecureForTests` to `true` in your tailscale's ACL rules:
```json
...
"derpMap": {
"Regions": {
"": {
...
"Nodes": [
{
...
"InsecureForTests": true,
},
],
},
},
},
```