extern/zrok
1
1
Fork 0
mirror of https://github.com/openziti/zrok.git synced 2024-11-28 19:14:07 +01:00
Code Issues Packages Projects Releases Wiki Activity

refine Linux instance guide; correct Docker instance errors

Browse Source
This commit is contained in:
Kenneth Bingham 2024-05-03 09:50:52 -04:00
parent 926978cb08
commit 5ed15fe9d8
No known key found for this signature in database
GPG Key ID: 31709281860130B6
2 changed files with 98 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docker/compose/zrok-instance/README.md
View File

@ -1,11 +1,11 @@
## Docker Quickstart
## 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>
### DNS Configuration
The quickstart makes these assumptions about your global 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.
@ -14,7 +14,7 @@ The quickstart makes these assumptions about your global DNS configuration.
### 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 "quickstart" container and is managed exclusively by zrok.
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.
#### Shortcut Option
@ -122,13 +122,13 @@ Follow [the getting started guide](/docs/getting-started#installing-the-zrok-com
### Firewall Configuration
The `quickstart` and `caddy` containers publish ports to all devices that use zrok shares. The `zrok-controller` and `zrok-frontend` containers expose ports only to the `caddy` container and the Docker host's loopback interface.
The `ziti-quickstart` and `caddy` containers publish ports to all devices that use zrok shares. The `zrok-controller` and `zrok-frontend` containers expose ports only to the `caddy` container and the Docker host's loopback interface.
#### Required
1. `443/tcp` - reverse proxy handles HTTPS requests for zrok API, OAuth, and public shares (published by container `caddy`)
1. `1280/tcp` - ziti ctrl plane (published by container `quickstart`)
1. `3022/tcp` - ziti data plane (published by container `quickstart`)
1. `1280/tcp` - ziti ctrl plane (published by container `ziti-quickstart`)
1. `3022/tcp` - ziti data plane (published by container `ziti-quickstart`)
#### Optional
@ -139,7 +139,7 @@ The `quickstart` and `caddy` containers publish ports to all devices that use zr
1. Check the ziti and zrok logs.
You can substitute the service container name of each to check their logs individually: `quickstart` (ziti container), `zrok-controller`, `zrok-frontend`.
You can substitute the service container name of each to check their logs individually: `ziti-quickstart`, `zrok-controller`, `zrok-frontend`.
```bash
docker compose logs zrok-controller

111
docs/guides/self-hosting/linux.mdx
View File

@ -10,34 +10,56 @@ sidebar_label: Linux
## Before you Begin
This will get you up and running with a self-hosted instance of zrok. I'll assume you have the following:
This will get you up and running with a self-hosted instance of `zrok`. I'll assume you have the following:
* a Linux server with a public IP
* a wildcard DNS record like `*.zrok.quigley.com` that resolves to the server IP
## OpenZiti Quickstart
## OpenZiti
The first step is to log in to your Linux server and run the OpenZiti quickstart. This will install a Ziti controller and Ziti router as systemd services.
OpenZiti (a.k.a. "Ziti") provides secure network backhaul for `zrok` public and private shares. You need a Ziti Controller and a Ziti Router. You can run everything on the same Linux VPS.
I specifically used the "Host OpenZiti Anywhere" variant because it provides a public controller. We'll need that to use zrok with multiple devices across different networks.
Keep track of the generated admin password when running the `expressInstall` script. The script will prompt you like this:
1. Install the Ziti Controller package by following the [Linux controller deployment guide](https://openziti.io/docs/category/deployments).
1. Ensure your answer file (`/opt/openziti/etc/controller/bootstrap.env`) has the FQDN of your Linux server and an admin password defined.
1. Ensure your firewall allows the controller port from the answer file.
1. Start the controller service (`ziti-controller.service`) and check the status.
1. Log in to the Ziti Controller
```text
Do you want to keep the generated admin password 'XO0xHp75uuyeireO2xmmVlK91T7B9fpD'? (Y/n)
```
```bash
ziti edge login localhost:1280 -u admin -p <password>
```
You'll need that generated password (`XO0xHp75uuyeireO2xmmVlK91T7B9fpD`) when building your `zrok` controller configuration.
1. Administratively Create a Ziti Router
BEGIN: [Run the OpenZiti Quickstart](https://docs.openziti.io/docs/learn/quickstarts/network/hosted)
```bash
ziti edge create edge-router "router1" -o /tmp/router1.jwt
```
1. Install the Ziti Router package by following [the Linux router deployment guide](https://openziti.io/docs/category/deployments).
1. Ensure your answer file (`/opt/openziti/etc/router/bootstrap.env`) has the FQDN of your Linux server for both controller and router addresses and the enrollment token from the previous step.
1. Ensure your firewall allows the router port from the answer file.
1. Start the router service (`ziti-router.service`) and check the status.
1. Verify the new router is online.
```bash
ziti edge list edge-routers
```
## Install zrok
Download [the latest release](https://github.com/openziti/zrok/releases/latest) from GitHub.
Debian and RPM packages are available for `zrok`.
```bash
sudo apt install zrok
```
Follow [the Linux installation guide](/guides/install/linux.mdx) to install the `zrok` package from the repository or manually install the binary for your platform.
## Configure the Controller
Create a controller configuration file in `etc/ctrl.yml`. The controller does not provide server TLS, but you may front the server with a reverse proxy. This example will expose the non-TLS listener for the controller.
Create a `zrok` controller configuration file in `etc/ctrl.yml`. The controller can terminate TLS or you may front the server with a reverse proxy that continually renews the necessary wildcard certificate (e.g., Caddy w/ a DNS provider plugin). This example will expose the non-TLS listener for the controller.
```yaml
# _____ __ ___ | | __
@ -66,10 +88,15 @@ store:
type: sqlite3
ziti:
api_endpoint: "https://127.0.0.1:8441"
api_endpoint: "https://127.0.0.1:1280"
username: admin
password: "XO0xHp75uuyeireO2xmmVlK91T7B9fpD"
# you can use certbot to renew the wildcard cert for the controller with a DNS provider API token or front this `zrok` # controller with Caddy
#tls:
# cert_path: "/Path/To/Cert/zrok.crt"
# key_path: "/Path/To/Cert/zrok.key"
```
The `admin` section defines privileged administrative credentials and must be set in the `ZROK_ADMIN_TOKEN` environment variable in shells where you want to run `zrok admin`.
@ -178,7 +205,7 @@ $ zrok admin create frontend sqJRAINSiB public http://{token}.zrok.quigley.com:8
[ 0.037] INFO main.(*adminCreateFrontendCommand).run: created global public frontend 'WEirJNHVlcW9'
```
The id of the frontend was emitted earlier in by the zrok controller when we ran the bootstrap command. If you don't have that log message the you can find the id again with the `ziti` CLI like this:
The id of the frontend was emitted earlier in by the `zrok` controller when we ran the bootstrap command. If you don't have that log message the you can find the id again with the `ziti` CLI like this:
```bash
# log in as admin (example)
@ -190,7 +217,7 @@ ziti edge list identities
The id is shown for the frontend identity named "public."
Nice work! The `zrok` controller is fully configured now that you have created the zrok frontend.
Nice work! The `zrok` controller is fully configured now that you have created the `zrok` frontend.
## Configure the Public Frontend
@ -202,7 +229,7 @@ host_match: zrok.quigley.com
address: 0.0.0.0:8080
```
This frontend config file has a `host_match` pattern that represents the DNS zone you're using with this instance of zrok. Incoming HTTP requests with a matching `Host` header will be handled by this frontend. You may also specify the interface address where the frontend will listen for public access requests.
This frontend config file has a `host_match` pattern that represents the DNS zone you're using with this instance of `zrok`. Incoming HTTP requests with a matching `Host` header will be handled by this frontend. You may also specify the interface address where the frontend will listen for public access requests.
The frontend does not provide server TLS, but you may front the server with a reverse proxy. It is essential the reverse proxy forwards the `Host` header supplied by the viewer. This example will expose the non-TLS listener for the frontend.
@ -220,9 +247,25 @@ $ zrok access public etc/http-frontend.yml
[ 0.002] INFO zrok/endpoints/public_frontend.newMetricsAgent: loaded 'public' identity
```
The zrok frontend uses the `public` identity created during the bootstrap process to securely access zrok backends. to provide public access for the `zrok` deployment. It is expected that the configured listener for this frontend corresponds to the DNS template specified when creating the public frontend record above.
The `zrok` frontend uses the `public` identity created during the bootstrap process to securely access zrok backends. to provide public access for the `zrok` deployment. It is expected that the configured listener for this frontend corresponds to the DNS template specified when creating the public frontend record above.
## Invite Yourself
## Create a User Account
With our `ZROK_ADMIN_TOKEN` and `ZROK_API_ENDPOINT` environment variables set, we can create our first user account.
```bash
zrok admin create account etc/ctrl.yml <email> <password>
```
The output is the account token you will use to enable each device's zrok environment.
```buttonless title="Example output"
SuGzRPjVDIcF
```
## Invite Additional Users
Offer this onboarding method to your users if you have configured an email-sending service in your `zrok` controller configuration.
```bash
$ zrok invite
@ -253,11 +296,39 @@ After doing that, I see the following output in my controller console:
Keep track of the token listed above (`SuGzRPjVDIcF`). We'll use this to enable our shell for this `zrok` deployment.
## Enable Your Shell
## Enable Your Environment
On another device that can reach your Linux server by FQDN, configure the API endpoint and enable the environment with the account token you received when you created the first user account.
```bash
$ zrok enable SuGzRPjVDIcF
export ZROK_API_ENDPOINT=https://zrok.quigley.com
# or
zrok config set apiEndpoint https://zrok.quigley.com
```
```bash
zrok enable SuGzRPjVDIcF
```
```buttonless title="Example output"
zrok environment '2AS1WZ3Sz' enabled for 'SuGzRPjVDIcF'
```
```bash
zrok status --secrets
```
```buttonless title="Example output"
Config:
CONFIG VALUE SOURCE
apiEndpoint https://zrok.quigley.com env
Environment:
PROPERTY VALUE
Secret Token SuGzRPjVDIcF
Ziti Identity 2AS1WZ3Sz
```
Congratulations. You have a working `zrok` environment!