ScratchPad

A server-rendered Go web application for creating and sharing self-destructing text snippets. Sign up, log in, publish a snippet with a title and content, and choose how long it lives (1 day, 1 week, or 1 year) before it disappears.

Features

• Create and view text snippets with an expiry date (1 day, 1 week, or 1 year)
• Home page lists the 10 most recent snippets that haven’t expired
• User authentication: signup, login, and logout
• Passwords hashed with bcrypt (cost 12)
• Session-based authentication (sessions stored in PostgreSQL)
• CSRF protection on all POST forms
• HTTPS/TLS with a hardened TLS 1.3 configuration
• Security headers (CSP, nosniff, frame protection, etc.)
• Flash messages on form submission
• JSON structured logging via log/slog
• Prometheus metrics exposed on a separate port with bounded-cardinality labels
• Static assets and templates embedded into the binary via embed
• Schema managed by golang-migrate; applied automatically in the container stack

Tech Stack

Getting Started

Prerequisites

• Go 1.26+
• Podman with podman-compose (or any Docker Compose v2 compatible tool)
• PostgreSQL 17 (via the compose stack, or locally for bare-metal development)

Option A — Full containerized stack (recommended)

podman-compose up -d --build

This builds the app image plus a small migrator image, applies all migrations once the database is healthy, then starts everything else:

The credentials above are development dummies hardcoded in docker-compose.yml. Change them before exposing this stack anywhere.

The app container mounts ./tls read-only and expects cert.pem/key.pem inside — generate them first (next section) if you don’t have them yet.

Option B — Local development (bare metal)

1. Generate TLS certificates

The server only speaks HTTPS and expects certificates at ./tls/cert.pem and ./tls/key.pem (both are gitignored):

mkdir -p tls
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout tls/key.pem -out tls/cert.pem -days 365 \
  -subj "/CN=localhost"

2. Start PostgreSQL

Either use just the database from the compose stack:

make compose-up          # or: podman-compose up -d db

or point at any existing PostgreSQL instance via DSN.

3. Apply migrations

make migrate-up          # uses ~/go/bin/migrate if not on PATH
# rollback one step: make migrate-down

Raw CLI equivalent:

migrate -path=./migrations \
  -database="postgres://scratchpad:password@localhost/scratchpad?sslmode=disable" up

4. Run the app

make run

Then open https://localhost:8080 (accept the self-signed certificate warning). Metrics are served separately on http://localhost:8081/metrics.

Configuration

Every setting is a CLI flag with an environment-variable fallback:

Note: the app serves over HTTPS only. Sessions and CSRF cookies are marked Secure, so the site won’t function over plain HTTP.

Routes

Metrics

Metrics live on their own listener (default :8081) behind a dedicated Prometheus registry, so scrape traffic never touches the application mux.

The endpoint label is the matched route pattern (e.g. GET /pads/view/{id}), never the raw request path — parameterized URLs can’t blow up label cardinality. Requests that don’t match any route are labeled unmatched. Panics recovered by middleware still produce a recorded 500 series, and the active-request gauge is decremented even on panic paths.

Grafana’s Prometheus datasource is provisioned automatically from grafana/datasources.yaml; the scrape config lives in prometheus/prometheus.yml.

Database & Migrations

Three tracked migrations create the schema: pads, users (unique email constraint), and sessions (token/data/expiry used by scs’s postgresstore).

make migrate-up     # apply all pending
make migrate-down   # roll back the latest
DSN="postgres://user:pass@host/dbname?sslmode=disable" make migrate-up   # custom target

In the container stack, the one-shot migrate service runs automatically before the app starts (depends_on: service_completed_successfully), so podman-compose down && podman-compose up re-applies pending migrations safely.

Tests

make test         # verbose go test ./...
make test-race    # race detector, no caching (same as CI)

• cmd/web — handler, middleware, template, and metrics tests run fully offline against model mocks (httptest + embedded templates).
• internal/models — data-layer integration tests that connect to PostgreSQL at the default local DSN. Their fixtures reset the users, pads, and sessions tables of the target database, so run them against a disposable database.
• CI (.github/workflows/ci.yml) builds, vets, and runs the whole suite with -race against a postgres:17 service container.

Project Structure

cmd/web/              Web application entrypoint: main, routes, handlers,
                      middleware, helpers, templates, context keys
internal/metrics/     Prometheus collectors, registry wiring, /metrics handler
internal/models/      Data access layer for pads and users, sentinel errors,
                      and mocks used by offline tests
internal/validator/   Form validation helpers (embedded in form structs)
internal/assert/      Tiny generic test assertion helpers
migrations/           golang-migrate SQL migrations (up/down pairs)
prometheus/           Scrape config mounted into the Prometheus container
grafana/              Datasource provisioning mounted into Grafana
ui/                   Embedded HTML templates, static CSS, and assets (embed.FS)
Dockerfile            Multi-stage build for the web binary
Containerfile.migrate Builds the pinned golang-migrate CLI image
docker-compose.yml    Full stack: db, migrate, scratchpad, prometheus, grafana, pgadmin
Makefile              Common dev tasks
tls/                  TLS certificates (gitignored)

Makefile Targets