A simple URL shortener built in Go, featuring a public API, a web interface for shortening URLs, email-based API key authentication, rate limiting, and background job support.
- Shortens URLs via Base62 encoding
- Exposes a public REST API (
POST /api/shorten,GET /:code) - Issues API keys through an email + magic link flow
- Enforces rate limiting and abuse prevention
- Request access via email on the
/apipage - Receive a magic link (valid for 15 minutes, single-use)
- Click the link to activate and receive your API key (shown once)
- Pass the key as an
X-API-Keyheader on API requests
The application is split into:
- API server — request handling, routing, authentication
- Worker — background jobs (e.g. email delivery)
- Redis — rate limiting and caching
- PostgreSQL — persistent storage
- Docker and Docker Compose
- Go 1.25+ (only if running outside Docker)
git clone https://github.com/khalidhaykay/smply.git
cd smplycp .env.example .envOpen .env and fill in the required values (SMTP credentials, app secret, etc.). Make sure APP_ENV=development is set.
The repo ships a base compose.yaml that is production-safe (no volume mounts). For local development, you need a compose.override.yaml that mounts your source code and enables hot reload via Air.
Create compose.override.yaml in the project root:
services:
app:
volumes:
- ./:/app
- go-module-cache:/root/go/pkg/mod
worker:
volumes:
- ./:/app
- go-module-cache:/root/go/pkg/mod
volumes:
go-module-cache:Why is this not committed? The override mounts your local source code into the container, which is only meaningful in development. Keeping it out of the repo ensures the production server can run
docker compose upsafely without any extra flags.
docker compose up --buildDocker Compose automatically merges compose.override.yaml with compose.yaml, so you don't need any extra flags. The app will start with Air watching for file changes and hot-reloading on save.
Open a shell inside the running container:
docker compose exec -it app shThen run the database migration command:
go run ./cmd/cli db:migrateThe app will be available at: http://localhost:8000
| Service | Port | Description |
|---|---|---|
app |
8000 |
Go application |
db |
5432 |
PostgreSQL 16 |
redis |
6379 |
Redis 8 |
On the production server, only compose.yaml is present (no override file). Start the app with:
APP_ENV=production docker compose up --build -dThe Dockerfile detects APP_ENV at build time: in production it compiles the Go binary; in development it installs Air for hot reload. The startup script (start.sh) then runs the appropriate process at container start.
POST /api/shorten
X-API-Key: <your-api-key>
Content-Type: application/json
{
"url": "https://example.com/very/long/url"
}
Response:
{
"short_url": "https://smply.app/aB3xZ"
}GET /:code
Redirects to the original URL.
- API keys and magic tokens are stored hashed (SHA-256); raw values are never persisted
- Magic tokens are single-use and expire after 15 minutes
- Only one active API key and one active magic token per email
- API keys expire after 30 days
- All sensitive configuration (DB credentials, SMTP, secrets) is provided via environment variables and is never committed to the repository
- Admin and protected routes require proper authentication; no security relies on obscurity
- Rate limiting is enforced using Redis to prevent abuse of public endpoints
- Input validation is applied to all incoming requests
- This repository is safe to open source under the assumption that no secrets are exposed and deployment environments are properly configured
This project is licensed under the MIT License — see the LICENSE file for details.