# NGINX-Demos: conference demos for the parts of NGINX Plus you cannot read about

> NGINX-Demos is a catalogue of twenty something scripted environments, several of them built around the NGINX Plus upstream configuration API, where service discovery systems reconfigure the load balancer without a reload. It is a conference exhibit rather than a product, and the prerequisites reach back to VirtualBox 4.x and Ansible.

**nginxinc/NGINX-Demos** — NGINX and NGINX Plus demos

- Repository: https://github.com/nginxinc/NGINX-Demos
- Stars: 1,285 · Forks: 648
- Language: HTML
- License: Apache-2.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/nginxinc-nginx-demos

## A catalogue of conference exhibits, not a framework

The repository is described as misc NGINX Demos from conferences showing different functionality of NGINX and NGINX Plus. That one line sets the expectations correctly, and it is the first thing to know.

The top level listing is a directory per demo, and there are around thirty of them: autoscaling-demo, aws-nlb-ha-asg, consul-api-demo, consul-dns-srv-demo, consul-template-demo, coreos-demo, etcd-demo, external-dns-nginx-ingress, fun-with-health-checks, gce-nginx-plus-deployment-guide-files, gcp-lb-ha-asg, kubernetes-demo, kubernetes-demo-nginx-ingress-resources, mqtt-contiki-demo, mysql-galera-demo, nginx-cookbook, nginx-docker-builder, nginx-gcp-meetup-demo, nginx-hello, nginx-hello-nonroot, nginx-nms-docker, nginx-openstack-heat-demo, nginx-regex-tester, nginx-swarm-demo, the two oauth2-token-introspection directories, random-files, redis-demo and zookeeper-demo.

The spread tells you the character of the collection. Some are one line of behaviour, like nginx-hello, which is NGINX running as a webserver in a Docker container serving a simple page containing the container's hostname, IP address and port, with a non root twin alongside it. Some are full infrastructures, like the autoscaling demo, which uses one NGINX Plus instance as a load balancer with two upstream groups, one for NGINX Plus web servers and one for Elasticsearch nodes, all running in Docker containers, using both the upstream_conf and status APIs, and showing creating a new NGINX Plus environment and adding and removing containers manually and with autoscaling.

The AWS and GCP entries are a different genre again. aws-nlb-ha-asg and gcp-lb-ha-asg contain series of scripts for deploying a high availability all active auto scaling NGINX Plus load balancing configuration, the GCP one described as an adaptation of a guide from nginx.com.

So the value proposition is: someone has already solved a specific problem in a specific way, and the scripts are here so you can see the answer. That is a genuinely useful thing for a repository to be, and it is also not a dependency you can add.

## The upstream_conf API is what half these demos are actually about

Read across the demo descriptions and one mechanism dominates: the upstream_conf API in NGINX Plus, used to add and remove upstream servers dynamically, without reloading NGINX Plus.

The consul-api-demo spins up a bunch of Docker containers and shows NGINX Plus used in conjunction with Consul, a service discovery platform, using the upstream_conf API to add the servers registered with Consul and remove the ones which get deregistered, and it says this automates the process of upstream reconfiguration based on Consul data using a simple bash script and Consul watches.

The etcd-demo is the same shape with a different source of truth. It uses upstream_conf to add the servers registered with etcd and remove the ones which get deregistered, again without reloading, using a simple bash script and etcdctl exec-watch.

The zookeeper-demo is the third instance of the same pattern, using a bash script and Zookeeper watches to add and remove servers dynamically.

Three demos, three different service discovery systems, one NGINX Plus API. That is the actual lesson of the collection and the reason to read them side by side rather than one at a time. The comparison is instructive because the three use different watch mechanisms, a Consul watch, an etcdctl exec-watch and a Zookeeper watch, which is the part a reader has to write themselves in each case.

The consul-template-demo and the external-dns-nginx-ingress directory extend the same territory, and the fun-with-health-checks directory suggests another NGINX Plus specific area. The nginx-openstack-heat-demo is the same idea in a different universe: deploying and configuring NGINX Plus to load balance a simple web application in OpenStack using Heat, with NGINX Plus reconfigured automatically whenever application instances are created or deleted.

The contrast case is nginx-swarm-demo, which shows load balancing with Docker Swarm alone first, then with NGINX open source, and then with NGINX Plus, including autoscaling the backend containers. That ordering is instructive, because it isolates what the Plus tier adds.

