Gatefold

Gatefold is a quick to set up, simple to use URL shortener built with Amazon API Gateway and Amazon DynamoDB and codified with Amazon CloudFormation.

Features:

• deploy a URL shortener to your AWS account in less than a minute
• shorten URLs and store a token to change it later
• create vanity URLs by passing custom strings
• specify a TTL for all shortened URLs on the domain.

The entire setup is bootstrapped with a CLI tool written in Node.js, which allows you to deploy or delete Gatefold stacks for several domains in multiple AWS accounts and regions. It is also possible to print the pre-populated API definition or the CloudFormation template to standard output for external processing.

No computing engines apart from API Gateway's VTL mapping templates are used, where all logic is stored.

Getting Started

Install the Gatefold package using npm or yarn:

npm install -g gatefold

To check your installation, run gatefold --version.

Now that you've installed Gatefold, you can deploy your custom URL shortener service:

gatefold deploy example.org

This will create a new Gatefold stack in your default AWS account and region. To change the target, use --profile <profile> and --region <region>:

gatefold deploy \
  --profile my-other-profile \
  --region eu-west-1 \
  example.org

Afterwards, set up a custom domain name and add an ALIAS record for the Amazon CloudFront distribution to hook it up to your domain. Both operations are easily achievable in the web console.

Wait for it to become available:

    until host example.org | grep address; do sleep 5; done \
      && echo "It's up!"

Consuming the API

Create your first shortened URL:

POST  HTTP/1.1
Host: example.org
Content-Type: application/json

{
  "longUrl": "https://cimpress.com"
}

The server responds with the shortened URL and a token:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://example.org/f530e741
{
    "longUrl": "https://cimpress.com",
    "shortUrl": "https://example.org/f530e741",
    "token": "a2354cd3-463e-11e8-ad00-8a820fb8b897"
}

You can also create a vanity URL passing a custom string:

PUT /gatefold HTTP/1.1
Host: example.org
Content-Type: application/json

{
  "longUrl": "https://cimpress.com",
  "token": "vas12tmsuo"
}

Update it by repeating the request with the same token.

Commands

You can see more information about a command by passing --help to the command, e.g. gatefold deploy --help.

gatefold deploy domain

Creates a new Gatefold stack in your AWS account or updates an existing one.

Specify TTL in days with --ttl <ttl>. The default is 3650, i.e. ten years.

gatefold delete domain

Deletes a Gatefold stack from your AWS account.

For gatefold deploy and gatefold delete possible to switch your default AWS account or region by passing --profile <profile> and --region <region> respectively.

gatefold get-swagger domain

Builds the Swagger API definition for Gatefold and prints it to standard output.

Specify TTL in days with --ttl <ttl>. The default is 3650, i.e. ten years.

gatefold get-cloudformation domain

Builds the CloudFormation template for Gatefold and prints it to standard output.

Specify TTL in days with --ttl <ttl>. The default is 3650, i.e. ten years.

Built With

• commander.js - Node.js CLI framework
• cfn - Amazon CloudFormation automation
• Swagger 2.0 - RESTful API description
• Amazon API Gateway - reliable API publishing
• Amazon DynamoDB - low-cost NoSQL document store
• Amazon CloudFormation - Infrastructure-as-Code (IaC), Infrastructure-as-a-Service (IaaS) solution

Contributing

Have you benefited from the tool? Have you found or fixed a bug? Would you like to see a new feature implemented? We are eager to collaborate with you on GitHub.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Igor Sowinski <[email protected], [email protected]> - GitHub

See also the list of contributors who participated in this project.

License

This project is licensed under the Apache 2.0 license - see the LICENSE file for details.