Merge pull request #247 from openziti/docker-share

docker share, docker access

.github/workflows/publish-docker-images.yml

@@ -87,11 +87,11 @@ jobs:
         with:
           builder: ${{ steps.buildx.outputs.name }}
           context: ${{ github.workspace }}/
-          file: ${{ github.workspace }}/docker-images/zrok/Dockerfile
+          file: ${{ github.workspace }}/docker/images/zrok/Dockerfile
           platforms: linux/amd64,linux/arm64
           tags: ${{ steps.tagprep_cli.outputs.DOCKER_TAGS }}
           build-args: |
-            DOCKER_BUILD_DIR=./docker-images/zrok
+            DOCKER_BUILD_DIR=./docker/images/zrok
             ARTIFACTS_DIR=./dist
           push: true
 
@@ -113,7 +113,7 @@ jobs:
       #   uses: docker/build-push-action@v3
       #   with:
       #     builder: ${{ steps.buildx.outputs.name }}
-      #     context: ${{ github.workspace }}/docker-images/zrok-controller/
+      #     context: ${{ github.workspace }}/docker/images/zrok-controller/
       #     platforms: linux/amd64,linux/arm64
       #     tags: ${{ steps.tagprep_ctrl.outputs.DOCKER_TAGS }}
       #     build-args: |
@@ -135,7 +135,7 @@ jobs:
       #   uses: docker/build-push-action@v3
       #   with:
       #     builder: ${{ steps.buildx.outputs.name }}
-      #     context: ${{ github.workspace }}/docker-images/zrok-frontend/
+      #     context: ${{ github.workspace }}/docker/images/zrok-frontend/
       #     platforms: linux/amd64,linux/arm64
       #     tags: ${{ steps.tagprep_frontend.outputs.DOCKER_TAGS }}
       #     build-args: |
@@ -157,7 +157,7 @@ jobs:
       #   uses: docker/build-push-action@v3
       #   with:
       #     builder: ${{ steps.buildx.outputs.name }}
-      #     context: ${{ github.workspace }}/docker-images/zrok-share/
+      #     context: ${{ github.workspace }}/docker/images/zrok-share/
       #     platforms: linux/amd64,linux/arm64
       #     tags: ${{ steps.tagprep_share.outputs.DOCKER_TAGS }}
       #     build-args: |
@@ -179,7 +179,7 @@ jobs:
       #   uses: docker/build-push-action@v3
       #   with:
       #     builder: ${{ steps.buildx.outputs.name }}
-      #     context: ${{ github.workspace }}/docker-images/zrok-access/
+      #     context: ${{ github.workspace }}/docker/images/zrok-access/
       #     platforms: linux/amd64,linux/arm64
       #     tags: ${{ steps.tagprep_access.outputs.DOCKER_TAGS }}
       #     build-args: |

docker/compose/.gitignore

@@ -0,0 +1 @@
+.env

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

