Local - Docker Compose

If you are not familiar with it, Docker Compose is a tool for defining and running multi-container Docker applications. It makes deploying multiple containers easy by using a declarative format defined via yaml. Note that this page uses "Compose V2". This means all the commands shown will reference docker compose, not docker-compose. If you're using the older style of compose, consider upgrading to the newer v2.

Preparation - Required Files

First, grab the compose file from the ziti repository.

Using curl that would look like this:

curl -so docker-compose.yaml https://get.openziti.io/dock/docker-compose.yml

Next, grab the default environment file or just make a file in this folder that looks like this:

curl -so .env https://get.openziti.io/dock/.env

or, if you would prefer to make your .env file manually, create a file in some way such as using the command shown below:

cat > .env <<DEFAULT_ENV_FILE
# OpenZiti Variables
ZITI_IMAGE=openziti/quickstart
ZITI_VERSION=latest
ZITI_CTRL_EDGE_ADVERTISED_ADDRESS=ziti-edge-controller

## Additional variables to override. 
#ZITI_CTRL_EDGE_ADVERTISED_ADDRESS=some.other.name.com
#ZITI_CTRL_EDGE_ADVERTISED_PORT=1280
#ZITI_EDGE_CONTROLLER_IP_OVERRIDE=20.20.20.20
DEFAULT_ENV_FILE

caution

If you are running Void linux, you need to modify the docker-compose file, otherwise the services will not start properly. To do this, add the following two lines to each service definition.

    security_opt:
      - seccomp:unconfined

Please see this discussion for more information

Running via Docker Compose

Once the compose file is downloaded and the .env file exists, you'll be able to start this network using docker compose just like you can with any other compose file: docker compose up

note

Docker compose will name your containers based on the folder you were in when you started them. For me, I've made a folder named docker so all my containers start with docker_. You can influence how this works by adding --project-name docker (or whatever name you like) to your docker compose up/down commands

docker compose --project-name docker up 

Stopping the Network

This docker-compose file will generate a volume mount as well as a two docker networks. When you issue --project-name docker down the volume mapping will not be removed. If you wish to remove the volume, you'll need to specify the -v flag to the docker compose command. Leave the -v off your command if you want to just stop the containers without losing the controller database and PKI.

Deployment Diagram

The docker-compose file will create quite a few containers on your behalf. Here is a logical overview of the network that will get created:

As you can see there's a fair bit going on in there, let's break it down. The first thing to notice is that the entire image is within the scope of a Docker network. You'll see with this compose file there are three pieces of the overlay which span the Docker network: the controller, an edge router, and a websocket-based edge router.

Deployment Simplified

The stock docker-compose.yml deploys many components and is somewhat complex. If you prefer a simplified deployment via Docker compose, one which only includes the basic controller and edge router combination you can instead download the simplified-docker-compose.yml

Networks

Inside the Docker network you'll see there are three networks:

• the blue docker network
• the red docker network
• the purple "logical" network

Docker will ensure only the pieces within a given network, can only communicate within that network. This network topology is designed to approximate, very loosely, what it would be like to have a publicly deployed network. The purple network would approximate the internet itself, the blue network would represent a cloud provider's private network (such as AWS) and the red network could represent another cloud provider network (like Azure). Those details are not important, the important part is that the networks are totally private to one another. See more on this topic below in the "Testing" section.

Purple Network

There is no Docker network named "purple" in the compose file, it's entirely a logical construct. It is shown only for clarity. All the assets in the purple network are in both the blue and red docker networks (which is why it's referred to as purple). The assets in the purple network need to be in both the red and blue networks because the assets located in the blue and red networks need to communicate to the public edge routers and also need to communicate to the controller. If that's confusing, see the "Testing" section below which will hopefully make this more clear.

Red Network

The red network exists for demonstration only at this time. As you can see there are no assets inside the red network other than the private, ziti-private-red router and the ziti-fabric-router-br. This means there's nothing in the red network for Ziti to access. It would serve as a great place for you to put your own assets and explore using Ziti!

Blue Network

The blue network contains two important assets, the ziti-private-blue router and the web-test-blue server. Along with those assets, the network also contains the ziti-fabric-router-br. Although the web-test-blue server does export a port by default (port 80 on your localhost, will translate to port 8000 on the web-test-blue server), you can use Ziti to access this server without the exported port.

The "Fabric" Router

The ziti-fabric-router-br exists to illustrate that you can create edge routers that are not necessarily fully public. This is the only router which can communicate to all the other routers. The Ziti mesh may choose to use this router if the algorithm indicates it's the fastest path. Perhaps we'll see more about this in future docs.

Testing the Network

Using Docker Locally

A quick note. If you are not well-versed with Docker you might forget that exposing ports in Docker is one thing, but you'll also need to have a hosts entry for the containers you want to access from outside the Docker network. This quickstart will expect that you understand this and for every router you add you will want to make sure you add a host entry. In the docker compose example you will want/need hosts entries for at least:

• ziti-edge-controller,
• ziti-edge-router

And if you want to expose any other routers - of course you'll need/want to have entries for those as well.

Testing

Now that we have used docker compose to deploy a relatively complicated network, we can start testing it out to make sure everything is in place and looks correct. Let's try it out.

To test, we will docker exec into the running controller. Notice we'll be specifying the container and it's expected that the project was named "docker". If you don't start your compose using --project-name docker, use the proper exec command:

