simplego

simplego is a lightweight, containerized URL redirect and tracking service.
It provides short redirect links that record click events asynchronously and forward users to their destinations instantly.
Designed for minimal setup and easy integration with newsletters, campaign tools, or custom applications.

Purpose

simplego offers:

• Fast and non-blocking HTTP redirects (/go/<redirect_key>/<user_key>)
• Asynchronous visit logging via PostgreSQL or external webhook
• REST API for creating and managing redirect keys
• Optional in-memory caching to reduce database load
• Easy deployment as a single Docker container

Use it anywhere you need to:

• Generate short, trackable URLs for newsletters or campaigns
• Collect analytics on link usage
• Self-host a simple alternative to third-party URL shorteners

Build the Container

Clone or copy the repository, then build the image:

sudo docker build -t simplego .

Database Setup

simplego requires a PostgreSQL database for storing redirect keys and visit logs.

1. Create the Database and User

Run the provided setup script as a PostgreSQL superuser (or your RDS admin user):

psql -U postgres -f SETUP.sql

This will:

• Create a new database called simplego
• Create a user simplego_user with password Trogdor123!
• Create the schema simplego
• Create two tables: redirect_keys and url_visits
• Apply all necessary privileges and sequences

2. Verify the Setup

Once complete, connect to the new database:

psql -U simplego_user -d simplego

Then list tables:

\dt simplego.*

You should see:

List of relations
 Schema  |      Name      | Type  |     Owner
----------+----------------+-------+----------------
 simplego | redirect_keys  | table | simplego_user
 simplego | url_visits     | table | simplego_user

3. Update Your Container Configuration

Set your environment variable in the container run command:

-e 'DATABASE_URL=postgresql://simplego_user:password@<db-host>:5432/simplego'

Run the Container

sudo docker stop redirect-tracker
sudo docker rm redirect-tracker
sudo docker run -d \
  --name redirect-tracker \
  -p 8080:8080 \
  -e 'DATABASE_URL=postgresql://username:password@postgreshost:5432/postgres' \
  -e ADMIN_SECRET="bananajames" \
  -e DEFAULT_REDIRECT="https://rwright.co" \
  -e CACHE_TTL=600 \
  -e PORT=8080 \
  simplego

Then access the service at:

http://<server-ip>:8080/go/<redirect_key>/<user_key>

or create redirects via API:

POST /api/create
Headers: X-Admin-Secret: <your-secret>
Body: { "redirect_key": "example", "dest_url": "https://example.com" }

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	—
ADMIN_SECRET	Secret key for API access	changeme
CACHE_TTL	Cache lifetime in seconds	300
PORT	Container listen port	8080
DEFAULT_REDIRECT	Default / error webpage for redirect	https://google.com