@@ -0,0 +1,66 @@
+version: '3'
+services:
+  zrok-enable-init:
+    image: busybox
+    # matches uid:gid of "nobody" in zrok container image
+    command: chown -Rc 65534:65534 /mnt/.zrok
+    user: root
+    volumes:
+      - zrok_env:/mnt/.zrok
+  zrok-enable:
+    image: docker.io/openziti/zrok:enable-headless  # FIXME: resume :latest if >= :0.3.2
+    depends_on:
+      zrok-enable-init:
+        condition: service_completed_successfully
+    entrypoint:
+      - bash
+      - -c
+      - |
+        if [[ -s /mnt/.zrok/environment.json ]]; then
+          echo "INFO: noop: zrok environment is already enabled"
+          exit 0
+        else
+          echo "INFO: running: zrok $$(sed -E "s/${ZROK_ENABLE_TOKEN}/************/" <<< $${@})"
+          exec zrok $${@}
+        fi
+    command: -- enable --headless ${ZROK_ENABLE_TOKEN}
+    volumes:
+      - zrok_env:/mnt/.zrok
+    environment:
+      HOME: /mnt
+      ZROK_ENABLE_TOKEN:
+      ZROK_API_ENDPOINT: https://api.zrok.io/
+  zrok-private-access:
+    image: docker.io/openziti/zrok
+    command: access private --bind 0.0.0.0:9191 ${ZROK_ACCESS_TOKEN}
+    depends_on:
+      zrok-enable:
+        condition: service_completed_successfully
+    ports:
+      - 9191:9191  # expose the zrok private access proxy to the Docker host
+    stdin_open: true  # FIXME: remove when --headless is available
+    tty: true         # FIXME: remove when --headless is available
+    volumes:
+      - zrok_env:/mnt/.zrok
+    environment:
+      HOME: /mnt
+      PFXLOG_NO_JSON: "true"
+      ZROK_ACCESS_TOKEN:
+
+  # alternatively, access the zrok private access proxy from another container
+  demo-client:
+    depends_on:
+      - zrok-private-access
+    image: busybox
+    entrypoint:
+      - sh
+      - -c
+      - |
+        while true; do 
+          echo 'INFO: trying wget';
+          wget -q -O - http://zrok-private-access:9191/ip; 
+          sleep 3; 
+        done
+
+volumes:
+  zrok_env:

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

@@ -0,0 +1,53 @@
+version: '3'
+services:
+  zrok-enable-init:
+    image: busybox
+    # matches uid:gid of "nobody" in zrok container image
+    command: chown -Rc 65534:65534 /mnt/.zrok
+    user: root
+    volumes:
+      - zrok_env:/mnt/.zrok
+  zrok-enable:
+    image: docker.io/openziti/zrok:enable-headless  # FIXME: resume :latest if >= :0.3.2
+    depends_on:
+      zrok-enable-init:
+        condition: service_completed_successfully
+    entrypoint:
+      - bash
+      - -c
+      - |
+        if [[ -s /mnt/.zrok/environment.json ]]; then
+          echo "INFO: noop: zrok environment is already enabled"
+          exit 0
+        else
+          echo "INFO: running: zrok $$(sed -E "s/${ZROK_ENABLE_TOKEN}/************/" <<< $${@})"
+          exec zrok $${@}
+        fi
+    command: -- enable --headless ${ZROK_ENABLE_TOKEN}
+    volumes:
+      - zrok_env:/mnt/.zrok
+    environment:
+      HOME: /mnt
+      ZROK_ENABLE_TOKEN:
+      ZROK_API_ENDPOINT: https://api.zrok.io/
+  zrok-private-share:
+    image: docker.io/openziti/zrok
+    command: share private --headless http://zrok-test:8080
+    depends_on:
+      zrok-enable:
+        condition: service_completed_successfully
+    volumes:
+      - zrok_env:/mnt/.zrok
+    environment:
+      HOME: /mnt
+      PFXLOG_NO_JSON: "true"
+
+  # demo servers you can share with zrok
+  zrok-test:
+    image: docker.io/openziti/zrok
+    command: test endpoint --address 0.0.0.0  # 9090
+  httpbin-test:
+    image: mccutchen/go-httpbin  # 8080/tcp
+
+volumes:
+  zrok_env:

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

