Skip to content
Last updated

Use Redoc CE Docker image

Redoc CE is available as a pre-built Docker image in Docker Hub. The image serves the standalone HTML page with nginx and takes its configuration from environment variables.

Before you begin

Make sure you have Docker installed.

Build API documentation

  1. Pull the image with the following command:

    docker pull redocly/redoc

  2. Run the image:

    docker run -p 8080:80 redocly/redoc

The preview starts on port 8080, based on the port used in the command. You can access the preview at http://localhost:8080.

To exit the preview, press control+C.

Change the API description file

A version of the Redocly Museum API is displayed by default.

You can change the description file used in the project: either a local file, or a URL. The description can be an OpenAPI, AsyncAPI, or GraphQL file, see Supported specifications.

URL

To change the URL of the description file:

  • Pass the URL to your description in the SPEC_URL environment variable.

For example:

docker run -p 8080:80 -e SPEC_URL=https://api.example.com/openapi.json redocly/redoc

The same variable serves an AsyncAPI document or a GraphQL schema:

docker run -p 8080:80 -e SPEC_URL=https://redocly.github.io/redoc/3.x/specs/cafe-asyncapi-amqp.yaml redocly/redoc

Local file

To run a local file:

  1. Mount the file into the nginx web root, /usr/share/nginx/html, where:

    • $(pwd)/cafe.yaml is the path to the description file on your machine
    • /usr/share/nginx/html/cafe.yaml is the path inside the container

  2. Set SPEC_URL to the file path relative to the web root:

    docker run -it --rm -p 8080:80 \
  -v $(pwd)/cafe.yaml:/usr/share/nginx/html/cafe.yaml \
  -e SPEC_URL=cafe.yaml redocly/redoc

$(pwd) is the directory where you run Docker. In the example above, Docker runs from the folder that contains cafe.yaml.

To serve several files, mount a folder instead: -v $(pwd)/specs/:/usr/share/nginx/html/specs/ together with -e SPEC_URL=specs/openapi.yaml.

Configure the container

VariableDescription
SPEC_URLURL or path of the API description. Default: https://cdn.redocly.com/redoc/museum-api.yaml.
REDOC_OPTIONSConfiguration options written as <redoc> attributes, for example layout="stacked" disable-telemetry="true". The value is inserted into the <redoc> element as written.
PAGE_TITLETitle of the HTML page. Default: ReDoc.
PAGE_FAVICONURL of the page favicon. Default: favicon.png, an icon shipped with the image.
BASE_PATHPath prefix to serve the documentation under, without slashes. For example, docs serves the page at /docs. Not set by default.
PORTPort nginx listens on inside the container. Default: 80.
HOSTnginx server_name. Default: localhost.

Pass configuration options

Pass any configuration option in REDOC_OPTIONS, using the same kebab-case attributes as the HTML element:

docker run -p 8080:80 \
  -e SPEC_URL=https://api.example.com/openapi.json \
  -e REDOC_OPTIONS='layout="stacked" sort-required-props-first="true" disable-telemetry="true"' \
  redocly/redoc

Serve under a path prefix

Set BASE_PATH to serve the documentation from a sub-path, for example behind a reverse proxy. The bundle, favicon, and stylesheet are then served under the prefix. A local description file must be referenced with the prefix as well:

docker run -p 8080:8080 \
  -e PORT=8080 \
  -e BASE_PATH=docs \
  -v $(pwd)/cafe.yaml:/usr/share/nginx/html/cafe.yaml \
  -e SPEC_URL=/docs/cafe.yaml \
  redocly/redoc

The documentation is available at http://localhost:8080/docs. Deep links use hash routing by default, so the prefix needs no extra nginx configuration.

Create a Dockerfile

You can also build your own image, for example to bake in environment variables or to ship a description file inside the image. Check out the Dockerfile in the Redoc CE repository, in the config/docker folder.

Resources

Use Redocly CLI with Redoc CE