docker exec -it docker-ziti-controller-1 bash

Once exec'ed into the controller, the ziti CLI will be added to your PATH for you. There is also the zitiLogin alias to make it easy for you to authenticate to the Ziti controller. Run zitiLogin now and ensure you're authenticated.

ziti@724087d30014:/persistent$ zitiLogin
Token: 55ec6721-f33b-4101-970a-412331bd7578
Saving identity 'default' to /persistent/ziti-cli.json

Test - Edge Routers Online

Once authenticated, let's see if all our routers are online by running ziti edge list edge-routers:

ziti@724087d30014:/persistent$ ziti edge list edge-routers
╭────────────┬───────────────────────┬────────┬───────────────┬──────┬───────────────────────╮
│ ID         │ NAME                  │ ONLINE │ ALLOW TRANSIT │ COST │ ATTRIBUTES            │
├────────────┼───────────────────────┼────────┼───────────────┼──────┼───────────────────────┤
│ C6LbVE7fIc │ ziti-edge-router      │ true   │ true          │    0 │ public                │
│ GY1pcE78Ic │ ziti-private-blue     │ true   │ true          │    0 │ ziti-private-blue     │
│ H0UbcE78Tc │ ziti-fabric-router-br │ true   │ true          │    0 │ ziti-fabric-router-br │
│ KHTAct78Tc │ ziti-private-red      │ true   │ true          │    0 │ ziti-private-red      │
│ Yblbct7fTc │ ziti-edge-router-wss  │ true   │ true          │    0 │ public                │
╰────────────┴───────────────────────┴────────┴───────────────┴──────┴───────────────────────╯
results: 1-5 of 5

We can see all the routers are online - excellent.

Test - Edge Router Identities

In this compose file, we have used a script that adds an identity for each of our edge routers as well. We can see those by running ziti edge list identities:

ziti@724087d30014:/persistent$ ziti edge list identities
╭────────────┬───────────────────────┬────────┬────────────╮
│ ID         │ NAME                  │ TYPE   │ ATTRIBUTES │
├────────────┼───────────────────────┼────────┼────────────┤
│ C6LbVE7fIc │ ziti-edge-router      │ Router │            │
│ GY1pcE78Ic │ ziti-private-blue     │ Router │            │
│ H0UbcE78Tc │ ziti-fabric-router-br │ Router │            │
│ KHTAct78Tc │ ziti-private-red      │ Router │            │
│ Yblbct7fTc │ ziti-edge-router-wss  │ Router │            │
│ kkVrSLy.D  │ Default Admin         │ User   │            │
╰────────────┴───────────────────────┴────────┴────────────╯
results: 1-6 of 6

Notice there is an identity for every router.

Test - Network Connectivity Success

Recall that the controller should be able to contact both the red and blue edge routers using the underlay network. Let's use ping and verify:

ziti@724087d30014:/persistent$ ping ziti-private-red -c 1
PING ziti-private-red (172.29.0.2): 56 data bytes
64 bytes from 172.29.0.2: icmp_seq=0 ttl=64 time=0.387 ms
--- ziti-private-red ping statistics ---
1 packets transmitted, 1 packets received, 0% packet loss
round-trip min/avg/max/stddev = 0.387/0.387/0.387/0.000 ms

ziti@724087d30014:/persistent$ ping ziti-private-blue -c 1
PING ziti-private-blue (172.28.0.6): 56 data bytes
64 bytes from 172.28.0.6: icmp_seq=0 ttl=64 time=0.633 ms
--- ziti-private-blue ping statistics ---
1 packets transmitted, 1 packets received, 0% packet loss
round-trip min/avg/max/stddev = 0.633/0.633/0.633/0.000 ms

Test - Underlay Network Connectivity Failure

Now let's exit the Ziti controller and instead attach to the private blue router by running this command: docker exec -it docker-ziti-private-blue-1 bash. Once attached to the blue router we'll verify that we cannot connect to the private red router:

ziti@e610d6b44166:/persistent$ ping ziti-private-red -c 1
ping: unknown host

Unknown host - the private blue router cannot connect to the red router.

Test - Underlay Network Web Test Blue

While we're attached to the blue router - let's make sure we can connect to that web-test-blue server.

ziti@e610d6b44166:/persistent$ curl http://web-test-blue:8000
<pre>
Hello World


                                       ##         .
                                 ## ## ##        ==
                              ## ## ## ## ##    ===
                           /""""""""""""""""\___/ ===
                      ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ /  ===- ~~~
                           \______ o          _,/
                            \      \       _,'
                             `'--.._\..--''
</pre>

Don't forget - you can also access this from the exported port 80 on your local machine too!

curl http://localhost:80
<pre>
Hello World


                                       ##         .
                                 ## ## ##        ==
                              ## ## ## ## ##    ===
                           /""""""""""""""""\___/ ===
                      ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ /  ===- ~~~
                           \______ o          _,/
                            \      \       _,'
                             `'--.._\..--''
</pre>

Next Steps

• Now that you have your network in place, you probably want to try it out. Head to the services quickstart and start learning how to use OpenZiti.
• Add a Second Public Router: In order for multiple routers to form transit links, they need a firewall exception to expose the "link listener" port. The default port is 10080/tcp.
• Help
  • Change Admin Password
  • Reset the Quickstart