## The two OAuth demos differ only in where the cache lives

Two directories, oauth2-token-introspection-oss and oauth2-token-introspection-plus, and the difference between them is the whole point of the pair.

The OSS version is NGINX OAuth 2.0 Token Introspection with disk caching. The Plus version is NGINX OAuth 2.0 Token Introspection with keyval caching.

That is a deliberately minimal A and B. The same protocol feature, token introspection, on both tiers, with the caching mechanism changed so you can see what the Plus edition gives you. The Plus version swaps the disk cache for keyval caching, so the pair isolates the caching mechanism as the single changed variable.

It is a small demonstration, but it is a well designed one. A single protocol feature shown on both tiers with one variable changed is the clearest possible way to make the argument about what the commercial edition is for.

The same pattern shows up elsewhere in the collection, most obviously in the consul-dns-srv-demo, which uses Consul's DNS interface for load balancing with NGINX Plus. It uses DNS SRV records with the service parameter for the server directive of the http upstream module and DNS lookups over TCP, a feature introduced in NGINX Plus R9. The stated consequence is that NGINX Plus can ask for the SRV record, port and weight, in the DNS query, and can switch the DNS query over TCP automatically if it receives a truncated DNS response over UDP.

That last detail is a good example of what these demos teach. The behaviour is not about NGINX at all, it is about DNS truncation, and the configuration has to cope with a real network condition that a demo that only works on a lab network would never expose.

## Getting the demos running, which is where the friction is

Most of the demos have been configured to utilize Vagrant and Ansible to enable autodeployment, and the prerequisites section is explicit about what that costs you.

You need Vagrant installed for your OS, a provider for Vagrant to start VMs, and Ansible. The default provider is VirtualBox, with a note that only VirtualBox versions 4.0, 4.1, 4.2 and 4.3 are supported, and a pointer to the full provider list if you would rather not use VirtualBox.

Then you clone the repository, and copy the nginx-repo.key and nginx-repo.crt files for your account into the autoscaling-demo ansible files directory.

```bash
git clone git@github.com:nginxinc/NGINX-Demos.git
```

Those two certificate files are the NGINX Plus repository credentials, and the fact that they are copied into a specific demo directory tells you something about the structure: each demo is self contained, and the Plus ones need a licensed repository that open source does not.

The VirtualBox constraint deserves emphasis. The README pins the default provider to those four releases, so the documented default path is a path that likely does not work on a current workstation without adjustment, and you should expect to pick a different Vagrant provider, or a different virtualization approach entirely, before the demos will run for you.

The nginx-docker-builder demo is the exception that avoids all of this. It helps you build a Docker image to deploy NGINX Plus in privileged and unprivileged variants, plus NGINX App Protect WAF and NGINX Agent for NGINX Instance Manager and NGINX One Console. That is a build script, not an infrastructure, so it needs a Docker daemon and a NGINX Plus repository access, and nothing else.

## The older demos are pinned to a generation of tooling

Several demos describe tooling that has moved on, and reading them as documentation rather than as runnable environments is the sane approach.

The nginx-swarm-demo is described as showing how to use NGINX and NGINX Plus in a Docker Swarm, utilising the new features of Docker 1.12. The phrase new features is doing a lot of work in a sentence written when 1.12 was new.

The coreos-demo shows how to use NGINX Plus to load balance an application running in a CoreOS cluster, utilizing fleet and etcd. That is a specific historical moment in container orchestration, and the demo is preserved here rather than maintained.

The mysql-galera-demo uses NGINX Plus as a TCP load balancer for a MySQL Galera cluster of two mysqld servers, doing round robin load balancing between them and active health checks using an xinetd script running on port 9200 inside each mysqld container. The redis-demo is the same shape with three Redis nodes, round robin load balancing, active health checks and advanced logging using nginScript. The mqtt-contiki-demo is a simple MQTT device, a mote, for Contiki OS, to demo with the Cooji simulator.

None of these are wrong. They are snapshots. The pattern to recognise is that the health check and logging demos are still good illustrations of NGINX Plus TCP load balancing, while the orchestration ones document an approach that has since been superseded.

The repository also has a renovate.json at the root, which means the dependency files in these demo directories are still being kept current by automation even where the surrounding scripts have aged.

## Where this repository stops being useful

Three boundaries, and they are structural rather than incidental.