@@ -0,0 +1,58 @@
+version: '3'
+services:
+  zrok-enable-init:
+    image: busybox
+    # matches uid:gid of "nobody" in zrok container image
+    command: chown -Rc 65534:65534 /mnt/.zrok
+    user: root
+    volumes:
+      - zrok_env:/mnt/.zrok
+  zrok-enable:
+    image: docker.io/openziti/zrok:enable-headless  # FIXME: resume :latest if >= :0.3.2
+    depends_on:
+      zrok-enable-init:
+        condition: service_completed_successfully
+    entrypoint:
+      - bash
+      - -c
+      - |
+        if [[ -s /mnt/.zrok/environment.json ]]; then
+          echo "INFO: noop: zrok environment is already enabled"
+          exit 0
+        else
+          echo "INFO: running: zrok $$(sed -E "s/${ZROK_ENABLE_TOKEN}/************/" <<< $${@})"
+          exec zrok $${@}
+        fi
+    command: -- enable --headless ${ZROK_ENABLE_TOKEN}
+    volumes:
+      - zrok_env:/mnt/.zrok
+    environment:
+      HOME: /mnt
+      ZROK_ENABLE_TOKEN:
+      ZROK_API_ENDPOINT: https://api.zrok.io
+  zrok-public-share:
+    image: docker.io/openziti/zrok
+    command: share public --headless http://zrok-test:9090
+    depends_on:
+      zrok-enable:
+        condition: service_completed_successfully
+    volumes:
+      - zrok_env:/mnt/.zrok
+    environment:
+      HOME: /mnt
+      PFXLOG_NO_JSON: "true"
+    volumes:
+      - zrok_env:/mnt/.zrok
+    environment:
+      HOME: /mnt
+      PFXLOG_NO_JSON: "true"
+
+  # demo servers you can share with zrok
+  zrok-test:
+    image: docker.io/openziti/zrok
+    command: test endpoint --address 0.0.0.0  # 9090
+  httpbin-test:
+    image: mccutchen/go-httpbin  # 8080/tcp
+
+volumes:
+  zrok_env:

docker/images/cross-build/Dockerfile

@@ -0,0 +1,35 @@
+FROM debian:bullseye-slim
+#
+# this file mirrors the build params used in the GitHub Actions and enables
+# reproducible builds for downstream forks for Ziti contributors 
+#
+
+ARG TARGETARCH
+ARG golang_version=1.19.5
+ARG go_distribution_file=go${golang_version}.linux-${TARGETARCH}.tar.gz
+ARG go_path=/usr/share/go
+ARG go_root=/usr/local/go
+ARG go_cache=/usr/share/go_cache
+ARG uid=1000
+ARG gid=1000
+RUN apt-get -y update
+RUN apt-get -y install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf gcc-aarch64-linux-gnu
+RUN apt-get -y install wget build-essential
+
+COPY ./linux-build.sh /usr/local/bin/
+RUN wget -q https://go.dev/dl/${go_distribution_file}
+RUN tar -xzf ${go_distribution_file} -C /usr/local/
+
+RUN mkdir ${go_path} ${go_cache}
+RUN chown -R ${uid}:${gid} ${go_path} ${go_cache}
+
+USER ${uid}:${gid}
+ENV TARGETARCH=${TARGETARCH}
+ENV GOPATH=${go_path}
+ENV GOROOT=${go_root}
+ENV GOCACHE=${go_cache}
+ENV PATH=${go_path}/bin:${go_root}/bin:$PATH
+RUN go install github.com/mitchellh/gox@latest
+WORKDIR /mnt
+ENTRYPOINT ["linux-build.sh"]
+

docker/images/cross-build/README.md

@@ -0,0 +1,46 @@
+
+# Cross-build Container for Building the Linux Executables for this zrok Project
+
+Running this container produces three executables for zrok, one for each platform architecture: amd64, arm, arm64. You may specify the target CPU architecture as a parameter to the `docker run` command.
+
+## Build the Container Image
+
+You only need to build the container image once unless you change the Dockerfile or `./linux-build.sh`.
+
+```bash
+# build a container image named "zrok-builder" with the same version of Go that's declared in go.mod
+docker buildx build \
+    --tag=zrok-builder \
+    --build-arg uid=$UID \
+    --build-arg gid=$GID \
+    --build-arg golang_version=$(grep -Po '^go\s+\K\d+\.\d+(\.\d+)?$' go.mod) \
+    --load \
+    ./docker/images/cross-build/
+```
+
+## Run the Container to Build Executables for the Desired Architectures
+
+Executing the following `docker run` command will:
+
+1. Mount the top-level of this repo on the container's `/mnt`
+2. Run `linux-build.sh ${@}` inside the container
+3. Deposit built executables in `./dist/`
+
+```bash
+# build for all three architectures: amd64 arm arm64
+docker run \
+    --rm \
+    --name=zrok-builder \
+    --volume=$PWD:/mnt \
+    zrok-builder
+
+# build only amd64 
+docker run \
+    --rm \
+    --name=zrok-builder \
+    --volume=$PWD:/mnt \
+    zrok-builder \
+        amd64
+```
+
+You will find the built artifacts in `./dist/`.

