README
¶
Shortener
A simple URL shortener application built with Go, Echo, and PostgreSQL.
Getting Started
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
Prerequisites
- Go 1.25+
- Docker
- sqlc
- golangci-lint
- Air (Optional)
SQL Queries
SQL queries are implemented using sqlc. Use the sqlc generate command to generate the Go code for the SQL queries.
Just
List of available just commands
just
Running the application
Set up Git hooks
sh install-hooks.sh
Install dependencies
go mod tidy
Fill out .env file with the required environment variables
cp .env.example .env
Run the required services in Docker
docker compose up -d db valkey otel-collector
# or
just docker-up
Run the application
just run
# or
just watch # run the app with live reload
Build/Run commands
Build the application
just build
Build the application for development
just build-dev
Live reload the application (with Air)
just watch
Clean up binary from the last build:
just clean
DB Migrations
Create a new migration file
just migrate-new name
Apply all migrations
just migrate-up
Rollback the last migration
just migrate-down
Migrate to a specific version
just migrate-force version
Show the current migration version
just migrate-version
Observability
Traces, metrics, and logs are collected via an OpenTelemetry Collector and exported to Grafana Cloud.
Set the following variables in your .env before starting the collector:
| Variable | Where to find it |
|---|---|
GRAFANA_CLOUD_OTLP_ENDPOINT |
Grafana Cloud → Connections → Add new connection → OpenTelemetry (OTLP) |
GRAFANA_CLOUD_INSTANCE_ID |
Your numeric stack/instance ID on the same page |
GRAFANA_CLOUD_API_KEY |
A Grafana Cloud API token with MetricsPublisher, LogsPublisher, and TracesPublisher scopes |
The collector exposes:
- Health check —
http://localhost:13133 - zPages (pipeline diagnostics) —
http://localhost:55679/debug/tracez
Quality Control
Audit the application for vulnerabilities, code quality, and dependency issues
just audit
Run all tests, including DB integration tests (made with testcontainers)
just test
Run all tests and display coverage
just test-cover
List direct dependencies that have upgrades available
just upgradeable
Tidy module dependencies and format .go files
just tidy
Directories