The first is that there is nothing to depend on. There is no package, no library API, no service contract. A demo is a directory of scripts, a configuration and a README paragraph, and you either run it as a whole or you read it. If you need a service discovery integration for NGINX Plus in production, you write it against the upstream_conf API, and this repository is a reference implementation you can read rather than a component you can install. That is a fine thing for it to be, and it is not fine if you assumed otherwise.

The second is the version drift. The demos are pinned to specific NGINX Plus features, specific cloud provider deployment guides and specific container tooling. There are no GitHub releases, so there is no version line to track and no changelog to read, and a demo that worked with a particular Plus release may not work with the current one. Before planning a deployment around a demo, check which NGINX Plus release it was written against.

The third is the mixed audience. The collection is explicitly a set of conference demonstrations, so it mixes infrastructure that teaches a concept, such as the upstream_conf demos, with infrastructure that exists to show a vendor capability, such as the AWS and GCP scripts, with a few utilities like the nginx-regex-tester and the nginx-cookbook, and one honest placeholder, the random-files demo, which the README describes as a demo to show random content and upstream_conf, with a note from the author asking for more description.

That last entry is a fair signal of the whole repository. It is a working notebook, and a notebook is worth reading in a different way from a product. Treat it as a set of worked examples to read, pick the one closest to your problem, and then check the current NGINX documentation for the API as it stands today.

## Conclusion

NGINX-Demos fits an engineer who already knows NGINX and wants to see a specific integration working end to end, whether that is Consul or etcd or Zookeeper driving upstream reconfiguration, or an OAuth 2.0 token introspection setup, or a Docker image build for NGINX Plus. It does not fit a team starting a project, because there is no library, no package and no versioned API here, and several demos are pinned to tooling generations that are long gone. Check three things before you plan around it. Check the toolchain, because most demos are configured for Vagrant with Ansible for autodeployment and the documented default provider supports only VirtualBox versions 4.0 through 4.3. Check whether your problem is one of the covered integrations, because the upstream_conf API is the mechanism behind several of the demos and the ones without it are about deployment rather than reconfiguration. And check the operational age of the demo you want, because the swarm demo cites Docker 1.12 and the CoreOS demo uses fleet and etcd. The last push was on 2026-10-15, the repository has no GitHub releases, and the license is Apache-2.0.

## FAQ

### What is the NGINX-Demos repository?

It is a collection of misc NGINX Demos from conferences showing different functionality of NGINX and NGINX Plus, with around thirty directories, one per demo, several of them using the NGINX Plus upstream configuration API to reconfigure upstreams from a service discovery system without a reload.

### What does the upstream_conf API do in these demos?

It lets NGINX Plus add and remove upstream servers dynamically, without a reload. The consul-api-demo, etcd-demo and zookeeper-demo each use it to follow the servers registered with their respective discovery system, using a bash script and the watch mechanism of each system.

### What are the prerequisites for running the NGINX-Demos?

Most demos are configured to use Vagrant with Ansible for autodeployment. You need Vagrant, a provider, with the default being VirtualBox where only versions 4.0, 4.1, 4.2 and 4.3 are supported, and Ansible. NGINX Plus demos also need the nginx-repo.key and nginx-repo.crt files for your account copied into the demo's ansible files directory.

### What is the difference between the two OAuth2 token introspection demos?

The oss directory is NGINX OAuth 2.0 Token Introspection with disk caching, and the plus directory is the same feature with keyval caching, so the pair isolates what the Plus tier changes.

### Can I run the NGINX-Demos without VirtualBox?

The documentation points to a full list of Vagrant providers if you do not want to use VirtualBox, and some demos need no virtual machine at all, such as the nginx-docker-builder demo for building NGINX Plus images and the nginx-hello container demo.

### What license is the NGINX-Demos repository released under?

Apache-2.0, with a LICENSE file at the root of the repository. The repository has no GitHub releases, and the last push was on 2026-10-15.

## Sources

- [Issues](https://github.com/nginxinc/NGINX-Demos/issues)
- [License: Apache-2.0](https://github.com/nginxinc/NGINX-Demos/blob/master/LICENSE)
- [nginxinc/NGINX-Demos on GitHub](https://github.com/nginxinc/NGINX-Demos)
- [README](https://github.com/nginxinc/NGINX-Demos/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nginxinc-nginx-demos