Gondola

June 23, 2026 · View on GitHub

Gondola

A simple and flexible reverse proxy written in Go

Features

Lightweight and fast execution
Simple configuration file (YAML)
Static file hosting
Fallback support
Custom error pages
Virtual host support
Graceful shutdown
Hot configuration reload (SIGHUP)
Access log reopen for rotation (SIGUSR1)
Detailed access logs (nginx-compatible)
Structured access logs (JSON)
TLS/SSL support (TLS 1.2+)
Trace ID support
Timeout control

Installation

Go

go get github.com/bmf-san/gondola

Binary

Download the latest binary from the Releases page.

Docker

docker pull bmfsan/gondola
docker run -v $(pwd)/config.yaml:/etc/gondola/config.yaml bmfsan/gondola

Usage

Command Line Options

Usage: gondola [options]

Options:
  -config string    Path to configuration file (default: config.yaml)
  -version          Display version information
  -help             Show help

Environment Variables

The following environment variables can override command line options:

GONDOLA_CONFIG: Path to the configuration file
GONDOLA_LOG_LEVEL: Log level (debug, info, warn, error)

Signal Handling

Gondola handles the following signals:

SIGTERM, SIGINT: Graceful shutdown
SIGHUP: Reload configuration file
SIGUSR1: Reopen access logs

Configuration File

proxy:
  port: "8080"
  read_header_timeout: 2000  # milliseconds
  read_timeout: 30000        # milliseconds
  write_timeout: 30000       # milliseconds
  idle_timeout: 60000        # milliseconds
  shutdown_timeout: 3000     # milliseconds
  max_header_bytes: 1048576  # bytes (1 MiB)
  # tls_cert_path: /path/to/cert.pem
  # tls_key_path: /path/to/key.pem
  # log_file: /var/log/gondola/access.log  # default: stdout
  static_files:
    - path: /public/
      dir: /path/to/public
      fallback_path: 404.html  # relative to dir
  # error_pages:               # custom pages by status (relative to first static dir)
  #   404: /404.html
  #   "500 502 503 504": /50x.html
  #   default: /error.html

upstreams:
  - host_name: api.example.com
    target: http://localhost:3000
    read_timeout: 5000      # milliseconds (upstream response header timeout)
    write_timeout: 5000     # milliseconds (upstream connection timeout)
  - host_name: web.example.com
    target: http://localhost:8000

log_level: "info"           # debug, info, warn, error
log_format: "json"          # json, common, combined, custom
# log_custom_format: '${remote_ip} ${method} ${uri} ${status} ${request_time}'

Startup Examples

Basic startup:

gondola -config config.yaml

Start in debug mode:

GONDOLA_LOG_LEVEL=debug gondola -config config.yaml

Start with Docker:

docker run -v $(pwd)/config.yaml:/etc/gondola/config.yaml \
          -p 8080:8080 \
          bmfsan/gondola

Start with systemd:

[Unit]
Description=Gondola Reverse Proxy
After=network.target

[Service]
ExecStart=/usr/local/bin/gondola -config /etc/gondola/config.yaml
Restart=always
Environment=GONDOLA_LOG_LEVEL=info

[Install]
WantedBy=multi-user.target

Access Logs

Gondola outputs detailed access logs compatible with nginx.

Log Format

The access log format is selectable via log_format:

json (default) — structured JSON via slog
common — Apache Common Log Format
combined — Apache Combined Log Format
custom — a template using ${...} variables (set via log_custom_format)

Custom variables: ${timestamp}, ${remote_ip}, ${method}, ${uri}, ${protocol}, ${status}, ${user_agent}, ${referer}, ${request_time}, ${trace_id}.

Log Fields

Client Information

remote_addr: Client IP address
remote_port: Client port number
x_forwarded_for: X-Forwarded-For header

Request Information

method: HTTP method (GET, POST, etc.)
request_uri: Full request URI
query_string: Query parameters
host: Host header
request_size: Request size

Response Information

status: HTTP status
body_bytes_sent: Response body size
bytes_sent: Total response size
request_time: Request processing time (seconds)

Upstream Information

upstream_addr: Backend address
upstream_status: Backend status
upstream_size: Backend response size
upstream_response_time: Backend response time (seconds)

Other Headers

referer: Referer header
user_agent: User-Agent header

Log Output Example

{
  "level": "INFO",
  "msg": "access_log",
  "remote_addr": "192.168.1.100",
  "remote_port": "54321",
  "x_forwarded_for": "",
  "method": "GET",
  "request_uri": "/api/users",
  "query_string": "page=1",
  "host": "api.example.com",
  "request_size": 243,
  "status": "OK",
  "body_bytes_sent": 1532,
  "bytes_sent": 1843,
  "request_time": 0.153,
  "upstream_addr": "localhost:3000",
  "upstream_status": "200 OK",
  "upstream_size": 1532,
  "upstream_response_time": 0.142,
  "referer": "https://example.com",
  "user_agent": "Mozilla/5.0 ...",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Projects

The gondola's board

ADR

Contribution

We welcome issues and pull requests at any time.

Feel free to contribute!

Before contributing, please check the following documents:

License

This project is licensed under the MIT License.

LICENSE

Stargazers

Forkers

Author

bmf-san