sudorandom/protodocs repository overview

⁠protodoc

protodoc is a web-based documentation browser for Protocol Buffer definitions. It allows you to navigate through your .proto files, view message and service definitions, and understand the structure of your APIs.

⁠Running with Docker

⁠1. Running the Pre-built Image from Docker Hub

You can pull and run the pre-built image directly from Docker Hub:

docker run -d -p 8080:80 sudorandom/protodocs:latest

Now open http://localhost:8080 in your web browser.

⁠2. Mounting Custom Descriptors (.binpb) at Runtime

You can mount your own custom serialized protobuf descriptors file (.binpb / .pb) directly into the container at runtime.

To generate a descriptor set from your .proto files using buf or protoc:

# Using buf:
buf build -o my-descriptors.binpb

# Or using protoc:
protoc --descriptor_set_out=my-descriptors.binpb --include_imports your_file.proto

You can then run the Docker container, mounting your descriptor file into the Nginx web root directory:

docker run -d -p 8080:80 \
  -v $(pwd)/my-descriptors.binpb:/usr/share/nginx/html/custom.binpb \
  sudorandom/protodocs:latest

Access your custom documentation in the browser using the query parameter: http://localhost:8080/?descriptors=/custom.binpb