Upload to your S3 bucket

Some vocabulary

If you already know what a bucket or a presigned URL is, you can skip this section and jump to How to use your S3 bucket with Doppio.

What is an S3 bucket?

Let's start with the basics. S3 stands for Simple Storage Service. It is an object-storage system where you can store and retrieve files by key. A bucket is the container that holds those objects and their associated configuration, such as access rules or lifecycle settings. S3-compatible storage can also offer features such as encryption, immutability, and versioning. If your project needs to manage many generated files, it can be a good fit.

Amazon S3 is the best-known implementation and largely defines the standard, but there are many compatible alternatives such as Clever Cloud Cellar or MinIO. Doppio can work with any AWS S3-compatible storage service.

What is a presigned URL?

An S3 bucket can be public or restricted to specific users for read and/or write access. Whatever your security policy, you can grant temporary access to a third party through a presigned URL. This is a URL that allows a specific action on a specific object for a limited time. Doppio only needs temporary write access to upload the rendered file.

How to use your S3 bucket with Doppio

Here are the steps required to have Doppio upload the rendered document to your bucket.

1. Create an S3 client

The first step is to create an S3 client that can generate a presigned upload URL for your bucket. Many libraries can do this, including the AWS SDK and MinIO. Use whichever client fits your stack.

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 depends on your S3 client library, but it should look roughly like this:

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

Renders are usually fast, so an expiration window of five minutes is typically 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 upload the file

After the document is rendered successfully, Doppio sends a PUT request to the presigned URL you provided. If that request succeeds, the file is uploaded directly to your S3 bucket. If the upload fails, try rendering the same document without the presigned URL first. That helps you determine whether the issue comes from the render itself or from the connection to your bucket.