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.
Prerequisites
-
OCI-compatible container runtime (such as Docker, containerd, CRI-O, etc).
-
Docker Compose or compatible alternative (such as Podman).
Download
-
Download Apiman Docker Compose distro 3.1.3.Final and unzip.
-
Refer to
README.adocfor the latest detailed instructions.
Services
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.
-
Apiman Manager UI: http://apiman.local.gd:8080/apimanui
-
Apiman Developer Portal: http://apiman.local.gd:8080/portal
-
Apiman Manager API: http://apiman.local.gd:8080/apiman
-
Apiman Gateway: http://gateway.local.gd:8080
-
Keycloak Admin: http://auth.local.gd:8080/admin
-
Keycloak Auth Endpoint: http://auth.local.gd:8080
-
Elasticsearch: http://elasticsearch.local.gd:8080
-
You may want to edit the docker-compose file and bind port 9200.
-
-
MailDev mock mail service: http://mail.local.gd:8080
-
You can view Apiman email notifications here
-
All mail goes to same mailbox with this mock server
-
You can distinguish between recipients by looking at the
tofield.
-
-
Default user and password for Apiman and Keycloak Admin:
-
Username:
admin -
Password:
admin123!
-
You can edit the values in .env if you want to change hostname bindings, passwords, etc.
Production notes
Apiman
-
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.
Keycloak
-
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.envfile. 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]
Prerequisites
-
Java 11+
-
Keycloak server. Don’t worry, it’s really easy! Here’s a simple guide to get your Keycloak server running and configured in a few clicks.
-
Refer to Migration Guide if upgrading.
-
If you are using Keycloak 16+ (or equivalent), consider setting
--spi-login-protocol-openid-connect-legacy-logout-redirect-uri=trueto ensure logging out works on the developer portal.
-
Configure
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.
Run
-
Ensure your Keycloak server is running, and you know its auth endpoint.
-
If you followed the guide above, it will be
http://localhost:8085
-
-
Start WildFly using the
standalone-apiman.xmlconfiguration:$ bin/standalone.sh -c standalone-apiman.xml \ -Dapiman.auth.url=http://localhost:8085 (1)1 Replace with your Keycloak server auth URL, as appropriate. -
Point your browser at the Apiman UI
http://localhost:8080/apimanuiand log in withadmin/admin123!
| Before transitioning to production, you must you change admin passwords and any default keys by logging into Keycloak. |
Tomcat Quickstart
Apiman on Apache Tomcat.
Prerequisites
-
Java 11+
-
Refer to Migration Guide if upgrading.
Download
-
Download Tomcat 9.0.82 — newer micro versions should also work
Install
-
Unpack the Apache Tomcat zip
-
Unpack the Apiman 3.1.3.Final Tomcat overlay zip inside the tomcat directory
Configure
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!
|
Run
-
Start Tomcat using the default configuration
-
Point your browser at the Apiman UI
http://localhost:8080/apimanuiand log in withadmin/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.
Prerequisites
-
Java 11+
-
Refer to Migration Guide if upgrading.
-
Apiman Manager running (any distribution).
Configure
-
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.adocin the distro zip.
Run
-
Start the Vert.x Gateway using your chosen configuration (e.g. Elasticsearch):
./apiman-gateway.sh --conf configs/conf-es.json -
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.
Prerequisites
-
OCI-compatible container runtime (such as Docker, containerd, CRI-O, etc).
-
You will need Keycloak running.
-
Apiman must be configured to point at Keycloak.
-
Images
-
List of images and container-specific documentation on Apiman Docker @ GitHub.