🚧 This project is still in active development and should not be considered stable.

API (and accompanying documentation) for social media-style expansion of links with site-defined metadata.

⚠️ This documentation is for getting started as a contributor. If you’re looking for information on using the API, head to unfurl.page.

• Docker version 1.10.0 (required)
• Node.js version 10.0.0 (recommended) — enables linting, git hooks, and better editor integration.

The majority of dependencies are installed within docker containers, so we recommend always running the application inside of their containers.

To prepare for local development by installing all dependencies, building docker containers, and creating local databases run:

make bootstrap

Start the application’s docker containers with:

make start

• The documentation pages are available at localhost:1313.
• The API is available at localhost:3000.

Use CONTROL C to shutdown the application.

To test endpoints that require key authentication, use API key test-consumer-token.

For GitHub authentication, configure a test OAuth application and add the credentials to a new file called .env to be loaded automatically. If you’d like your key to be authorized as an administrator, add your GitHub email to ADMIN_EMAILS_CSV as well.

• Homepage URL: http://0.0.0.0:3000
• Application callback URL: http://0.0.0.0:3000/sessions/new

AUTH_GITHUB_CLIENT_ID=
AUTH_GITHUB_CLIENT_SECRET=
ADMIN_EMAILS_CSV=

Restart the server if running.

See all available development commands by running:

make

We recommend integrating the following with your editor:

• Prettier to apply consistent code formatting rules. These rules are enforced on commit, so editor integration significantly reduces frustration.

Secrets needed beyond AWS credentials are encrypted in this repository using sops. To edit the encrypted files in terraform/variables.enc.yml:

make secrets-edit

Your AWS credentials must be accessible in the environment, and they must be able to access the encryption key in AWS KMS.