I compiled my resources and repeated my setup, and wrote a doc for a quick and repeatable docker compose setup. The parts that were confusing to me are in the example doc for the .env file. I wrote this for my testing and team and wanted to share it. This serves as the basis for all the future testing we will do, that is until we outgrow it as a testing environment.
How-to Start an OpenZiti Simple Instance with Docker Compose
The following how-to will create an OpenZiti instance running on Docker Compose using the simplified quickstart method. This will allow simple re-creation of the environment for fast-feedback in your testing.
Assumptions:
You will need to make several substitutions for your environment. These substitutions are as follows.
- Our ziti controller hostname and port is
ziti.zititest.biz:1280.- Our ziti controller web address and port is
https://ziti.zititest.biz:8443. (note it is a self-signed cert)- We have a dns record for
ziti.zititest.bizpointing to our public IP address of123.123.123.123.- The ziti default admin password is
ThisIsNotYourPassword!.- Debian 12 will be used as our example operating system.
- All commands will be executed from the
~/zitidirectory once it exists.- For the purposes of this demo, we will be using the Docker Convenience Script, which is suitable for testing only.
Prepare Your Host VM
In our case, we are using a virtual machine on Linode, although any small vps will be sufficient. We will ssh into our vm and prep the operating system for use.
-
Update your host with
sudo apt update && sudo apt dist-upgrade -y && sudo reboot -
Install Docker with
curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh ./get-docker.sh -
Verify Docker is installed with
sudo docker ps. You should see the following as output.$ sudo docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
Prepare Your Ziti Components
We will now create a directory to run our Ziti instance in. Then we will get the simplified compose file, .env file, and make the necessary changes for our environment.
-
Create a directory to work from with
mkdir ziti -
Change to this directory with
cd ziti -
Get the simplified compose file with
curl -o docker-compose.yml https://raw.githubusercontent.com/openziti/ziti/release-next/quickstart/docker/simplified-docker-compose.yml -
Get the environment file with
curl -O https://raw.githubusercontent.com/openziti/ziti/release-next/quickstart/docker/.env -
Make the following changes to your
.envfile for your actual environment:ZITI_PWD=ThisIsNotYourPassword! ZITI_CTRL_EDGE_ADVERTISED_ADDRESS=ziti.zititest.biz ZITI_CTRL_ADVERTISED_ADDRESS=ziti.zititest.biz ZITI_CTRL_EDGE_IP_OVERRIDE=123.123.123.123
Start Your Ziti Instance
We should now be able to run our Ziti instance with Docker Compose. The next step will be helpful to run in a separate terminal, so that we can watch the the logs of the containers.
-
Start your compose instance with
sudo docker compose up -dAn example of the output is below.
$ sudo docker compose up -d [+] Running 2/4 โ ด ziti-controller-init-container Pulling 3.6s โ ด ziti-edge-router 12 layers [โฃทโฃฆโฃฟโฃฟโ โ โ โ โ โ โ โ ] 68.4MB/83.47MB Pulling 3.6s โ ด ziti-console 11 layers [โ โ โ โ โ โ โ โ โ โ โ ] 0B/0B Pulling 3.6s โ ด ziti-controller Pulling 3.6s -
We can monitor the status of our compose environment with a tool called jesseduffield/lazydocker, which is a minimalist terminal based viewer for container workloads. The executable can be downloaded and executed with the following commands.
curl https://raw.githubusercontent.com/jesseduffield/lazydocker/master/scripts/install_update_linux.sh | bash sudo $HOME/.local/bin/lazydocker
You should see the containers settle into a running state and the logs mostly go quiet. The ziti-controller-init-1 container will exit having finished it's work, and the ziti instance should be up and running.
Test Your Ziti Instance
Let's test the instance now by attempting to log into it. We can do this from the terminal on our host vm. Then let's see if we can list identities and other objects.
-
First, we need to get the Ziti Executable and extract it to our folder. We can find the executable from the Releases ยท openziti/ziti page. Get the URL of the current release. We can then download and extract with the following commands.
wget -q https://github.com/openziti/ziti/releases/download/v0.30.0/ziti-linux-amd64-0.30.0.tar.gz tar -xzvf ziti-linux-amd64-0.30.0.tar.gz -
Test the
zitiexecutable with./ziti -vand confirm that the version you downloaded is output. -
Sign in to the ziti instance and accept the certificate authority prompt.
./ziti edge login localhost:1280 -u admin -p ThisIsNotYourPassword!The output should look like the following.
$ ./ziti edge login localhost:1280 -u admin -p ThisIsNotYourPassword! Untrusted certificate authority retrieved from server Verified that server supplied certificates are trusted by server Server supplied 5 certificates Trust server provided certificate authority [Y/N]: y Server certificate chain written to /home/jp/.config/ziti/certs/localhost Token: 894d724c-8fd1-48bb-81e9-4d7cbe618534 Saving identity 'default' to /home/jp/.config/ziti/ziti-cli.json -
Now list the identities with
./ziti edge list identitiesAnd example of the output is below.
$ ./ziti edge list identities โญโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโฌโโโโโโโโโโโโโฌโโโโโโโโโโโโโโฎ โ ID โ NAME โ TYPE โ ATTRIBUTES โ AUTH-POLICY โ โโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโผโโโโโโโโโผโโโโโโโโโโโโโผโโโโโโโโโโโโโโค โ 3yOFl14MW โ ziti-edge-router โ Router โ โ Default โ โ 9KBjA-Dah โ Default Admin โ User โ โ Default โ โฐโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโดโโโโโโโโโดโโโโโโโโโโโโโดโโโโโโโโโโโโโโฏ
If you see output like the above, then you are successful in creating your Docker Compose instance of OpenZiti
You can also test the ZAC (Ziti web console) with the curl command below. This will just respond with the HTTP Status Code confirming it is online. You can browse to this page if you have allowed firewall access to your server, the default port is 8443.
curl -o /dev/null -w '%{http_code}\n' -s -I https://localhost:8443/login -k
The output looks like the following, it returns a 200. The 200 OK status code means that the request was successful.
$ curl -o /dev/null -w '%{http_code}\n' -s -I https://localhost:8443/login -k
200
Deleting Your Ziti Instance
When you are ready to delete your Ziti instance, the process is very simple. The command below will stop the instance, clear out the container volumes that hold the data like the certificates and database, and then delete the images used by the container. This will allow you to start fresh again, with a new instance for further testing.
sudo docker compose down -v -rmi all
Here is what the output looks like when destroying the instance.
$ sudo docker compose down -v --rmi all
[+] Running 8/8
โ Container ziti-ziti-controller-init-container-1 Removed 0.0s
โ Container ziti-ziti-console-1 Removed 10.3s
โ Container ziti-ziti-edge-router-1 Removed 10.4s
โ Container ziti-ziti-controller-1 Removed 10.3s
โ Volume ziti_ziti-fs Remo... 0.0s
โ Image openziti/quickstart:latest Removed 0.1s
โ Image openziti/zac:latest Removed 0.7s
โ Network ziti_ziti Remove... 0.3s
Conclusion
If you have been able to follow along with this how-to, congratulations, you should have an instance of OpenZiti suitable for testing using Docker Compose. This instance is easy to tear down and build up again. Each time you rebuild the instance, you will have a clean instance with nothing but the quickstart resources.