English 日本語

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

1. Client Information

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

2. Request Information

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

3. Response Information

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

4. Upstream Information

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

5. 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

• ADR

Contribution

We welcome issues and pull requests at any time.

Feel free to contribute!

Before contributing, please check the following documents:

• CODE_OF_CONDUCT
• CONTRIBUTING

Sponsors

If you like this project, consider sponsoring us!

Github Sponsors - bmf-san

Alternatively, giving us a star would be appreciated!

It helps motivate us to continue maintaining this project. :D

License

This project is licensed under the MIT License.

LICENSE

Stargazers

Forkers

Author

bmf-san

• Email
  • bmf.infomation@gmail.com
• Blog
  • bmf-tech.com
• Twitter
  • bmf-san