Tessa - asseT management

Tessa is a small web API that manages assets by providing links to upload, download, and delete remote files via HTTP. It has a database to track metadata on all of the assets it has provided links for.

With this version Tessa only provides links for Amazon S3, but it could theoretically support any system that allows for signed links to manage files.

See the tessa-client project for a client implementation for this service.

Configuration

Credentials and strategies can be configured in one of two ways. Through a JSON encoded environment variable or through a YAML config file.

config/creds.yml

This YAML file provides username and passwords for basic authentication for clients of the API. You can provide as many credentials as is necessary for your deployment. The schema is:

username1: password1
username2: password2

This can also be configured through the TESSA_CREDENTIALS environment variable. See the Environment Variables section below.

config/strategies.yml

The strategies file allows you to configure multiple strategies for file storage. In this version all strategies are for AWS S3. These are the possible options:

• bucket: Name of the S3 bucket
• prefix: Prefix for all keys generated in this strategy
• acl: The acl for new files in this strategy
• region: The AWS region
• ttl: Time to live in seconds for signed links generated by Tessa (default is 900).
• region: AWS region (defaults to AWS_REGION environment variable)
• credentials: AWS access and secret keys (defaults to respective environment variables)

The format is

strategy_name:
  bucket: my-tessa-bucket
  prefix: files/
  ttl: 1800
  region: "us-east-1"
  credentials:
    access_key_id: "ABC123"
    secret_access_key: "DEF456"

The region and credentials config items are optional if you provide the AWS prefixed environment variables. See the Environment Variables section below.

Warning: signed downloads will not work if the region config does not actually match the region of the bucket.

Strategies can also be configured through the TESSA_STRATEGIES environment variable. See the Environment Variables section below.

How should I configure my s3 bucket?

First thing to note is you should almost always use us-east-1, you're likely to get headaches if you use another region.

The s3 bucket must also be configured with the proper Bucket Policy and CORS configuration to work appropriately.

1. In the IAM console, find (or create) a user for Tessa.
2. During the user creation step (or on the Security Credentials tab) create an Access Key. Use the Key and Key ID in the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.
3. In the user's Permissions tab, create (or attach) a Policy that allows all "put", "get", and "delete" actions against the bucket and all objects within it. Hint: start with the bucket's ARN and then check all the policies that apply to the bucket.
   Here's what a bucket ARN looks like (note that you need both the root as well as /* to access all items in the bucket):

   "arn:aws:s3:::assets.watermark.org/*",
   "arn:aws:s3:::assets.watermark.org"

4. Go back to the Bucket and edit the CORS configuration. This allows Dropzone.js to upload files from the browser.
   Server responded with 0 code - if you get this error, you didn't set up the CORS properly!
   you need a new CORSRule for each website that will upload to Tessa using Dropzone.js. The AllowedOrigin must match the Website that is allowed to upload.

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
<CORSRule>
    <AllowedOrigin>https://events.watermark.org</AllowedOrigin>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>POST</AllowedMethod>
    <AllowedMethod>DELETE</AllowedMethod>
    <AllowedHeader>*</AllowedHeader>
</CORSRule>
<CORSRule>
    <AllowedOrigin>*</AllowedOrigin>
    <AllowedMethod>GET</AllowedMethod>
</CORSRule>
</CORSConfiguration>

5. (optional) Set up a Public CDN to serve images
   If you followed the guide in the Events system readme to set up a public CDN to serve uploaded assets, then the bucket will need the following Bucket Policy.
   Note: if you selected "Grant Read Permissions on Bucket - Yes, Update Bucket Policy" then AWS took care of this for you automatically.
   This policy allows the CloudFront CDN to read all objects in the bucket. You can mix this with other policies.

{
    "Version": "2008-10-17",
    "Id": "PolicyForCloudFrontPrivateContent",
    "Statement": [
        {
            "Sid": "1",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::cloudfront:user/CloudFront Origin Access Identity xxxxxx"
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::assets.watermark.org/*"
        }
    ]
}

Environment Variables

Default AWS credentials and region for the strategies in your system can be configured with the environment variables AWS_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY. Each strategy can override the settings given, but these will be used if none is provided.

Tessa uses a PostreSQL database for persisting data on the assets in the system. You will need to configure a DATABASE_URL environment variables to a PostgreSQL database.

TESSA_CREDENTIALS when set will take precedence over the YAML config file. It has the same schema, but is JSON encoded. For example: {"username":"password"}.

TESSA_STRATEGIES when set will take precedence over the YAML config file. It has the same schema, but is JSON encoded. For example: {"strategy_name":{"bucket":"my-tessa-bucket","prefix":"files/","ttl":1800}}

Development

To get started with development first follow the instructions on Watermark's devenv repository. Once that is setup and working clone down this repository and do the following:

• Get your AWS credentials and put them in your creds.yml file
• bin/setup - Run a few app setup tasks
• $ docker-compose up - Start up necessary Docker containers
• Visit http://tessa.wcc in your browser. You should see the app!
• Run the test suite with $ docker-compose run web rspec
• If you need to create any development specific configuration do it in the .env[.ENV].local file.

This should be all you need to get a working development environment. If you're having trouble please get in touch with us at dev@watermark.org. We'd be glad to help.

Contributing

See CONTRIBUTING.md