Darjeelink

Darjeelink is a very simple link shortener gem. Authorized users can create shortened links. The shortened link can be visited by anyone, and they are redirected to the original link.

Authorisation is handled by Google oauth.

It needs to be mounted inside a rails app to be used.

It tracks the number of times a link has been clicked. This is the only metric that is tracked.

There is a UTM generator, where you can provide:

• a base url
• a source and medium
• a campaign identifier And you can get a link with UTM params all filled in, and shortern it with one click.

There is an API available to create short links. To create a short link via the API:

First, create an api token Darjeelink::ApiToken.create!(username: <username>, active: true). Then grab the token.

Next, make a request

POST /api
Authorization => Token token=<username>:<token>
{
  short_link: {
    url: 'https://www.example.com',
    shortened_path: 'xmpl' (optional)
  }
}

url is the absolute URI that you wish to shorten shortened_path is the path that you will visit to get redirected to your original link. It is optional. If it is not provided one will be generated automatically

If successful you will get a response like:

STATUS 201
{
  short_link: <shortened_url>
}

If unsuccessful you will get a response like

STATUS 400
{
  error: "information on what went wrong"
}

If authorization failed you will get a response like

STATUS 401
{}

Add these lines to your app's Gemfile

gem 'darjeelink'
gem 'repost' # Shouldn't be required, but it is.  Investigate why

Add these lines to your app's routes.rb

mount Darjeelink::Engine => "/"

# Go to short links
get '/:id' => "shortener/shortened_urls#show"

• DATABASE_URL

• AUTH_DOMAIN
• GOOGLE_API_CLIENT_ID
• GOOGLE_API_CLIENT_SECRET

• FALLBACK_URL - If someone tries to visit a link that does not exist then they will go here.
• PERMITTED_IPS - If you want to admin access to certain IP addresses then use this setting.
• REBRANDLY_API_KEY - Used to fetch links from rebrandly if importing old links from there.

In config/initializers/darjeelink.rb edit the config.source_mediums hash.

Each key is a hyphenated source-medium. If you just want the source then omit the hyphen and medium.

Each value is a slightly more readable version for display.

Docker can be used to run tests easily - 'docker-compose up' should run the unit tests.

Another approach is to use Vagrant. vagrant up will create an isolated darjeelink instance. Before you run vagrant up, make sure to create .env.development & .env.test files as detailed below.

Run cp .env.sample spec/dummy/.env.development

Nothing else required

Run cp .env.sample spec/dummy/.env.test

Change the database url to be different to the development one i.e. postgres://darjeelink_dbuser:password@localhost/darjeelink-test

Darjeelink follows Semantic Versioning

NB: Before releasing, ensure that the gem is working as expected by running the tests. If possible perform some manual testing via a webserver.

Once all necessary changes have made it in to master and you are ready to do a release you need to do these steps.

Note that if you are running in a vagrant VM or docker-shell.sh constainer, most of these steps can be done from the terminal session.

• Update lib/darjeelink/version.rb to the new version
• Run bundle install to pick up the change in Gemfile.lock
• Commit the changes to lib/darjeelink/version.rb and Gemfile.lock, and push them to GitHub
• Go to https://github.com/38degrees/darjeelink/releases and create a release tag in GitHub
• Run gem build darjeelink.gemspec this will output a file darjeelink-X.X.X.gem the version should match what version.rb and github.
• Run gem push darjeelink-X.X.X.gem

We have a few TODOs in the project. Please grep for TODO in the codebase to see them, and consider picking one up during maintainance.

No personally identifiable data is stored about the public by this gem. It does not store information on individual clicks, only a counter of how many times a link has been clicked. There are no cookies required to visit a short link.

For the admin side there is a session cookie that stores information in the session cookie TODO: LIMIT THIS TO EMAIL

This gem has been developed by 38 Degrees to meet our link shortening needs. To Contribute, create a PR, Doesn't have to be from a fork

The gem is available as open source under the terms of the MIT License.