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
Postman
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 idurl: string
- The saved urlcreatedAt: string
- an ISO 8601 date indicating the creation timeupdatedAt: 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.
Copyright (c) 2020-present, Snir Shechter