Merge pull request #624 from openziti/refine-zrok-instance

make caddy tls optional

docker/compose/zrok-instance/.gitignore

@@ -1,2 +1 @@
-/.env
-/compose.yml
+/.env

docker/compose/zrok-instance/Caddyfile

@@ -1,5 +1,5 @@
 {
-	email {$CADDY_ACME_EMAIL}
+	email {$ZROK_USER_EMAIL}
 	acme_ca {$CADDY_ACME_API}
 	admin 0.0.0.0:2019
 }

docker/compose/zrok-instance/README.md

@@ -1,20 +1,25 @@
 
 ## Docker Instance
 
-<iframe width="100%" height="315" src="https://www.youtube.com/embed/zoWmTzTa1cg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+<iframe width="100%" height="315" src="https://www.youtube.com/embed/70zJ_h4uiD8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+
+This Docker Compose project creates a zrok instance and includes a ziti controller and router. An optional Caddy container is included to provide HTTPS and reverse proxy services for the zrok API and public shares.
 
 ### DNS Configuration
 
-The Compose project makes these assumptions about your global DNS configuration.
-
-1. A Caddy DNS plugin is available for your DNS provider (see [github.com/caddy-dns](https://github.com/orgs/caddy-dns/repositories?type=all&q=sort%3Aname-asc))
-1. You have designated A DNS zone for zrok, e.g. `example.com` or `share.example.com` and created (and delegated, if necessary) the zone on your DNS provider's platform.
 1. A wildcard record exists for the IP address where the zrok instance will run, e.g. if your DNS zone is `share.example.com`, then your wildcard record is `*.share.example.com`.
-1. You have created an API token in your DNS provider's platform and the token has permission to create DNS records in the DNS zone.
+
+#### Additional DNS Configuration for Caddy TLS
+
+The included Caddy container can automatically manage a wildcard certificate for your zrok instance. You can enable Caddy in this compose project by renaming `caddy.compose.override.yml` as `compose.override.yml`.
+
+1. Ensure A Caddy DNS plugin is available for your DNS provider (see [github.com/caddy-dns](https://github.com/orgs/caddy-dns/repositories?type=all&q=sort%3Aname-asc)).
+1. Designate A DNS zone for zrok, e.g. `example.com` or `share.example.com` and create the zone on your DNS provider's platform.
+1. Created an API token in your DNS provider that has permission to manage zrok's DNS zone.
 
 ### Create the Docker Compose Project
 
-Create a working directory on your Docker host and save these Docker Compose project files. A OpenZiti network is provided by the "ziti-quickstart" container and is managed exclusively by zrok.
+Create a working directory on your Docker host and save these Docker Compose project files.
 
 #### Shortcut Option
 
@@ -51,17 +56,26 @@ Create an `.env` file in the working directory.
 ```bash title=".env required"
 ZROK_DNS_ZONE=share.example.com
 
-CADDY_DNS_PLUGIN=cloudflare
-CADDY_DNS_PLUGIN_TOKEN=abcd1234
-CADDY_ACME_EMAIL=me@example.com
+ZROK_USER_EMAIL=me@example.com
+ZROK_USER_PWD=zrokuserpw
 
 ZITI_PWD=zitiadminpw
-
 ZROK_ADMIN_TOKEN=zroktoken
-ZROK_USER_PWD=zrokuserpw
 ```
 
 ```bash title=".env options"
+# plugin name for your DNS provider
+CADDY_DNS_PLUGIN=cloudflare
+# API token from your DNS provider
+CADDY_DNS_PLUGIN_TOKEN=abcd1234
+# use the staging API until you're sure everything is working to avoid hitting the rate limit
+CADDY_ACME_API=https://acme-staging-v02.api.letsencrypt.org/directory
+
+# zrok version, e.g., 1.0.0
+ZROK_IMAGE_TAG=latest
+
+# ziti version, e.g., 1.0.0
+ZITI_IMAGE_TAG=latest
 # ziti ports
 ZITI_CTRL_ADVERTISED_PORT=1280
 ZITI_ROUTER_PORT=3022
@@ -72,9 +86,6 @@ ZROK_OAUTH_GITHUB_CLIENT_ID=abcd1234
 ZROK_OAUTH_GITHUB_CLIENT_SECRET=abcd1234
 ZROK_OAUTH_GOOGLE_CLIENT_ID=abcd1234
 ZROK_OAUTH_GOOGLE_CLIENT_SECRET=abcd1234
-
-# use the staging API until you're sure everything is working to avoid hitting the main CA's rate limit
-CADDY_ACME_API=https://acme-staging-v02.api.letsencrypt.org/directory
 ```
 
 ### Start the Docker Compose Project
@@ -89,10 +100,10 @@ CADDY_ACME_API=https://acme-staging-v02.api.letsencrypt.org/directory
 
 ### Set up a User Account
 
-This step creates a user account. You will log in to the zrok web console with the account password created in this step. The CADDY_ACME_EMAIL and ZROK_USER_PWD variables are set in the `.env` file. You can create more user accounts the same way by substituting a different email and password.
+This step creates a user account. You will log in to the zrok web console with the account password created in this step. The ZROK_USER_EMAIL and ZROK_USER_PWD variables are set in the `.env` file. You can create more user accounts the same way by substituting a different email and password.
 
-```bash
-docker compose exec zrok-controller bash -xc 'zrok admin create account /etc/zrok-controller/config.yml ${CADDY_ACME_EMAIL} ${ZROK_USER_PWD}'
+```bash title="Create the first user account"
+docker compose exec zrok-controller bash -xc 'zrok admin create account /etc/zrok-controller/config.yml ${ZROK_USER_EMAIL} ${ZROK_USER_PWD}'
 ```
 
 ```buttonless title="Example output"
@@ -102,6 +113,12 @@ docker compose exec zrok-controller bash -xc 'zrok admin create account /etc/zro
 heMqncCyxZcx
 ```
 
+Create additional users by running the command again with a different email and password.
+
+```bash title="Create another user"
+docker compose exec zrok-controller zrok admin create account /etc/zrok-controller/config.yml <email> <password>
+```
+
 ### Enable the User Environment
 
 You must enable each device environment with the account token obtained when the account was created. This is separate from the account password that's used to log in to the web console.
@@ -114,6 +131,12 @@ Follow [the getting started guide](/docs/getting-started#installing-the-zrok-com
     zrok config set apiEndpoint https://zrok.share.example.com
     ```
 
+    or, if not using Caddy for TLS:
+
+    ```bash
+    zrok config set apiEndpoint http://zrok.share.example.com:18080
+    ```
+
 1. Enable an environment on this device with the account token from the previous step.
 
     ```bash

docker/compose/zrok-instance/bootstrap-frontend.bash

@@ -106,11 +106,11 @@ if [[ -n "${ZROK_PUBLIC_TOKEN}" ]]; then
 
     echo "INFO: updating frontend"
     zrok admin update frontend "${ZROK_PUBLIC_TOKEN}" \
-        --url-template "https://{token}.${ZROK_DNS_ZONE}"
+        --url-template "${ZROK_FRONTEND_SCHEME}://{token}.${ZROK_DNS_ZONE}:${ZROK_FRONTEND_PORT}"
 else
     echo "INFO: creating frontend"
     zrok admin create frontend "${ZITI_PUBLIC_ID}" public \
-        "https://{token}.${ZROK_DNS_ZONE}"
+        "${ZROK_FRONTEND_SCHEME}://{token}.${ZROK_DNS_ZONE}:${ZROK_FRONTEND_PORT}"
 fi
 
 exec "${@}"

docker/compose/zrok-instance/caddy.compose.override.yml

@@ -0,0 +1,41 @@
+# delete this file from your compose project if you do not want to use Caddy for TLS termination
+services:
+  caddy:
+    build:
+      context: .
+      dockerfile: ./caddy.Dockerfile
+      args:
+        CADDY_DNS_PLUGIN: ${CADDY_DNS_PLUGIN} # e.g., "digitalocean" (see github.com/caddy-dns)
+    restart: unless-stopped
+    environment:
+      CADDY_DNS_PLUGIN: ${CADDY_DNS_PLUGIN}  # e.g., "digitalocean" (see github.com/caddy-dns)
+      CADDY_DNS_PLUGIN_TOKEN: ${CADDY_DNS_PLUGIN_TOKEN}  # API token from DNS provider used by plugin to solve the ACME challenge
+      ZROK_USER_EMAIL: ${ZROK_USER_EMAIL}  # email address sent to CA for ACME account and renewal notifications
+      CADDY_ACME_API: ${CADDY_ACME_API:-https://acme-v02.api.letsencrypt.org/directory}  # ACME API endpoint
+      ZROK_DNS_ZONE: ${ZROK_DNS_ZONE}  # e.g., "example.com" or "127.0.0.1.sslip.io"
+      ZROK_CTRL_PORT: ${ZROK_CTRL_PORT:-18080}
+      ZROK_FRONTEND_PORT: ${ZROK_FRONTEND_PORT:-8080}
+      ZROK_OAUTH_PORT: ${ZROK_OAUTH_PORT:-8081}
+    expose:
+      - 80/tcp
+      - 443/tcp
+      - 443/udp   # Caddy's HTTP/3 (QUIC) (not published)
+      - 2019/tcp  # Caddy's admin API     (not published)
+    ports:
+      - ${CADDY_INTERFACE:-0.0.0.0}:80:80
+      - ${CADDY_INTERFACE:-0.0.0.0}:443:443
+      # - ${CADDY_INTERFACE:-0.0.0.0}:443:443/udp"  # future: HTTP/3 (QUIC)
+    volumes:
+      - caddy_data:/data
+      - caddy_config:/config
+    networks:
+      zrok-instance:
+  
+  zrok-frontend:
+    environment:
+      ZROK_FRONTEND_SCHEME: https
+      ZROK_FRONTEND_PORT: 443
+
+volumes:
+  caddy_data:
+  caddy_config:

docker/compose/zrok-instance/compose.yml

@@ -1,5 +1,3 @@
-# this compose file is designed to merge with the ziti all-in-one quickstart compose file by renaming 
-# https://get.openziti.io/dock/all-in-one/compose.yml to compose.override.yml
 
 services:
   ziti-quickstart:
@@ -111,12 +109,11 @@ services:
     restart: unless-stopped
     expose:
       - ${ZROK_CTRL_PORT:-18080}  # (not published)
-    # Caddy's published ports provide a TLS reverse proxy for the zrok controller
-    # ports:
-    #   - 127.0.0.1:${ZROK_CTRL_PORT:-18080}:${ZROK_CTRL_PORT:-18080}
+    ports:
+      - 127.0.0.1:${ZROK_CTRL_PORT:-18080}:${ZROK_CTRL_PORT:-18080}
     environment:
       ZROK_USER_PWD: ${ZROK_USER_PWD} # admin account password     (initial user account)
-      CADDY_ACME_EMAIL: ${CADDY_ACME_EMAIL}  # login email address (initial user account)
+      ZROK_USER_EMAIL: ${ZROK_USER_EMAIL}  # login email address (initial user account)
 
   zrok-frontend:
     depends_on:
@@ -146,54 +143,23 @@ services:
     expose:
       - ${ZROK_FRONTEND_PORT:-8080}  # (not published)
       - ${ZROK_OAUTH_PORT:-8081}     # (not published)
-    # ports:
-    #   - 127.0.0.1:${ZROK_FRONTEND_PORT:-8080}:${ZROK_FRONTEND_PORT:-8080}
-    #   - 127.0.0.1:${ZROK_OAUTH_PORT:-8081}:${ZROK_OAUTH_PORT:-8081}
+    ports:
+      - 127.0.0.1:${ZROK_FRONTEND_PORT:-8080}:${ZROK_FRONTEND_PORT:-8080}
+      - 127.0.0.1:${ZROK_OAUTH_PORT:-8081}:${ZROK_OAUTH_PORT:-8081}
     environment:
       HOME: /var/lib/zrok-frontend
       ZROK_DNS_ZONE: ${ZROK_DNS_ZONE}  # e.g., "example.com" or "127.0.0.1.sslip.io"
       ZROK_ADMIN_TOKEN: ${ZROK_ADMIN_TOKEN} # zrok controller admin password
       ZROK_API_ENDPOINT: http://zrok-controller:${ZROK_CTRL_PORT:-18080} # bridge address of the zrok controller
+      ZROK_FRONTEND_SCHEME: http
+      ZROK_FRONTEND_PORT: ${ZROK_FRONTEND_PORT:-8080}
       ZITI_CTRL_ADVERTISED_PORT: ${ZITI_CTRL_ADVERTISED_PORT:-1280}
       ZITI_PWD: ${ZITI_PWD} # ziti controller admin password
 
-  caddy:
-    build:
-      context: .
-      dockerfile: ./caddy.Dockerfile
-      args:
-        CADDY_DNS_PLUGIN: ${CADDY_DNS_PLUGIN} # e.g., "digitalocean" (see github.com/caddy-dns)
-    restart: unless-stopped
-    environment:
-      CADDY_DNS_PLUGIN: ${CADDY_DNS_PLUGIN}  # e.g., "digitalocean" (see github.com/caddy-dns)
-      CADDY_DNS_PLUGIN_TOKEN: ${CADDY_DNS_PLUGIN_TOKEN}  # API token from DNS provider used by plugin to solve the ACME challenge
-      CADDY_ACME_EMAIL: ${CADDY_ACME_EMAIL}  # email address sent to CA for ACME account and renewal notifications
-      CADDY_ACME_API: ${CADDY_ACME_API:-https://acme-v02.api.letsencrypt.org/directory}  # ACME API endpoint
-      ZROK_DNS_ZONE: ${ZROK_DNS_ZONE}  # e.g., "example.com" or "127.0.0.1.sslip.io"
-      ZROK_CTRL_PORT: ${ZROK_CTRL_PORT:-18080}
-      ZROK_FRONTEND_PORT: ${ZROK_FRONTEND_PORT:-8080}
-      ZROK_OAUTH_PORT: ${ZROK_OAUTH_PORT:-8081}
-    expose:
-      - 80/tcp
-      - 443/tcp
-      - 443/udp   # Caddy's HTTP/3 (QUIC) (not published)
-      - 2019/tcp  # Caddy's admin API     (not published)
-    ports:
-      - ${CADDY_INTERFACE:-0.0.0.0}:80:80
-      - ${CADDY_INTERFACE:-0.0.0.0}:443:443
-      # - ${CADDY_INTERFACE:-0.0.0.0}:443:443/udp"  # future: HTTP/3 (QUIC)
-    volumes:
-      - caddy_data:/data
-      - caddy_config:/config
-    networks:
-      zrok-instance:
-
 volumes:
   ziti_home:  # this will not be used if you switch from named volume to bind mount volume
   zrok_ctrl:
   zrok_frontend:
-  caddy_data:
-  caddy_config:
 
 # define a custom network so that we can also define DNS aliases
 networks:

docker/compose/zrok-private-access/.gitignore

@@ -0,0 +1,2 @@
+.env
+/compose.override.yml

docker/compose/zrok-private-share/.gitignore

@@ -0,0 +1,2 @@
+.env
+/compose.override.yml

docker/compose/zrok-public-share/.gitignore

@@ -0,0 +1,2 @@
+.env
+*compose.override.yml