refactor docs

hallfay · Oct 4, 2024 · 05fbd2e · 05fbd2e
1 parent f096f6e
commit 05fbd2e
Show file tree

Hide file tree

Showing 11 changed files with 103 additions and 91 deletions.
diff --git a/.github/workflows/build-publish.yml b/.github/workflows/build-publish.yml
@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       GOST_VERSION:
-        description: 'Version of gost. If empty, the latest version will be used.'
+        description: "Version of gost. If empty, the latest version will be used."
         required: false
         type: string
 

diff --git a/Dockerfile b/Dockerfile
@@ -48,6 +48,8 @@ RUN mkdir -p /home/warp/.local/share/warp && \
 ENV GOST_ARGS="-L :1080"
 ENV WARP_SLEEP=2
 ENV REGISTER_WHEN_MDM_EXISTS=
+ENV WARP_LICENSE_KEY=
+ENV BETA_FIX_HOST_CONNECTIVITY=
 
 HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=3 \
   CMD /healthcheck/index.sh

diff --git a/README.md b/README.md
@@ -1,10 +1,8 @@
 # warp-docker
 
 [![Docker Pulls](https://img.shields.io/docker/pulls/caomingjun/warp)](https://hub.docker.com/r/caomingjun/warp)
-![WARP version in latest image](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.caomingjun.com%2Fdockerhub-label%3Frepo%3Dcaomingjun%2Fwarp%26label%3DWARP_VERSION%26display%3DWARP%2520in%2520image
-)
-![GOST version in latest image](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.caomingjun.com%2Fdockerhub-label%3Frepo%3Dcaomingjun%2Fwarp%26label%3DGOST_VERSION%26display%3DGOST%2520in%2520image
-)
+![WARP version in latest image](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.caomingjun.com%2Fdockerhub-label%3Frepo%3Dcaomingjun%2Fwarp%26label%3DWARP_VERSION%26display%3DWARP%2520in%2520image)
+![GOST version in latest image](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.caomingjun.com%2Fdockerhub-label%3Frepo%3Dcaomingjun%2Fwarp%26label%3DGOST_VERSION%26display%3DGOST%2520in%2520image)
 
 Run official [Cloudflare WARP](https://1.1.1.1/) client in Docker.
 
@@ -18,15 +16,15 @@ Run official [Cloudflare WARP](https://1.1.1.1/) client in Docker.
 To run the WARP client in Docker, just write the following content to `docker-compose.yml` and run `docker-compose up -d`.
 
 ```yaml
-version: '3'
+version: "3"
 
 services:
   warp:
     image: caomingjun/warp
     container_name: warp
     restart: always
     ports:
-      - '1080:1080'
+      - "1080:1080"
     environment:
       - WARP_SLEEP=2
       # - WARP_LICENSE_KEY= # optional
@@ -52,79 +50,14 @@ If the output contains `warp=on` or `warp=plus`, the container is working proper
 You can configure the container through the following environment variables:
 
 - `WARP_SLEEP`: The time to wait for the WARP daemon to start, in seconds. The default is 2 seconds. If the time is too short, it may cause the WARP daemon to not start before using the proxy, resulting in the proxy not working properly. If the time is too long, it may cause the container to take too long to start. If your server has poor performance, you can increase this value appropriately.
-
 - `WARP_LICENSE_KEY`: The license key of the WARP client, which is optional. If you have subscribed to WARP+ service, you can fill in the key in this environment variable. If you have not subscribed to WARP+ service, you can ignore this environment variable.
+- `GOST_ARGS`: The arguments passed to GOST. The default is `-L :1080`, which means to listen on port 1080 in the container at the same time through HTTP and SOCKS5 protocols. If you want to have UDP support or use advanced features provided by other protocols, you can modify this parameter. For more information, refer to [GOST documentation](https://v2.gost.run/en/). If you modify the port number, you may also need to modify the port mapping in the `docker-compose.yml`.
+- `REGISTER_WHEN_MDM_EXISTS`: If set, will register consumer account (WARP or WARP+, in contrast to Zero Trust) even when `mdm.xml` exists. You usually don't need this, as `mdm.xml` are usually used for Zero Trust. However, some users may want to adjust advanced settings in `mdm.xml` while still using consumer account.
+- `BETA_FIX_HOST_CONNECTIVITY`: If set, will add checks for host connectivity into healthchecks and automatically fix it if necessary. See [host connectivity issue](docs/host-connectivity.md) for more information.
 
 Data persistence: Use the host volume `./data` to persist the data of the WARP client. You can change the location of this directory or use other types of volumes. If you modify the `WARP_LICENSE_KEY`, please delete the `./data` directory so that the client can detect and register again.
 
-### Change proxy type
-
-The container uses [GOST](https://github.com/ginuerzh/gost) to provide proxy, where the environment variable `GOST_ARGS` is used to pass parameters to GOST. The default is `-L :1080`, that is, to listen on port 1080 in the container at the same time through HTTP and SOCKS5 protocols. If you want to have UDP support or use advanced features provided by other protocols, you can modify this parameter. For more information, refer to [GOST documentation](https://v2.gost.run/en/).
-
-If you modify the port number, you may also need to modify the port mapping in the `docker-compose.yml`.
-
-### Health check
-
-The health check of the container will verify if the WARP client inside the container is working properly. If the check fails, the container will automatically restart. Specifically, 10 seconds after starting, a check will be performed every 15 seconds. If the inspection fails for 3 consecutive times, the container will be marked as unhealthy and trigger an automatic restart.
-
-If `BETA_FIX_HOST_CONNECTIVITY=1` is passed, host connectivity check will be added to the health check. If the check fails, the container will automatically fix it. This may prevent you from accessing certain intranet services of your organization, as the docker network subnet may conflict with the addresses of these services. This is a beta feature and may not work in all cases. If you encounter any issues, please report them.
-
-If you don't want the container to restart automatically, you can remove `restart: always` from the `docker-compose.yml`. You can also modify the parameters of the health check through the `docker-compose.yml`.
-
-### Setting up as WARP connector
-
-If you want to setup [WARP Connector](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/private-net/warp-connector)
-
-> [!NOTE]
-> If you have already started the container, stop it and delete the data directory.
-
-1. Create mdm.xml as explained in Cloudflare WARP Connector [step 4](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/private-net/warp-connector/#4-install-a-warp-connector)
-2. Mount the mdm.xml to path `/var/lib/cloudflare-warp/mdm.xml`
-3. Start the container
-
-<details>
-
-```yaml
-services:
-  warp:
-    image: caomingjun/warp
-    container_name: warp
-    restart: always
-    ports:
-      - '1080:1080'
-    environment:
-      - WARP_SLEEP=2
-      # - WARP_LICENSE_KEY= # optional
-    cap_add:
-      - NET_ADMIN
-    sysctls:
-      - net.ipv6.conf.all.disable_ipv6=0
-      - net.ipv4.conf.all.src_valid_mark=1
-      - net.ipv4.ip_forward=1
-    volumes:
-      - ./data:/var/lib/cloudflare-warp
-      - ./config/warp/mdm.xml:/var/lib/cloudflare-warp/mdm.xml
-```
-
-<summary><i>Sample Docker Compose File</i></summary  >
-</details>
-
-### Use with Cloudflare Zero Trust
-
-If you want to use the WARP client with Cloudflare Zero Trust, just start the container without specifying license key, use `docker exec -it warp bash` to get into the container and follow these steps:
-
-1. `warp-cli registration delete` to delete current registration
-2. `warp-cli teams-enroll <your-team-name>` to enroll the device
-3. Open the link in the output in a browser and follow the instructions to complete the registration
-4. On the success page, right-click and select **View Page Source**.
-5. Find the HTML metadata tag that contains the token. For example, `<meta http-equiv="refresh" content"=0;url=com.cloudflare.warp://acmecorp.cloudflareaccess.com/auth?token=yeooilknmasdlfnlnsadfojDSFJndf_kjnasdf..." />`
-6. Copy the URL field: `com.cloudflare.warp://<your-team-name>.cloudflareaccess.com/auth?token=<your-token>`
-7. In the terminal, run the following command using the URL obtained in the previous step: `warp-cli registration token com.cloudflare.warp://<your-team-name>.cloudflareaccess.com/auth?token=<your-token>`. If you get an API error, then the token has expired. Generate a new one by refreshing the web page and quickly grab the new token from the page source.
-8. `warp-cli connect` to reconnect using new registration.
-9. Wait untill `warp-cli status` shows `Connected`.
-10. Try `curl --socks5-hostname 127.0.0.1:1080 https://cloudflare.com/cdn-cgi/trace` to verify the connection.
-
-This is only needed for the first time. After the device is enrolled, the registration information will be stored in the `./data` directory, if you don't delete them, the container will automatically use the registration information to connect to the WARP service after restart or recreate.
+For advanced usage or configurations, see [documentation](docs/README.md).
 
 ### Use other versions
 
@@ -158,22 +91,20 @@ If you want to build the image locally, you can use [`.github/workflows/build-pu
 
 ### Proxying UDP or even ICMP traffic
 
-The default `GOST_ARGS` is `-L :1080`, which provides HTTP and SOCKS5 proxy. If you want to proxy UDP or even ICMP traffic, you need to change the `GOST_ARGS`. Read the [GOST documentation](https://v2.gost.run/en/) for more information.
+The default `GOST_ARGS` is `-L :1080`, which provides HTTP and SOCKS5 proxy. If you want to proxy UDP or even ICMP traffic, you need to change the `GOST_ARGS`. Read the [GOST documentation](https://v2.gost.run/en/) for more information. If you modify the port number, you may also need to modify the port mapping in the `docker-compose.yml`.
 
 ### How to connect from another container
 
 You may want to use the proxy from another container and find that you cannot connect to `127.0.0.1:1080` in that container. This is because the `docker-compose.yml` only maps the port to the host, not to other containers. To solve this problem, you can use the service name as the hostname, for example, `warp:1080`. You also need to put the two containers in the same docker network.
 
 ### Container runs well but cannot connect from host
 
-This issue often arises when using Zero Trust. You may find that you can run `curl --socks5-hostname 127.0.0.1:1080 https://cloudflare.com/cdn-cgi/trace` inside the container, but cannot run this command outside the container (from host or another container). This is because  Cloudflare WARP client is grabbing the traffic. There are three solutions.
-
-If you have permission to edit the [split tunnel settings](https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/warp/configure-warp/route-traffic/split-tunnels/), you can add the subnet of your docker network to the split tunnel.
+This issue often arises when using Zero Trust. You may find that you can run `curl --socks5-hostname 127.0.0.1:1080 https://cloudflare.com/cdn-cgi/trace` inside the container, but cannot run this command outside the container (from host or another container). This is because Cloudflare WARP client is grabbing the traffic. See [host connectivity issue](docs/host-connectivity.md) for solutions.
 
-If you don't have the permission, use `docker exec warp-test warp-cli --accept-tos tunnel dump` to list your current excluded subnets, and carefully select one of them to set as the docker network subnet. The subnet you choose should be within the [private address range](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_addresses); using a public address will prevent you from accessing certain services properly. This solution can be quite brittle and manual as you may need to change the subnet when your organization changes the excluded subnets, but it won't cause any other problems.
+### How to enable MASQUE / use with Zero Trust / set up WARP Connector / change health check parameters
 
-The third solution is to pass environment variable `BETA_FIX_HOST_CONNECTIVITY=1` to container, the container will add checks for host connectivity into healthchecks and automatically fix it if necessary. **This may prevent you from accessing certain intranet services of your organization**, as the docker network subnet may conflict with the addresses of these services. This is a beta feature and may not work in all cases. If you encounter any issues, please report them.
+See [documentation](docs/README.md).
 
 ## Further reading
 
-Read in my [blog post](https://blog.caomingjun.com/run-cloudflare-warp-in-docker/en/#How-it-works).
+For how it works, read my [blog post](https://blog.caomingjun.com/run-cloudflare-warp-in-docker/en/#How-it-works).
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -1,15 +1,14 @@
-version: '3'
+version: "3"
 
 services:
   warp:
     image: caomingjun/warp
     container_name: warp
     restart: always
     ports:
-      - '1080:1080'
+      - "1080:1080"
     environment:
       - WARP_SLEEP=2
-      # - REGISTER_WHEN_MDM_EXISTS=true
       # - WARP_LICENSE_KEY= # optional
     cap_add:
       - NET_ADMIN
@@ -18,4 +17,3 @@ services:
       - net.ipv4.conf.all.src_valid_mark=1
     volumes:
       - ./data:/var/lib/cloudflare-warp
-      # - ./enable_masque_mdm.xml:/var/lib/cloudflare-warp/mdm.xml
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,9 @@
+# Documentation
+
+This directory contains advanced usage and configurations of the project. Below is a brief introduction to each document:
+
+- [healthcheck.md](healthcheck.md): Describes the health check mechanism for the container and its configuration.
+- [host-connectivity.md](host-connectivity.md): Discusses potential host connectivity issue when using Zero Trust and provides three solutions.
+- [warp-connector.md](warp-connector.md): Provides steps and a sample Docker Compose file for setting up the WARP Connector.
+- [zero-trust.md](zero-trust.md): Details the steps to use the WARP client with Cloudflare Zero Trust.
+- [masque.md](masque.md): Describes how to enable MASQUE, WARP's new protocol.
diff --git a/docs/healthcheck.md b/docs/healthcheck.md
@@ -0,0 +1,7 @@
+# Health check
+
+The health check of the container will verify if the WARP client inside the container is working properly. If the check fails, the container will automatically restart. Specifically, 10 seconds after starting, a check will be performed every 15 seconds. If the inspection fails for 3 consecutive times, the container will be marked as unhealthy and trigger an automatic restart.
+
+By default, the health check only checks if the WARP client is running. Sometime you may face a [host connectivity issue](host-connectivity.md), which is not covered by the default health check. If `BETA_FIX_HOST_CONNECTIVITY=1` is passed, host connectivity check will be added to the health check. If the check fails, the container will automatically fix it. This may prevent you from accessing certain intranet services of your organization, as the docker network subnet may conflict with the addresses of these services. This is a beta feature and may not work in all cases. If you encounter any issues, please report them.
+
+If you don't want the container to restart automatically, you can remove `restart: always` from the `docker-compose.yml`. You can also modify the parameters of the health check through the `docker-compose.yml`.
diff --git a/docs/host-connectivity.md b/docs/host-connectivity.md
@@ -0,0 +1,9 @@
+# Host connectivity issue
+
+This issue often arises when using Zero Trust. You may find that you can run `curl --socks5-hostname 127.0.0.1:1080 https://cloudflare.com/cdn-cgi/trace` inside the container, but cannot run this command outside the container (from host or another container). This is because Cloudflare WARP client is grabbing the traffic. There are three solutions.
+
+If you have permission to edit the [split tunnel settings](https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/warp/configure-warp/route-traffic/split-tunnels/), you can add the subnet of your docker network to the split tunnel.
+
+If you don't have the permission, use `docker exec warp-test warp-cli --accept-tos tunnel dump` to list your current excluded subnets, and carefully select one of them to set as the docker network subnet. The subnet you choose should be within the [private address range](https://en.wikipedia.org/wiki/Private_network#Private_IPv4_addresses); using a public address will prevent you from accessing certain services properly. This solution can be quite brittle and manual as you may need to change the subnet when your organization changes the excluded subnets, but it won't cause any other problems.
+
+The third solution is to pass environment variable `BETA_FIX_HOST_CONNECTIVITY=1` to container, the container will add checks for host connectivity into [healthchecks](healthcheck.md) and automatically fix it if necessary. **This may prevent you from accessing certain intranet services of your organization**, as the docker network subnet may conflict with the addresses of these services. This is a beta feature and may not work in all cases. If you encounter any issues, please report them.
diff --git a/docs/masque.md b/docs/masque.md
@@ -0,0 +1,11 @@
+# Enable MASQUE
+
+[MASQUE](https://blog.cloudflare.com/zero-trust-warp-with-a-masque/) is WARP's new protocol which is more unlikely to be block by firewall (of your company or ISP) than WireGuard.
+
+If you are using Zero Trust, go to Cloudflare Zero Trust portal and set [device tunnel protocol](https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/warp/configure-warp/warp-settings/#device-tunnel-protocol) to MASQUE.
+
+If you are using consumer account, you can enable MASQUE by following the steps below:
+
+1. run `docker exec -it warp bash` to get into the container shell
+2. run `warp-cli tunnel protocol set MASQUE` to enable MASQUE
+3. run `warp-cli settings list` to check if MASQUE is enabled
diff --git a/docs/warp-connector.md b/docs/warp-connector.md
@@ -0,0 +1,33 @@
+# Setting up as WARP connector
+
+If you want to setup [WARP Connector](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/private-net/warp-connector)
+
+> [!NOTE]
+> If you have already started the container, stop it and delete the data directory.
+
+1. Create `mdm.xml` as explained in Cloudflare WARP Connector [step 4](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/private-net/warp-connector/#4-install-a-warp-connector)
+2. Mount the `mdm.xml` to path `/var/lib/cloudflare-warp/mdm.xml`
+3. Start the container
+
+Sample Docker Compose File:
+
+```yaml
+services:
+  warp:
+    image: caomingjun/warp
+    container_name: warp
+    restart: always
+    ports:
+      - "1080:1080"
+    environment:
+      - WARP_SLEEP=2
+    cap_add:
+      - NET_ADMIN
+    sysctls:
+      - net.ipv6.conf.all.disable_ipv6=0
+      - net.ipv4.conf.all.src_valid_mark=1
+      - net.ipv4.ip_forward=1
+    volumes:
+      - ./data:/var/lib/cloudflare-warp
+      - ./config/warp/mdm.xml:/var/lib/cloudflare-warp/mdm.xml
+```