URL Shortener

A simple URL shortening web application built with Flask.

Supports web-browsers and cli (e.g. curl) for shortening URLs.

Features

• Shorten long URLs to shorter ones
• Redirect shortened URLs to the original long URLs
• Simple and user-friendly web interface
• CLI support for URL shortening
• QR code generation for shortened URLs

Screenshots

Main Page

Shortened URL Display Web browser

Shortened URL Display CLI

$ curl "http://localhost:8088/shortener?url-string=https://example.com"

In this scenario the application looks for User-Agent header to determine the type of client. CLI clients (like curl) currently supported are:

• curl
• httpie
• wget

Alternatively, you can explicitly request CLI output by requesting shortener-cli path:

$ curl "http://localhost:8088/shortener-cli?url-string=https://example.com"

Architecture

The application is built using the Flask web framework and packed with Docker and docker-compose for easy deployment.

Repo content & Application components

• shortener_flask_app/: Main Flask application code
  • app/: Application package
    • routes.py: Defines the web routes and their handlers
    • models.py: Database models for storing URLs
    • utils.py: Utility functions
    • database.py: Database setup
    • cache.py: Caching setup
    • consts.py: Application constants
  • static/: Static files (CSS, JS, images)
    • main.css: Main stylesheet
  • templates/: HTML templates
    • index.html: Main page template
    • shortened.html: Shortened URL display template
  • tests/: Unit and integration tests for the application
  • config.py: Application configuration
  • factory.py: Application factory
  • gunicorn_cfg.py: Gunicorn configuration for production deployment
  • __main__.py: Entry point for running the application with uv
• Dockerfile: Dockerfile for building the application image
• compose.yml: Docker Compose configuration for running the application and all its other components (database, cache, proxy)
• README.md: This readme file
• docs/: Documentation files and diagrams
• nginx.conf: Nginx configuration file for reverse proxy
• .python-version: Python version file for pyenv
• example.env: Example environment variables file
• uv.lock: uv lock file for dependencies
• pyproject.toml: uv configuration file for dependencies
• .gitignore: Git ignore file

Getting Started

There are two ways to run the application: using Docker and docker compose or running it locally with Python and uv.

Running with Docker and Docker Compose

1. Make sure you have Docker/podman and Docker Compose/podman compose installed on your machine.
2. Prepare env file. See example.env for reference. You need to have the files:
   • web.env - for the Flask application
   • db.env - for the database
   • cache.env - for the Redis cache
3. Run the following command to start the application:

docker-compose up

The application will be accessible at http://localhost:8088.

Running Locally with Python and uv

1. Make sure you have Python 3.14+ installed on your machine.
2. Install dependencies using uv:

uv sync

3. Export the necessary environment variables. You can use the example.env file as a reference. But in this case you, probably, want to set the following variables as it shown:

• unset or remove DATABASE_URI so by default it will use a sqlite database (sqlite:///app.db in the application folder)
• CACHE_OPTIONS="SimpleCache" - to use simple in-memory cache instead of Redis

4. Run the Flask application using uv:

uv run shortener_flask_app

The application will be accessible at http://localhost:8088.