Upload to your S3 bucket #

Some vocabulary #

If you already know what is a bucket or a pre-signed URL you can skip this section and jump to How to link your bucket to Doppio

What is an S3 bucket ? #

Let's start with the basics. S3 refers to a Simple Storage Service. It is a system storage where you can store and retrieve any amount of data (objects, files, ...) with a single key. A bucket is a container for the stored data and a way to manage all this stored data at once (access, lifecycle management, ...). An S3 can offer several additional interesting features such as encryption, immutability and versioning to name a few. If your project includes the management of many files, it could be worth looking into this.

Amazon's AWS S3 is the most famous one and set the standard for all others, but there are loads of offers on the market such as Clevercloud's Cellar or MinIo. We can work with any server AWS-compatible.

What is a presigned URL ? #

An S3 bucket can be open to the public or restrict its access to a few users (read, write or both) to secure your data. Whatever your security policy, you can always give a temporary access to a third party via a presigned url, that is a URL which can only read or write a specific data for a limited period of time (beyond which, the URL is no longer valid). Doppio only needs a temporary write access to your bucket.

How to use your S3 bucket with Doppio #

Here is a list of steps to follow to make Doppio upload the rendered document in your bucket.

1. Create an S3 client #

The first step to get a presigned upload URL for your bucket is to create an S3 client. There are many libraries out there able to do just that like AWS SDK or minio. Just use one that you like.

Here is an example with minio JS:

// Instantiate the minio client with the endpoint
// and access keys as shown below.
var minioClient = new Minio.Client({
    endPoint: 'play.min.io',
    port: 9000,
    useSSL: true,
    accessKey: '<YOUR_S3_SERVER_ACCESS_KEY>',
    secretKey: '<YOUR_S3_SERVER_SECRET_KEY>'
});

2. Get a presigned URL #

The exact code will change depending on your S3 client library, but it should look something like this :

// expires in 5 minutes.
const presignedUrl = await minioClient.presignedPutObject('mybucket', 'nameOfDocument.pdf', 5*60);

Our render is pretty fast, so an expiration date of 5 minutes should be more than enough.

3. Add it to the request body #

When making a request to Doppio, add the presigned URL to the payload.

{
    "doppio": {
        "presignedUrl": "<PRESIGNED_URL_RETRIEVED_FROM_S3_CLIENT>"
    },
    "page": {
        // ...
    }
}

4. Let Doppio do its magic #

After the successfull render of the document, Doppio will attempt a PUT request on the provided presigned URL. If it is successfull, it will be put directly on your S3 bucket without you having to do a thing ! If the render is unsuccessfull, try rendering the same document without the presigned URL to find out if the error comes from the rendering or the connection to your bucket.