docker-buf

Extended Docker image for Buf with comprehensive protoc plugin support.

Based on the official bufbuild/buf Docker image, this image includes additional protoc plugins for generating code in multiple languages and formats

Plugins included:

• gRPC-Go
• protoc-gen-doc
• protoc-gen-go
• protoc-gen-grpc-gateway
• protoc-gen-openapiv2
• protoc-gen-go
• protoc-gen-go-grpc
• protoc-gen-validate
• protoc-gen-ts_proto
• protoc-gen-grpc-web
• gRPC-python
• protocolbuffers-python
• protoc-gen-bruno - Generates Bruno API collections

Quick Start

# Generate code using the Docker image
make docker-buf

# Or run manually
docker build -t docker-buf:latest .
docker run --rm -v $(pwd):/mnt/pwd -w /mnt/pwd docker-buf:latest generate --template buf.gen.yaml --path api

Available Make Targets

make help          # Show all available targets
make docker-buf    # Build Docker image and generate code
make buf-build     # Update buf dependencies and build
make swagger-ui    # Start Swagger UI in Docker
make clean         # Clean all generated files

Directory / File Structure

api/book/v1/book.proto     # Example .proto file
docs/generated/
  template.gotmpl            # Doc API template
book.config.swagger.yaml     # Swagger config
buf.gen.yaml                 # Code generation config (v2)
buf.work.yaml
buf.yaml                     # Buf config (v2)
Dockerfile                   # Multi-stage build
docker-compose.yaml
Makefile
README.md

• buf-gen-yaml
• buf-work-yaml
• buf-yaml

Bufbuild installation & configuration for local development

1. Installation: https://docs.buf.build/installation
2. make buf-build
3. To make your editor recognize Buf modules(external library) follow this instructions: https://docs.buf.build/editor-integration

To compile proto files for the application, run the following command (can be run without bufbuild configured locally):

make docker-buf

Bruno API Collections

The generated Bruno API collections will be available in bruno/collections/ directory. To use them:

1. Open Bruno
2. Click "Open Collection"
3. Navigate to bruno/collections folder
4. Select environment (Local, Development, Staging, Production)

The collections include:

• HTTP requests from google.api.http annotations
• gRPC requests from service definitions
• Auto-generated example request bodies
• Multi-environment support (Dev, Staging, Production)

Configuration Files

buf.yaml

The main Buf configuration file using v2 format with:

• External dependencies from Buf Schema Registry
• Standard linting rules
• Breaking change detection

buf.gen.yaml

Code generation configuration using v2 format with:

• Managed mode enabled for consistent package names
• Multiple plugin configurations for different languages
• Environment-specific settings

Requirements

• Docker (with Compose v2)
• Make (optional, but recommended)
• For local development: Buf CLI

Troubleshooting

Permission Issues

If you encounter permission issues with generated files:

make clean
sudo make docker-buf

Docker Build Fails

Ensure you have the latest Docker version:

docker --version  # Should be 20.10+
docker compose version  # Should be v2+

Node Dependencies

If npm dependencies are out of date:

npm install
make docker-buf

Version Information

• Buf: 1.71.0
• Go: 1.26
• Node: 22 Alpine
• Configuration: v2 format

Contributing

Issues and pull requests are welcome! Please check the issue tracker.

License

MIT License