Merge pull request #787 from openziti/doc-share-backend-modes

cross-link concepts to make it easier to answer "what are the different backend modes?"

CHANGELOG.md

@@ -10,6 +10,8 @@ FIX: reduce Docker image sizes (https://github.com/openziti/zrok/pull/783)
 
 FIX: Correct the download URL for the armv7 Linux release (https://github.com/openziti/zrok/issues/782)
 
+CHANGE: briefly mention the backend modes that apply to public and private share concepts
+
 ## v0.4.44
 
 FIX: Fix for goreleaser build action to align with changed ARM64 build path.
@@ -228,7 +230,7 @@ CHANGE: The OpenZiti SDK for golang (https://github.com/openziti/sdk-golang) has
 
 ## v0.4.23
 
-FEATURE: New CLI commands have been implemented for working with the `drive` share backend mode (part of the "zrok Drives" functionality). These commands include `zrok cp`, `zrok mkdir` `zrok mv`, `zrok ls`, and `zrok rm`. These are initial, minimal versions of these commands and very likely contain bugs and ergonomic annoyances. There is a guide available at (`docs/guides/drives/cli.md`) that explains how to work with these tools in detail (https://github.com/openziti/zrok/issues/438)
+FEATURE: New CLI commands have been implemented for working with the `drive` share backend mode (part of the "zrok Drives" functionality). These commands include `zrok cp`, `zrok mkdir` `zrok mv`, `zrok ls`, and `zrok rm`. These are initial, minimal versions of these commands and very likely contain bugs and ergonomic annoyances. There is a guide available at (`docs/guides/drives.mdx`) that explains how to work with these tools in detail (https://github.com/openziti/zrok/issues/438)
 
 FEATURE: Python SDK now has a decorator for integrating with various server side frameworks. See the `http-server` example.
 

docs/concepts/_backend_http.mdx

@@ -0,0 +1,5 @@
+
+- `proxy` mode forwards requests received by the frontend to the target server ([more](/concepts/http.md))
+- `web` mode serves a target folder as a file index web page ([more](/concepts/files.md))
+- `drive` mode serves a target folder with WebDAV ([guide](/guides/drives.mdx))
+- `caddy` mode runs the built-in Caddy server with the targeted Caddyfile ([example](pathname:///simple_reverse_proxy.Caddyfile))

docs/concepts/http.md

@@ -29,4 +29,4 @@ When you execute this command, you'll get a `zrok` bridge like the following:
 
 The URL shown at the top of the bridge shows the address where you can access your `public` share.
 
-Hit `CTRL-C` or `q` in the bridge to exit it and delete the `public` share.
+Hit `CTRL-C` or `q` in the bridge to exit it and delete the `public` share.

docs/concepts/index.md

@@ -7,7 +7,7 @@ sidebar_position: 25
 
 `zrok` was designed to make sharing local resources both secure and easy. In this section of the `zrok` documentation, we'll tour through all of the most important features.
 
-Sharing with `zrok` can be either [`public`](./sharing-public.md) or [`private`](./sharing-private.md).
+Sharing with `zrok` can be either [`public`](./sharing-public.mdx) or [`private`](./sharing-private.mdx).
 Naturally, regular web-based resources can be shared but `zrok` also includes support for sharing raw [TCP](./tunnels.md) and [UDP](./tunnels.md) network connections, and also includes a [website and file sharing](./files.md) feature.
 
 Learn about `zrok` [hosting here](./hosting.md), including instructions on how to [install your own `zrok` instance](/guides/self-hosting/linux/index.mdx).

docs/concepts/sharing-private.md → docs/concepts/sharing-private.mdx

@@ -1,6 +1,9 @@
 ---
 sidebar_position: 0
 ---
+
+import BackendHttp from '/../docs/concepts/_backend_http.mdx'
+
 # Private Shares
 
 `zrok` was built to share and access digital resources. A `private` share allows a resource to be 
@@ -12,7 +15,7 @@ Peer-to-peer private resource sharing is one of the things that makes `zrok` uni
 
 Here's how private sharing works:
 
-# Peer to Peer
+## Peer to Peer
 
 ![zrok_public_share](../images/zrok_private_share.png)
 
@@ -27,3 +30,16 @@ The shared resource can be a development web server to share with friends and co
 The peer-to-peer capabilities of `zrok` are an important property of the underlying [OpenZiti](https://docs.openziti.io/docs/learn/introduction/) network that `zrok` uses to provide connectivity between users and resources.
 
 Creating `private` shares is easy and is accomplished using the `zrok share private` command. Run `zrok share private` to see the usage output and to further learn how to use the command.
+
+## Private Backend Modes
+
+The default backend mode is `proxy` which targets an HTTP URL that must be reachable by the backend.
+
+```bash title="proxy example"
+zrok share private 80
+```
+
+<BackendHttp/>
+- `tcpTunnel`, `udpTunnel` modes forward the data payload to the target server ([more](/concepts/tunnels.md))
+- `socks` mode provides a SOCKS5 dynamic proxy on the private access bind port that tunnels TCP payloads to the share backend where they are forwarded to their destinations ([blog](https://blog.openziti.io/the-zrok-socks-backend))
+- `vpn` mode provides a network layer tunnel between the private access and the share backend ([guide](guides/vpn/vpn.md))

docs/concepts/sharing-public.md → docs/concepts/sharing-public.mdx

@@ -1,6 +1,9 @@
 ---
 sidebar_position: 10
 ---
+
+import BackendHttp from '/../docs/concepts/_backend_http.mdx'
+
 # Public Shares
 
 `zrok` supports `public` sharing for web-based (HTTP and HTTPS) resources. These resources are easily shared with the general internet through public access points.
@@ -13,4 +16,14 @@ sidebar_position: 10
 
 As with `private` sharing, `public` sharing does not require you to open any firewall ports or otherwise compromise the security of your local environments. A `public` share goes away as soon as you terminate the `zrok share` command.
 
-Using `public` shares is easy and is accomplished using the `zrok share public` command. Run `zrok share public` to see the command-line help and to learn how to use `public` shares.
+Using `public` shares is easy and is accomplished using the `zrok share public` command. Run `zrok share public` to see the command-line help and to learn how to use `public` shares.
+
+## Public Backend Modes
+
+The default backend mode is `proxy` which targets an HTTP URL that must be reachable by the backend.
+
+```bash title="proxy example"
+zrok share public 80
+```
+
+<BackendHttp/>

docs/getting-started.mdx

@@ -67,9 +67,9 @@ The best ways to engage are [Discourse](https://openziti.discourse.group/) for q
 
 Use `zrok` to share a running service, like a web server or a network socket, or to share a directory of static files.
 
-If [sharing publicly](./concepts/sharing-public.md), you can reserve a subdomain, enable authentication options, or both. Public shares proxy HTTPS to your service or files.
+If [sharing publicly](./concepts/sharing-public.mdx), you can reserve a subdomain, enable authentication options, or both. Public shares proxy HTTPS to your service or files.
 
-If [sharing privately](./concepts/sharing-private.md), only users with the share token can access your share. In addition to what you can share publicly, private shares can include TCP and UDP services.
+If [sharing privately](./concepts/sharing-private.mdx), only users with the share token can access your share. In addition to what you can share publicly, private shares can include TCP and UDP services.
 
 ## Installing the zrok Command
 
@@ -245,6 +245,8 @@ If we try to reload the frontend endpoint in our web browser, we'll see:
 
 ![Not Found](images/zrok_not_found.png)
 
+[More about public shares](/concepts/sharing-public.mdx)
+
 ### Private Shares
 
 `zrok` also provides a powerful _private_ sharing model. If I execute the following command:
@@ -263,6 +265,8 @@ Rather than allowing access to your service through a public frontend, a _privat
 
 The `zrok access private wvszln4dyz9q` command can be run by any `zrok` user, allowing them to create and bind a local HTTP listener, that allows for private access to your shared resources.
 
+[More about private shares](/concepts/sharing-private.mdx)
+
 ### Proxy Backend Mode
 
 Without specifying a _backend mode_, the `zrok share` command will assume that you're trying to share a `proxy` resource. A `proxy` resource is usually some private HTTP/HTTPS endpoint (like a development server, or a private application) running in your local environment. Usually such an endpoint would have no inbound connectivity except for however it is reachable from your local environment. It might be running on `localhost`, or only listening on a private LAN segment behind a firewall. 
@@ -320,6 +324,8 @@ $ zrok release mltwsinym1s2
 [   0.230]    INFO main.(*releaseCommand).run: reserved share 'mltwsinym1s2' released
 ```
 
+[More about reserved shares](/concepts/sharing-reserved.md)
+
 ## Concepts Review
 
 In summary, `zrok` lets you easily and securely share resources with both general internet users (through _public_ sharing) and also with other `zrok` users (through _private_ sharing).

docs/guides/docker-share/docker_private_share_guide.md

@@ -12,7 +12,7 @@ Privately share a Docker Compose service with a separate zrok environment and a
 
 With zrok, you can privately share a service that's running in Docker. You need a zrok private share running somewhere that it can reach the service you're sharing, and a zrok private access running somewhere else where you want to use the private share. Together, the private share and private access form a private point-to-point tunnel.
 
-Here's a short article with an overview of [private sharing with zrok](/concepts/sharing-private.md).
+Here's a short article with an overview of [private sharing with zrok](/concepts/sharing-private.mdx).
 
 ## Walkthrough Video
 

docs/guides/docker-share/docker_public_share_guide.md

@@ -12,7 +12,7 @@ Publicly share a Docker Compose service with a separate zrok environment and a p
 
 With zrok, you can publicly share a service that's running in Docker. You need a zrok public share running somewhere that it can reach the service you're sharing. As long as that public share is running and your service is available, anyone with the address can use your service.
 
-Here's a short article with an overview of [public sharing with zrok](/concepts/sharing-public.md).
+Here's a short article with an overview of [public sharing with zrok](/concepts/sharing-public.mdx).
 
 ## Walkthrough Video
 

docs/guides/drives/cli.md → docs/guides/drives.mdx

@@ -1,4 +1,5 @@
-# The Drives CLI
+
+# Drives
 
 The zrok drives CLI tools allow for simple, ergonomic management and synchronization of local and remote files.
 

website/docusaurus.config.js

@@ -7,7 +7,7 @@ const darkCodeTheme = require('prism-react-renderer/themes/dracula');
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: 'Zrok',
-  staticDirectories: ['static', '../docs/images', '../docker/compose'],
+  staticDirectories: ['static', '../docs/images', '../docker/compose', '../etc/caddy'],
   tagline: 'Globally distributed reverse proxy',
   url: 'https://docs.zrok.io',
   baseUrl: '/',