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

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

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>

Run MiniUrl's docker image directly.

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

NOTE this deployment is NOT production ready since it uses the InMemory storage driver which is a plain object. To run a production-grade docker deployment, you will need to provide a suitable database. A working example using Postgres:

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=Relational \
                             -e RELATIONAL_STORAGE_CLIENT=postgres \
                             -e RELATIONAL_STORAGE_DATABASE=postgres \
                             -e RELATIONAL_STORAGE_HOST=localhost \
                             -e RELATIONAL_STORAGE_USER=postgres \
                             -e RELATIONAL_STORAGE_PASSWORD=postgres

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=InMemory 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 InMemory storage driver which is a plain object. 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=Relational \
              RELATIONAL_STORAGE_CLIENT=postgres \
              RELATIONAL_STORAGE_HOST=localhost \
              RELATIONAL_STORAGE_USER=postgres \
              RELATIONAL_STORAGE_PASSWORD=postgres \
              npm start

See running the project in development mode.

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

Insomnia

• MiniUrl workspace

Postman

• Url collection
• Demo environment
• Local environment

Save a url and get a shorter one instead.

Body (json)

• url: string (required) - The url to shorten

Body (text) - a shortened Url

Retrieves a saved url with its information.

Query

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

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

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.

Query

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

Redirect 302 - redirects to the saved url.

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

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

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.

STORAGE_DRIVER (required) - MiniUrl's storage driver. available options are InMemory (for development purposes only) and Relational (for any Knex.js-complaint SQL database).

RELATIONAL_STORAGE_CLIENT (required if STORAGE_DRIVER is Relational) - the relational client to use, see Knex.js docs for the available options

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

RELATIONAL_STORAGE_USER (required if STORAGE_DRIVER is Relational) - the relational database's username

RELATIONAL_STORAGE_PASSWORD (required if STORAGE_DRIVER is Relational) - the relational database's password

RELATIONAL_STORAGE_DATABASE (required if STORAGE_DRIVER is Relational) - the relational database's name (e.g postgres)

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

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

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

Refer to our contribution guide.

MIT

Copyright (c) 2020-present, Snir Shechter