Basic URL Shortener

No-Frills Short URLs

The simplest of URL shorteners for self-hosted users. No analytics. No complex installation.

Features

• Extremely light-weight (public site is <4KB)
• Automatic light and dark themes
• Simple, intuitive dashboard

Example

For screenshots of the dashboard, check out the Wiki.

Tech Stack

• Server-side processing: PHP
• Configuration: Single JSON file
• Data storage: Single JSON file
• Build System: Node.js

Pre-requisites

• A domain for your short URLs, e.g. example.com
• A seperate domain for the dashboard to manage short URLs, e.g. dash.example.com
• A web server like Apache or NGINX
• Node.js
• PHP
• HTTPS Certificates for each domain

Installation

1. Clone the repository

   $ git clone https://github.com/aensley/bus-php

2. Install dependencies

   $ npm ci

3. Configure your installation

4. Build the site

   $ npm run build

Updates

1. Update the repository

   $ git pull

2. Update dependencies

   $ npm ci

3. Rebuild the site

   $ npm run build

Server Setup

The built site will be available in two directories:

1. dist/public/ - This is for the domain hosting BUS itself, e.g. https://example.com
2. dist/dash/ - This is for the domain hosting the BUS dashboard, where the short URLs will be created and managed, e.g. https://dash.example.com

Example configs are included for apache for both the public and dash sites.

Authentication

You will need to setup some form of authentication in front of the dashboard domain. The example config uses basic auth.

Configuration

.env.json

In the dist/ folder, you must create a .env.json file with the site configuration.

An example .env.json file is included for reference.

Settings

Setting	Required	Default	Description
public-domain	Yes	None	The domain for your URL shortener. This will be used as the base for your short URLs.
dash-domain	Yes	None	The domain for your dashboard to create and manage short URLs.
short-code-length	No	4	The length to use for automatically generated short-codes.
link-to-dash	No	false	Set to true to show a link to your

Application Data

The only data stored by this application are the short URLs, the long URLs they link to, and the timestamp of when they were created. All of this is stored in a single JSON file.

.data.json

In the dist/ folder you will need to create a .data.json file. The .data.json file must be writeable by the web server user.

This file contains a JSON-formatted list of all short URLs added to your site. Each entry has the short-code as its key and the following properties:

• l: The long URL.
• c: Timestamp representing when the short URL was created.

If you lose this file, you lose your short URLs. It is a good idea to regularly backup this file.