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
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 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=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
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 idurl: string
- The saved urlcreatedAt: string
- an ISO 8601 date indicating the creation timeupdatedAt: 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 idurl: string
- The updated urlcreatedAt: string
- an ISO 8601 date indicating the creation timeupdatedAt: 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 usernamePOSTGRES_STORAGE_PASSWORD (required if STORAGE_DRIVER is
Postgres
) - the Postgres database's passwordPOSTGRES_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
Copyright (c) 2020-present, Snir Shechter