Apiman Docker Compose Quickstart

This quickstart lets you try Apiman with an architecture that is more representative of a real-world deployment.

It is composed of independent containers for Apiman Manager, Apiman Gateway (Vert.x), Keycloak, PostgreSQL, and Elasticsearch. A mock mail server is also included to allow you to test Apiman’s email notifications in a safe way.

This distribution is new in Apiman 3. We need your feedback!


  • OCI-compatible container runtime (such as Docker, containerd, CRI-O, etc).

  • Docker Compose or compatible alternative (such as Podman).



  1. docker-compose -f docker-compose.setup.yml up

  2. docker-compose up

  3. http://apiman.local.gd:8080/apimanui


We use local.gd to make DNS mappings easier when using localhost. If you can’t use local.gd, simply edit .env and change APIMAN_HOSTNAME to you preferred alternative.

You can edit the values in .env if you want to change hostname bindings, passwords, etc.

Production notes


  • Assuming you are terminating TLS/SSL on Apiman, the demo self-signed certificates, keystores, truststores, etc., should be replaced with your organisation’s versions.

  • Components for such as Postgres and Elasticsearch likely should be run in a multi-node setup to provide high levels of resilience and redundancy. You should make some considerations for backups, etc.


  • For a real deployment, please run Keycloak in production mode. For this quickstart Keycloak runs in dev-mode, which is very permissive and tolerant of self-signed certs, etc. — but it is inappropriate for real-world deployments. Refer to the Keycloak production guide.

  • You must change the default usernames and/or passwords before going to production.

  • Keys are generated and stored in data/keys, and then copied into the .env file. Storing keys in plaintext is not usually advised for a production environment; you should consider using a dedicated secrets storage and injection mechanism. For example, Hashicorp Vault or K8s secrets.

WildFly Quickstart

This quickstart includes a WildFly Apiman Manager and a WildFly Apiman Gateway.

As of Apiman 3, you need to download and run Keycloak separately. [1]



  1. Unpack WildFly

  2. Unpack Apiman zip overlay inside the wildfly directory


Refer to our configuration guide to see all the ways you can configure Apiman. This contains instructions for how to set up external databases, auth, metrics, email notifications, and much more.


  1. Ensure your Keycloak server is running, and you know its auth endpoint.

  2. Start WildFly using the standalone-apiman.xml configuration:

    $ bin/standalone.sh -c standalone-apiman.xml \
        -Dapiman.auth.url=http://localhost:8085 (1)
    1 Replace with your Keycloak server auth URL, as appropriate.
  3. Point your browser at the Apiman UI http://localhost:8080/apimanui and log in with admin/admin123!

Before transitioning to production, you must you change admin passwords and any default keys by logging into Keycloak.

1. It is no longer possible to bundle both platforms into the same WildFly instance.

Tomcat Quickstart

Apiman on Apache Tomcat.




  1. Unpack the Apache Tomcat zip

  2. Unpack the Apiman 3.1.3.Final Tomcat overlay zip inside the tomcat directory


This distribution comes pre-configured with everything you should need to get started.

Please see the Installation and User Guide for information about how to change Apiman configuration options if you require more customization.

It is possible to use Keycloak instead of Tomcat auth by adding the Keycloak Tomcat valve, but this is an exercise left to the reader.

We strongly recommend you change the admin password in tomcat-users.xml!


  1. Start Tomcat using the default configuration

  2. Point your browser at the Apiman UI http://localhost:8080/apimanui and log in with admin/admin123!

Vert.x Gateway Quickstart

The Apiman Vert.x Gateway is our premier gateway implementation, offering the best performance and smallest footprint. If you need better throughput and lower latency, this is likely the choice for you.

This implementation is gateway only; you need to run an Apiman Manager separately.


  • Java 11+

  • Refer to Migration Guide if upgrading.

  • Apiman Manager running (any distribution).


  • Unpack the Vert.x Gateway zip


  • Refer to the installation guide for detailed configuration instructions.

  • The Vert.x gateway is configured through a JSON file rather than properties.

  • Refer to the README.adoc in the distro zip.


  1. Start the Vert.x Gateway using your chosen configuration (e.g. Elasticsearch):

    ./apiman-gateway.sh --conf configs/conf-es.json
  2. Install one gateway to your Apiman Manager via the administration console or REST API. A walkthrough is available in our installation guide.

    • Generally only one instance from a given cluster needs to be installed into the Apiman Manager (e.g. staging cluster, production cluster, etc).

Apiman Containers

Previously, we published our images to DockerHub only. As of Apiman 3, our canonical repository is the Apiman GitHub Container Registry (GHCR), but we will continue publishing to DockerHub for now.


  • OCI-compatible container runtime (such as Docker, containerd, CRI-O, etc).

  • You will need Keycloak running.



  • Typically, you will want to map at least port 8080 (HTTP) and 8443 (HTTPS).

Please refer to the Apiman Docs.