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