From 3050a2ccbb4fc90a5664530fbddbc88217ad7118 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Mon, 13 May 2024 10:41:04 -0400 Subject: [PATCH 1/2] stop ignoring the same files for all compose projects --- docker/compose/zrok-instance/.gitignore | 3 +-- docker/compose/zrok-private-access/.gitignore | 2 ++ docker/compose/zrok-private-share/.gitignore | 2 ++ docker/compose/{ => zrok-public-reserved}/.gitignore | 0 docker/compose/zrok-public-share/.gitignore | 2 ++ 5 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 docker/compose/zrok-private-access/.gitignore create mode 100644 docker/compose/zrok-private-share/.gitignore rename docker/compose/{ => zrok-public-reserved}/.gitignore (100%) create mode 100644 docker/compose/zrok-public-share/.gitignore diff --git a/docker/compose/zrok-instance/.gitignore b/docker/compose/zrok-instance/.gitignore index 7ee12f8c..4cb512ec 100644 --- a/docker/compose/zrok-instance/.gitignore +++ b/docker/compose/zrok-instance/.gitignore @@ -1,2 +1 @@ -/.env -/compose.yml \ No newline at end of file +/.env \ No newline at end of file diff --git a/docker/compose/zrok-private-access/.gitignore b/docker/compose/zrok-private-access/.gitignore new file mode 100644 index 00000000..2c7d667a --- /dev/null +++ b/docker/compose/zrok-private-access/.gitignore @@ -0,0 +1,2 @@ +.env +/compose.override.yml \ No newline at end of file diff --git a/docker/compose/zrok-private-share/.gitignore b/docker/compose/zrok-private-share/.gitignore new file mode 100644 index 00000000..2c7d667a --- /dev/null +++ b/docker/compose/zrok-private-share/.gitignore @@ -0,0 +1,2 @@ +.env +/compose.override.yml \ No newline at end of file diff --git a/docker/compose/.gitignore b/docker/compose/zrok-public-reserved/.gitignore similarity index 100% rename from docker/compose/.gitignore rename to docker/compose/zrok-public-reserved/.gitignore diff --git a/docker/compose/zrok-public-share/.gitignore b/docker/compose/zrok-public-share/.gitignore new file mode 100644 index 00000000..f19fff7f --- /dev/null +++ b/docker/compose/zrok-public-share/.gitignore @@ -0,0 +1,2 @@ +.env +*compose.override.yml \ No newline at end of file From d968d2d068d75393fca59160ebb322bbd83794e0 Mon Sep 17 00:00:00 2001 From: Kenneth Bingham Date: Mon, 13 May 2024 14:44:35 -0400 Subject: [PATCH 2/2] make caddy optional --- docker/compose/zrok-instance/Caddyfile | 2 +- docker/compose/zrok-instance/README.md | 59 +++++++++++++------ .../zrok-instance/bootstrap-frontend.bash | 4 +- .../zrok-instance/caddy.compose.override.yml | 41 +++++++++++++ docker/compose/zrok-instance/compose.yml | 50 +++------------- 5 files changed, 93 insertions(+), 63 deletions(-) create mode 100644 docker/compose/zrok-instance/caddy.compose.override.yml diff --git a/docker/compose/zrok-instance/Caddyfile b/docker/compose/zrok-instance/Caddyfile index f91a559c..0e9a913f 100644 --- a/docker/compose/zrok-instance/Caddyfile +++ b/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 } diff --git a/docker/compose/zrok-instance/README.md b/docker/compose/zrok-instance/README.md index 48cb5849..bc7131b2 100644 --- a/docker/compose/zrok-instance/README.md +++ b/docker/compose/zrok-instance/README.md @@ -1,20 +1,25 @@ ## Docker Instance - + + +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 +``` + ### 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 diff --git a/docker/compose/zrok-instance/bootstrap-frontend.bash b/docker/compose/zrok-instance/bootstrap-frontend.bash index 57dbcd6d..2341db11 100755 --- a/docker/compose/zrok-instance/bootstrap-frontend.bash +++ b/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 "${@}" diff --git a/docker/compose/zrok-instance/caddy.compose.override.yml b/docker/compose/zrok-instance/caddy.compose.override.yml new file mode 100644 index 00000000..9423485a --- /dev/null +++ b/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: diff --git a/docker/compose/zrok-instance/compose.yml b/docker/compose/zrok-instance/compose.yml index bd69780b..eb7ae970 100644 --- a/docker/compose/zrok-instance/compose.yml +++ b/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: