Sign inSign up

aeciopires/gofipe

By aeciopires

•Updated 2 days ago

A web application that provides an interface to search the Brazilian FIPE vehicle price table

Image
1

9.3K

aeciopires/gofipe repository overview

⁠gofipe

A lightweight web application to search the Brazilian FIPE vehicle price table (cars, motorcycles and trucks), shipped as a single, self-contained Go binary in a small, secure, multi-arch Docker image.

Source code: https://github.com/aeciopires/gofipe⁠

gofipe screenshot

⁠Table of Contents

⁠Quick start

docker pull aeciopires/gofipe:latest
docker run -d -p 8080:8080 --rm --name gofipe aeciopires/gofipe:latest

Then open http://localhost:8080⁠ in your browser.

Recommended for production — see the CHANGELOG⁠.

Platforms: linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 (runs on servers, Apple Silicon and Raspberry Pi).

⁠Features

  • FIPE price lookup: choose vehicle type, brand, model and year to get the current FIPE price, FIPE code, fuel and reference month.
  • Real price history: chart with the real monthly history from the FIPE API v2 (up to 24 months with a token; about 3 months on the free tier).
  • Day/night theme: client-side light/dark toggle.
  • BFF (Backend for Frontend): the Go backend proxies the FIPE API v2⁠, hiding upstream details from the browser.
  • Input validation: vehicle type and IDs are validated before reaching the FIPE API (no path/query injection).
  • Smart in-memory cache: TTL cache for brands/models (12h), years (24h), prices (1h) and history (6h), with periodic cleanup.
  • Robust error handling: meaningful HTTP status codes (400/404/429/502/504) without leaking internal details.
  • Production-ready server: HTTP timeouts and graceful shutdown on SIGTERM (readiness switches to 503 and the server drains for SHUTDOWN_DELAY).
  • Health checks: /health/live (liveness/startup), /health/ready (readiness) and /health (Docker HEALTHCHECK).
  • Prometheus metrics: Go runtime/process metrics, per-route request counter and latency histogram with trace exemplars, plus business metrics (most searched brands/models/years, min/max prices, fuel types).
  • Structured JSON logs: one JSON object per line via log/slog, with trace_id/span_id correlation and a JSON access log per request.
  • OpenTelemetry: traces and logs exported via OTLP/HTTP, enabled with the standard OTEL_EXPORTER_OTLP_ENDPOINT variable.
  • Self-contained binary: HTML, CSS and JavaScript embedded with go:embed — no extra files needed.
  • Secure image: Alpine-based, runs as non-root (UID 10001), compatible with a read-only root filesystem, scanned with Trivy.
  • Ready for Kubernetes: a Helm 4 chart⁠ is included in the repository.

⁠How to use

⁠Run with Docker
docker run -d -p 8080:8080 --rm --name gofipe aeciopires/gofipe:latest

Follow the JSON logs:

docker logs -f gofipe

Use a different port:

docker run -d -p 9000:9000 -e PORT=9000 --rm --name gofipe aeciopires/gofipe:latest
⁠Run with a FIPE API token

The public FIPE API works without a key. A subscription token from https://fipe.online⁠ raises rate limits and allows a longer price history:

docker run -d -p 8080:8080 --rm --name gofipe \
  -e FIPE_API_TOKEN="<your-token>" \
  aeciopires/gofipe:latest
⁠Run with Docker Compose
services:
  gofipe:
    image: aeciopires/gofipe:latest
    container_name: gofipe
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      # - FIPE_API_TOKEN=<your-token>
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
docker compose up -d

Want metrics, logs and traces out of the box? The repository includes a full local observability stack (OpenTelemetry Collector, Prometheus, Loki, Tempo, Jaeger and Grafana with provisioned dashboards):

git clone https://github.com/aeciopires/gofipe.git
cd gofipe/app
docker compose up -d --build

Grafana will be available at http://localhost:3000⁠ (admin / admin), with dashboards in the gofipe folder.

⁠Enable OpenTelemetry tracing

Point the container to any OTLP/HTTP endpoint (OpenTelemetry Collector, Tempo, Jaeger, etc.):

docker run -d -p 8080:8080 --rm --name gofipe \
  -e OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318" \
  -e OTEL_SERVICE_NAME="gofipe" \
  aeciopires/gofipe:latest
⁠Deploy on Kubernetes
git clone https://github.com/aeciopires/gofipe.git
cd gofipe/helm-chart
helm upgrade --install gofipe . --namespace gofipe --create-namespace --wait
kubectl port-forward svc/gofipe 8080:80 -n gofipe

The chart requires Helm 4 and Kubernetes >= 1.29. See the chart README⁠ for all options (Ingress, HPA, PodDisruptionBudget, ServiceMonitor, etc.).

⁠Environment variables

VariableDefaultDescription
PORT8080HTTP port the server listens on.
FIPE_BASE_URLhttps://fipe.parallelum.com.br/api/v2Base URL of the FIPE API v2.
FIPE_API_TOKEN(empty)Optional subscription token from https://fipe.online⁠ (sent as X-Subscription-Token).
SHUTDOWN_DELAY0sTime to keep serving after SIGTERM while /health/ready returns 503 (e.g. 5s).
OTEL_EXPORTER_OTLP_ENDPOINT(empty)OTLP/HTTP endpoint. When set, traces and logs are exported with OpenTelemetry.
OTEL_SERVICE_NAMEgofipeService name reported in traces and logs.
OTEL_RESOURCE_ATTRIBUTES(empty)Extra resource attributes (e.g. deployment.environment.name=prod).
OTEL_SDK_DISABLEDfalseSet to true to disable OpenTelemetry export.

⁠Endpoints

System

MethodEndpointDescription
GET/Web UI.
GET/health{"status": "ok"} — used by the Docker HEALTHCHECK.
GET/health/liveLiveness: {"status": "ok"}.
GET/health/readyReadiness: {"status": "ok"}, or 503 {"status": "unavailable"} while starting/shutting down.
GET/metricsPrometheus / OpenMetrics format (with exemplars).

Business API

MethodEndpointQuery parametersDescription
GET/api/brandstype (cars, motorcycles, trucks; default cars)Lists brands.
GET/api/modelstype, brandIdLists models of a brand.
GET/api/yearstype, brandId, modelIdLists available years of a model.
GET/api/pricetype, brandId, modelId, yearIdReturns the current FIPE price.
GET/api/priceHistorytype, brandId, modelId, yearId, months (1–24, default 12)Returns {"history": [...]}, newest first.

Example:

curl "http://localhost:8080/api/brands?type=cars"

⁠Prometheus metrics

MetricTypeDescription
fipe_http_requests_totalCounterHTTP requests by route and method.
fipe_http_request_duration_secondsHistogramRequest latency by route, method and status code, with trace_id exemplars.
fipe_search_statsCounterSearches by brand, model and year.
fipe_price_min / fipe_price_maxGaugeLowest / highest price observed.
fipe_fuel_countCounterSearches by fuel type.
fipe_brand_search_countCounterSearches by brand.

Standard Go runtime and process metrics are also exposed.

⁠Image details

  • Base image: Alpine Linux (runtime), built with the official golang Alpine image (multi-stage).
  • User: non-root, UID/GID 10001.
  • Exposed port: 8080.
  • Healthcheck: built-in HEALTHCHECK on /health.
  • Filesystem: the app writes nothing to disk, so --read-only works.
  • Security: each release is scanned with Trivy⁠; Go code checked with golangci-lint and govulncheck.

⁠Contributing and support

If this project is useful to you, please give it a ⭐ on GitHub!

⁠License

Released under the GNU General Public License v3.0⁠.

Tag summary

Content type

Image

Digest

sha256:147b8ea48…

Size

10.3 MB

Last updated

2 days ago

docker pull aeciopires/gofipe