Shortener

A private URL shortening service with a web dashboard, browser extension and Android app. Automatically fetches Open Graph metadata (title, description, image) from target pages and tracks click counts.

Česká verze / Czech version

Features

• URL shortening — custom or auto-generated short codes (6 characters)
• Open Graph metadata — automatic fetching of title, description and image from the target page, with manual editing
• Click counter — traffic tracking with bot detection
• Dashboard — link management, search, pagination, copy to clipboard
• Browser extension — shorten links via popup or context menu (right-click)
• Android app — share any URL via Android Share Sheet to shorten it instantly, with a built-in WebView dashboard
• Internationalization — English (default) and Czech, language auto-detected from browser or set via env variable

Tech stack

Layer	Technology
Backend	Flask, Gunicorn, SQLAlchemy
Database	MariaDB 11
Frontend	Jinja2, vanilla JS, CSS (dark mode)
Android	Kotlin, WebView, EncryptedSharedPreferences
Infra	Docker Compose

Project structure

shortener/
├── docker-compose.sample.yml  # Docker Compose template
├── .env.sample               # Environment variables template
├── db/
│   └── init.sql              # Initial SQL schema
├── flask/
│   ├── Dockerfile
│   ├── requirements.txt
│   └── app/
│       ├── __init__.py       # Flask app factory
│       ├── models.py         # Models (User, ShortURL)
│       ├── routes.py         # Endpoints (auth, API, redirect)
│       ├── cli.py            # CLI commands (create-user, sync-db)
│       ├── i18n.py           # Internationalization
│       ├── og_fetcher.py     # OG metadata fetcher
│       ├── translations/     # JSON translation files (en, cs)
│       ├── templates/        # Jinja2 templates
│       └── static/           # CSS, JS, images
├── extension/                # Browser extension (Manifest v3)
└── android/                  # Android app (Kotlin)
    └── app/src/main/java/com/shortener/app/
        ├── AuthManager.kt    # Auth, cookies, API calls
        ├── MainActivity.kt   # WebView dashboard
        ├── SetupActivity.kt  # Server & credentials setup
        └── ShareActivity.kt  # Share Sheet handler

Installation

1. Prepare configuration:

   cp .env.sample .env
   cp docker-compose.sample.yml docker-compose.yml
   

   Edit .env — set at least MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD, SECRET_KEY and SITE_URL.

2. Start containers:

   docker compose up -d
   

3. Create a user:

   docker compose exec flask flask create-user <username>
   

   You will be prompted for a password.

4. Sync database schema (on update):

   docker compose exec flask flask sync-db
   

   Compares models with the database and adds missing tables, columns and indexes. Extra structures are listed and require confirmation before removal.

5. Access:

   The dashboard runs at http://localhost:8002.

Environment variables

Variable	Description	Default
MYSQL_ROOT_PASSWORD	MariaDB root password	—
MYSQL_DATABASE	Database name	shortener
MYSQL_USER	Application database user	shortener
MYSQL_PASSWORD	Application database user password	—
SECRET_KEY	Key for signing session cookies	random
LOG_LEVEL	Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)	WARNING
SITE_URL	Public URL of the service (no trailing slash)	—
LANGUAGE	UI language: auto (detect from browser), en, cs	auto

API

All API endpoints require authentication.

Method	Endpoint	Description
GET	/api/urls	List URLs (query: q, offset, limit)
POST	/api/urls	Create a shortened link
PUT	/api/urls/<id>	Edit OG metadata
DELETE	/api/urls/<id>	Delete a link
GET	/api/urls/<id>/image	OG image (binary)
GET	/api/suggest-code	Suggest a random short code

Redirect: GET /<short_code> → target URL (HTTP 301).

Browser extension

See extension/README.md for installation and usage.

Android app

See android/README.md for building and usage.

License

MIT

---

Česká verze

Soukromá služba pro zkracování URL s webovým dashboardem, rozšířením pro prohlížeč a Android aplikací. Automaticky stahuje Open Graph metadata (titulek, popis, obrázek) z cílových stránek a sleduje počty kliknutí.

Funkce

• Zkracování URL — vlastní nebo automaticky generované krátké kódy (6 znaků)
• Open Graph metadata — automatické stahování titulku, popisu a obrázku z cílové stránky s možností ruční úpravy
• Počítadlo kliknutí — sledování návštěvnosti s detekcí botů
• Dashboard — správa odkazů, vyhledávání, stránkování, kopírování do schránky
• Rozšíření pro prohlížeč — zkrácení odkazu přes popup nebo kontextové menu
• Android aplikace — sdílení URL přes Android Share Sheet pro okamžité zkrácení, s vestavěným WebView dashboardem
• Internacionalizace — angličtina (výchozí) a čeština, jazyk detekován z prohlížeče nebo nastaven přes env proměnnou

Instalace

1. Příprava konfigurace:

   cp .env.sample .env
   cp docker-compose.sample.yml docker-compose.yml
   

   Upravte .env — nastavte minimálně MYSQL_ROOT_PASSWORD, MYSQL_PASSWORD, SECRET_KEY a SITE_URL.

2. Spuštění kontejnerů:

   docker compose up -d
   

3. Vytvoření uživatele:

   docker compose exec flask flask create-user <jméno>
   

   Příkaz se zeptá na heslo.

4. Synchronizace schématu databáze (při aktualizaci):

   docker compose exec flask flask sync-db
   

   Porovná modely s databází a přidá chybějící tabulky, sloupce a indexy. Přebytečné struktury vypíše a zeptá se na potvrzení před odstraněním.

5. Přístup:

   Dashboard běží na http://localhost:8002.

Proměnné prostředí

Proměnná	Popis	Výchozí
MYSQL_ROOT_PASSWORD	Root heslo MariaDB	—
MYSQL_DATABASE	Název databáze	shortener
MYSQL_USER	Uživatel aplikace	shortener
MYSQL_PASSWORD	Heslo uživatele aplikace	—
SECRET_KEY	Klíč pro podepisování session cookies	náhodný
LOG_LEVEL	Úroveň logování (DEBUG, INFO, WARNING, ERROR, CRITICAL)	WARNING
SITE_URL	Veřejná URL služby (bez lomítka na konci)	—
LANGUAGE	Jazyk UI: auto (detekce z prohlížeče), en, cs	auto

Rozšíření pro prohlížeč

Viz extension/README.md.

Android aplikace

Viz android/README.md.