docker/images/cross-build/linux-build.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+#
+# build the Linux artifacts for amd64, arm, arm64
+#
+# runs one background job per desired architecture unless there are too few CPUs
+#
+# 
+
+set -o pipefail -e -u
+
+# if no architectures supplied then default list of three
+if (( ${#} )); then
+    typeset -a JOBS=(${@})
+else
+    typeset -a JOBS=(amd64 arm arm64)
+fi
+
+# specify the Go template used by Gox to save the artifacts
+GOX_OUTPUT="dist/{{.Arch}}/{{.OS}}/{{.Dir}}"
+# count the number of available CPUs for time-efficient parallelism
+PROC_COUNT=$(nproc --all)
+# compute the number of processors available for each job, rounded down to integer
+PROCS_PER_JOB=$((PROC_COUNT / ${#JOBS[@]}))
+# if multiple jobs and at least one processor for each job then background, else foreground with all available CPUs-1 (gox default)
+if (( ${#JOBS[@]} > 1 && ${PROCS_PER_JOB} )); then 
+    BACKGROUND="&"
+    # initialize an associative array in which to map background PIDs to the ARCH being built
+    typeset -A BUILDS
+else
+    BACKGROUND=""   # run normally in foreground
+    PROCS_PER_JOB=0 # invokes gox default to use all CPUs-1
+fi
+
+for ARCH in ${JOBS[@]}; do
+    GOX_CMD="
+        gox \
+            -cgo \
+            -os=linux \
+            -arch=${ARCH} \
+            -output=${GOX_OUTPUT} \
+            -parallel=${PROCS_PER_JOB} \
+            ./cmd/zrok
+    "
+case ${ARCH} in
+        amd64)  eval ${GOX_CMD} ${BACKGROUND}
+                (( ${PROCS_PER_JOB} )) && BUILDS[${!}]=${ARCH}  # if greater than zero procs per job then map background pid->arch
+        ;;
+        arm)    eval CC=arm-linux-gnueabihf-gcc ${GOX_CMD} ${BACKGROUND}
+                (( ${PROCS_PER_JOB} )) && BUILDS[${!}]=${ARCH}
+        ;;
+        arm64)  eval CC=aarch64-linux-gnu-gcc ${GOX_CMD} ${BACKGROUND}
+                (( ${PROCS_PER_JOB} )) && BUILDS[${!}]=${ARCH}
+        ;;
+        *)      echo "ERROR: invalid architecture '${ARCH}', must be one of amd64, arm, arm64" >&2
+                exit 1
+        ;;
+    esac
+done
+
+# if not background in parallel then exit now with well earned success
+[[ -z "${BACKGROUND:-}" ]] && exit 0
+
+# Wait for builds in the background and exit with an error if any fail
+EXIT=0
+while true; do
+    # "wait -p" requires BASH >=5.1 which is present in Ubuntu 20.10 and Debian Bullseye
+    wait -n -p JOB_PID; JOB_RESULT=$?
+    echo "Building for ${BUILDS[$JOB_PID]} finished with result ${JOB_RESULT}"
+    (( ${JOB_RESULT} )) && EXIT=1
+done
+
+exit ${EXIT}

docs/core-features/hosting.md

@@ -5,7 +5,7 @@ sidebar_position: 200
 
 ## Self-Hosted
 
-`zrok` is not limited to a managed offering. You can [host your own](../guides/v0.3_self_hosting_guide.md) instance of `zrok` as well. `zrok` is
+`zrok` is not limited to a managed offering. You can [host your own](../guides/self-hosting/v0.3_self_hosting_guide.md) instance of `zrok` as well. `zrok` is
 also freely available as open source software hosted by GitHub under a very permissive Apache v2 license.
 
 ## Managed Service

docs/getting-started.md

@@ -430,7 +430,7 @@ You use the `zrok reserve` command to create _reserved shares_. Reserved shares
 
 ## Self-Hosting a Service Instance
 
-Interested in self-hosting your own `zrok` service instance? See the [self-hosting guide](guides/v0.3_self_hosting_guide.md) for details.
+Interested in self-hosting your own `zrok` service instance? See the [self-hosting guide](./guides/self-hosting/v0.3_self_hosting_guide.md) for details.
 
 [openziti]: https://docs.openziti.io/docs/learn/introduction/	"OpenZiti"
 [ zrok-download]: https://zrok.io "Zrok Download"

docs/guides/_category_.json

@@ -2,6 +2,6 @@
   "label": "Guides",
   "position": 30,
   "link": {
-    "type": "generated-index",
+    "type": "generated-index"
   }
 }

docs/guides/docker-share/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Docker Share",
+  "position": 40,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/guides/docker-share/v0.3_docker_private_share_guide.md

@@ -0,0 +1,92 @@
+---
+sidebar_position: 20
+sidebar_label: Private Share
+---
+
+
+# Docker Private Share
+
+With zrok, you can privately share a server app that's running in Docker. Another zrok somewhere else can then access your private share with Docker too. In this guide we'll cover both sides: the private share and the private access.
+
+## Before You Begin
+
+To follow this guide you will need [Docker](https://docs.docker.com/get-docker/) and [the Docker Compose plugin](https://docs.docker.com/compose/install/) for running `docker compose` commands in your terminal.
+
+If you have installed Docker Desktop on macOS or Windows then you are all set.
+
+## Private Share with Docker Compose
+
+First, let's create the private share.
+
+1. Make a folder on your computer to use as a Docker Compose project for your zrok private share.
+1. In your terminal, change directory to your newly-created project folder.
+1. Download [the zrok-private-share Docker Compose project file](../../../docker/compose/zrok-private-share/docker-compose.yml) into your new project folder and make sure it's named `docker-compose.yml`.
+1. Copy your zrok environment token from the zrok web console to your clipboard and paste it in a file named `.env` in the same folder like this:
+
+    ```bash
+    # file name ".env"
+    ZROK_ENABLE_TOKEN="8UL9-48rN0ua"
+    ```
+
+1. Run your Compose project to start sharing the built-in demo web server:
+
+    ```bash
+    docker compose up
+    ```
+
+1. Read the private share token from the output. One of the last lines is like this:
+
+    ```bash
+    zrok-private-share-1  | zrok access private wr3hpf2z5fiy
+    ```
+
+    Keep track of this token so you can use it in your zrok private access project.
+
+## Private Access with Docker Compose
+
+Now that we have a private share we can access it with zrok running in Docker. Next, let's access the demo web server in a web browser.
+
+1. Make a folder on your computer to use as a Docker Compose project for your zrok private access.
+1. In your terminal, change directory to your newly-created project folder.
+1. Download [the zrok-private-access Docker Compose project file](../../../docker/compose/zrok-private-access/docker-compose.yml) into your new project folder and make sure it's named `docker-compose.yml`.
+1. Copy your zrok environment token from the zrok web console to your clipboard and paste it in a file named `.env` in the same folder like this:
+
+    ```bash
+    # file name ".env"
+    ZROK_ENABLE_TOKEN="8UL9-48rN0ua"
+    ```
+
+1. Now copy the zrok private access token from the zrok private share project's output to your clipboard and paste it in the same file named `.env` here in your private share project folder like this:
+
+    ```bash
+    # file name ".env"
+    ZROK_ENABLE_TOKEN="8UL9-48rN0ua"
+    ZROK_ACCESS_TOKEN="wr3hpf2z5fiy"
+    ```
+
+1. Run your Compose project to start accessing the private share:
+
+    ```bash
+    docker compose up zrok-private-access
+    ```
+
+1. Now your zrok private access proxy is ready on http://127.0.0.1:9191. You can visit the demo web server in your browser.
+
+## Going Further with Private Access
+
+1. Try changing the demo web server used in the private share project. One alternative demo server is provided: `httpbin`.
+1. Try accessing the private share from _inside_ a container running in the private access project. One demo client is provided: `demo-client`. You can run it like this.
+
+    ```bash
+    docker compose up demo-client
+    ```
+
+1. You'll see in the terminal output that the demo-client container is getting a response from the private share indicating the source IP of the request from the perspective of the demo server: `httpbin` that's running in the private share project.
+
+## Cleaning Up
+
+Run the "down" command in both Compose projects to destroy them when you're all done. This will stop the running containers and delete zrok environments' storage volumes. Then delete the selected zrok environment by clicking "Actions" in the web console.
+
+```bash
+docker compose down --remove-orphans --volumes
+```

docs/guides/docker-share/v0.3_docker_public_share_guide.md

@@ -0,0 +1,64 @@
+---
+sidebar_position: 10
+sidebar_label: Public Share
+---
+
+# Docker Public Share
+
+You can run a public or private zrok share with Docker.
+
+## Before You Begin
+
+To follow this guide you will need [Docker](https://docs.docker.com/get-docker/) and [the Docker Compose plugin](https://docs.docker.com/compose/install/) for running `docker compose` commands in your terminal.
+
+## Public Share with Docker Compose
+
+1. Make a folder on your computer to use as a Docker Compose project for your zrok public share.
+1. In your terminal, change directory to your newly-created project folder.
+1. Download [the zrok-public-share Docker Compose project file](../../../docker/compose/zrok-public-share/docker-compose.yml) into your new project folder.
+1. Copy your zrok environment token from the zrok web console to your clipboard and paste it in a file named `.env` in the same folder like this:
+
+    ```bash
+    # file name ".env"
+    ZROK_ENABLE_TOKEN="8UL9-48rN0ua"
+    ```
+
+1. Run your Compose project to start sharing the built-in demo web server:
+
+    ```bash
+    docker compose up
+    ```
+
+1. Read the public share URL from the output. One of the last lines is like this:
+
+    ```bash
+    zrok-public-share-1  |  https://w6r1vesearkj.in.zrok.io/
+    ```
+
+    You can swap in a different server app container instead of the demo server, or you could change the Docker network to "host" and share something running on the Docker host's localhost interface.
+
+1. Edit the file `docker-compose.yml`. Replace the following line:
+
+    ```yaml
+    command: share public --headless http://zrok-test:9090
+    ```
+
+    Replace that line with this to start sharing the HTTPBin server app container instead of the zrok test endpoint.
+
+    ```yaml
+    command: share public --headless http://httpbin-test:8080
+    ```
+
+1. Re-run your project to load the new server configuration.
+
+    ```bash
+    docker-compose up --force-recreate
+    ```
+
+    Now you'll have a new public share URL for the `httpbin` API testing server.
+
+1. Run "down" to destroy the Compose project when you're done. Then delete the selected zrok environment by clicking "Actions" in the web console.
+
+    ```bash
+    docker compose down --remove-orphans --volumes
+    ```

docs/guides/self-hosting/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Self Hosting",
+  "position": 20,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/guides/self-hosting/v0.3_nginx_tls_guide.md

@@ -1,3 +1,8 @@
+---
+sidebar_position: 50
+sidebar_label: Nginx TLS
+---
+
 # Nginx Reverse Proxy for zrok
 
 ## Walkthrough Video

docs/guides/self-hosting/v0.3_self_hosting_guide.md

@@ -1,4 +1,9 @@
-# Self-Hosting Guide
+---
+sidebar_position: 40
+sidebar_label: Linux VPS
+---
+
+# Self-Hosting Guide for Linux
 
 ## Walkthrough Video