apicurio/apicurio-studio-api

By apicurio

Updated 11 months ago

The API component of the Apicurio Studio application.

Image

50M+

Apicurio API Component

Usage

To start up apicurio/apicurio-studio-api

docker run -it apicurio/apicurio-studio-api:latest-release

You may want to map the port(s) so you can access the app

docker run -it -p 8080:8080 -p 8443:8443 apicurio/apicurio-studio-api:latest-release

How to Configure the Image

There are some configuration options that are imporant when starting up this component. The following is a list of environment variables that you can set (e.g. when starting the docker image):

Env Variable NameDescriptionDefault Value
APICURIO_KC_AUTH_URLThe URL to the Keycloak authentication server.https://studio-auth.apicur.io/auth/
APICURIO_KC_REALMThe name of the Keycloak realm to use for authentication.apicurio
APICURIO_KC_CLIENT_IDThe Client ID of the Keycloak client to use for authentication.apicurio-api
APICURIO_KC_SSL_REQUIREDUsed to determine whether the Keycloak server MUST be accessed via HTTPS.NONE
APICURIO_KC_DISABLE_TRUST_MANAGERSet to true to disable the HTTP client trust manager when accessing Keycloak (used when making HTTPS client calls to Keycloak).true
APICURIO_PORT_OFFSETPort offset to use when starting the server (e.g. set to 10 to shift the http port from 8080 to 8090).0
APICURIO_DB_DRIVER_NAMEDatabase driver name. Possible values: h2, mysql, and postgresql.h2
APICURIO_DB_CONNECTION_URLDatabase (JDBC) connection URL.jdbc:h2:mem:apicuriodb
APICURIO_DB_USER_NAMEDatabase username.sa
APICURIO_DB_PASSWORDDatabase password.sa
APICURIO_DB_INITIALIZESet to true if Apicurio should initialize the database (set to false if a DBA will do this).true
APICURIO_DB_TYPEDatabase type. Valid values: h2, postgresql9, mysql5h2
APICURIO_LOGGING_LEVELDefault logging level.INFO
APICURIO_MIN_HEAPMinimum java heap setting.768m
APICURIO_MAX_HEAPMaxiumum java heap setting.2048m
APICURIO_GITHUB_API_URLURL of the GitHub API.https://api.github.com
APICURIO_GITLAB_API_URLURL of the GitLab API.https://gitlab.com
APICURIO_BITBUCKET_API_URLURL of the Bitbucket API.https://api.bitbucket.org/2.0

For example, if you wish to use a custom Keycloak client but leave all other settings as defaults, you could start the docker image like this:

docker run -it -p 8080:8080 -p 8443:8443 \
	-e "APICURIO_KC_AUTH_URL=https://keycloak.example.com/auth/" \
	-e "APICURIO_KC_REALM=my-apicurio" \
	apicurio/apicurio-studio-api:latest-release

Note: you will typically need to at least customize the Database settings so that all of the Apicurio components (API, WS, and UI) point to the same shared database instance (typically mysql or postgresql).

That might look like this:

docker run -it -p 8080:8080 -p 8443:8443 \
	-e "APICURIO_KC_AUTH_URL=https://keycloak.example.com/auth/" \
	-e "APICURIO_DB_DRIVER_NAME=postgresql" \
	-e "APICURIO_DB_CONNECTION_URL=jdbc:postgresql://db.example.com:5432/apicuriodb" \
	-e "APICURIO_DB_TYPE=postgresql9" \
	-e "APICURIO_DB_USER_NAME=dbuser" \
	-e "APICURIO_DB_PASSWORD=dbpassword123" \
	apicurio/apicurio-studio-api:latest-release

Requirements

The apicurio/apicurio-studio-api component is only one of several components that make up the Apicurio Studio application. For Apicurio Studio to fully function, the following components are required:

ComponentDescriptionDocker Image
APIThe REST API based backend. Used by the UI for most operations.apicurio/apicurio-studio-api
EditingThe Web Socket based concurrent editing layer. Used by the UI only when editing an API.apicurio/apicurio-studio-ws
UIThe Angular based UI. Users go here to access the Apicurio UI.apicurio/apicurio-studio-ui
AuthKeycloak server to provide authentication and account linking functionality.apicurio/apicurio-studio-auth

Note: you can install/run/configure your own Keycloak server if you already have one or don't want to use the apicurio/apicurio-studio-auth image.

Docker Pull Command

docker pull apicurio/apicurio-studio-api