MiniUrl

MiniUrl is an open-source production-ready microservice for shortening Urls. Deploy it on your personal cloud and get a fully-functional url-shortener with zero effort.

MiniUrl is part of the Mini Services Project.

Features

Extremely efficient
Production ready
Zero code
Easy setup
Highly configurable
Cloud-ready with an almost zero-config Helm chart
Multiple deployment options

Getting Started

Run using Helm, Docker or Node.js
Use the API (future: dashboard) and enjoy a zero-code microservice 🙃

Deployment Options

Helm

MiniUrl maintains an extensive production-grade Helm chart. See the chart for the possible values configuration and examples.

helm repo add miniservices https://raw.githubusercontent.com/mini-services/helm-charts/main
helm repo update

# You may also add --set ingress.enable=true for deploying an Ingress route as well
helm upgrade --install miniurl miniservices/miniurl --set baseRedirectUrl=<YOUR_SHORT_URL>

Docker

Run MiniUrl's docker image directly.

docker run -d --name miniurl -e BASE_REDIRECT_URL=<YOUR_SHORT_URL> -e STORAGE_DRIVER=Sqlite -p 80:8000 miniservices/miniurl

docker run -d --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres
docker run -d --name miniurl -p 80:8000 miniservices/miniurl \
                             -e BASE_REDIRECT_URL=<YOUR_SHORT_URL> \
                             -e STORAGE_DRIVER=Postgres \
                             -e POSTGRES_STORAGE_DATABASE=postgres \
                             -e POSTGRES_STORAGE_HOST=localhost \
                             -e POSTGRES_STORAGE_USER=postgres \
                             -e POSTGRES_STORAGE_PASSWORD=postgres

Node.js

Requirements:

Node.js 14.8+
NPM 6+ or Yarn X+

git clone https://github.com/mini-services/miniurl.git
cd miniurl
npm install
npx cross-env BASE_REDIRECT_URL=<YOUR_SHORT_URL> STORAGE_DRIVER=Sqlite npm start

Node.js troubleshooting:

for Windows OS, it is also possible to use nvm for Windows. Refer to the nvm documentation.

NOTE this deployment is NOT production ready since it uses the Sqlite storage driver. To run a production-grade docker deployment, you will need to provide a suitable databases (and possibly a process manager such as pm2). A working example assuming a Postgres database on localhost:5432 with username postgres and password postgres:

npx cross-env BASE_REDIRECT_URL=<YOUR_SHORT_URL> \
              STORAGE_DRIVER=Postgres \
              POSTGRES_STORAGE_HOST=localhost \
              POSTGRES_STORAGE_USER=postgres \
              POSTGRES_STORAGE_PASSWORD=postgres \
              npm start

Development

See running the project in development mode.

API

The easiest way to get familiar with MiniUrl's API is using Insomnia or Postman.

Insomnia

MiniUrl workspace

Postman

POST /miniurl/url

Save a url and get a shorter one instead.

Request

Body (json)

url: string (required) - The url to shorten

Response

Body (text) - a shortened Url

GET /miniurl/url/:id

Retrieves a saved url with its information.

Request

Query

id: string (required) - The saved url's id

Response

Body (json)

id: string - The url's id
url: string - The saved url
createdAt: string - an ISO 8601 date indicating the creation time
updatedAt: string - an ISO 8601 date indicating the last updated time

PUT /miniurl/url/:id

Update the URL and retrieve its information

Request

Body (json)

url: string (required) - The updated url

Query

id: string (required) - The saved shorten url's id

Response

Body (json)

id: string - The url's id
url: string - The updated url
createdAt: string - an ISO 8601 date indicating the creation time
updatedAt: string - an ISO 8601 date indicating the last updated time

GET <BASE_REDIRECT_URL>/:id

Redirects to a saved url.

NOTE this endpoint may not be found at the root url since it depends on the baseRedirectUrl configuration variable. e.g if the baseRedirectUrl is localhost:3000/u, this endpoint will be found at /u/:id.

Request

Query

id: string (required) - The saved url's id

Response

DELETE /miniurl/url/:id

Delete url with its information.

Request

Required: auth bearer token.

Query

id: string (required) - The saved url's id

Redirect 302 - redirects to the saved url.

Configuration

Since MiniUrl follows the best practices including the 12 factor app, the microservice is entirely configurable via environment variables. Available variables are:

General

BASE_REDIRECT_URL (required) - the shortened urls' base path e.g https://youtu.be, https://bit.ly or https://example.com/u

API_PREFIX (default: "/miniurl") - MiniUrl's prefix for the api routes (e.g for saving a url, one would POST to ${API_PREFIX}/url)

URL_MATCH_PATTERN (default: "**") - a micromatch-complaint glob pattern for restricting the saved urls (for example, if you don't want your MiniUrl to save links other than your domain such as https://evil-fisching.com)

URL_LIFETIME (default: "7 days") - a human-readible time (see the ms docs for available options) stating the url lifetime (after which it expires). Note that the expiration mechanism runs at most once per minute and at least once per hour and so slight deviation may occur.

PORT (default: "80") - the Node.js process port. In most cases your shouldn't change this

Storage

STORAGE_DRIVER (required) - MiniUrl's storage driver. available options are

InMemory (for development purposes only)
Sqlite (for development purposes only)

SQLITE_STORAGE_FILENAME (default: ./db.sqlite) - the Sqlite storage path
Redis

REDIS_STORAGE_HOST (required) - the database host (e.g https://my-redis-database.com)

REDIS_STORAGE_PASSWORD (required) - the Postgres database password

REDIS_STORAGE_PORT (default: 6379) - the database port

REDIS_STORAGE_USERNAME (default: undefined) - the database username
Postgres

POSTGRES_STORAGE_HOST (required if STORAGE_DRIVER is Postgres) - the Postgres database's host (e.g https://my-database.com)

POSTGRES_STORAGE_USER (required if STORAGE_DRIVER is Postgres) - the Postgres database's username

POSTGRES_STORAGE_PASSWORD (required if STORAGE_DRIVER is Postgres) - the Postgres database's password

POSTGRES_STORAGE_DATABASE (required if STORAGE_DRIVER is Postgres) - the Postgres database's name (e.g postgres)

Auth

AUTH_DRIVER (default: BearerToken) - MiniUrl's auth driver. Currently, the only available option is BearerToken.

AUTH_BEARER_TOKEN (default: ) - The bearer token to use when selecting the BearerToken auth driver.

Issues and Questions

Issues & Features

If you found a bug or have an idea for a feature, feel free to open an issue.

Questions

You may open an issue for questions, but it's usually faster to send a message on our Slack

Contribution

Refer to our contribution guide.

License

MIT