Document default behavior for uploads (and upload collection configuration)

[jamesvclements]

I think the readme currently implies that files are automatically stored in the cloud (and local storage is disabled):

this plugin extends Payload so that all of your media will be stored in S3 rather than locally.

But it's hard to tell whether this happens automatically or if you still need some amount of configuration in the collection(s) you're using for uploads themselves. E.g. does a media collection still need staticDir, disableLocalStorage, etc?

It'd be great to clarify in this repo's readme (or the main doc website may be even better) what is needed for upload configuration when using Payload Cloud vs. the cloud-storage plug-in vs. default local storage.

[denolfe]

I agree this is needed. Thank you for the feedback @jamesvclements

[jamesvclements]

@denolfe ofc! What is the right answer? 😁 for a Media collection with admin thumbnails

[denolfe]

The plugin handles all of this automatically if it is invoked.

How it does this is, when in Payload Cloud (process.env.PAYLOAD_CLOUD=true), it overrides disableLocalStorage to true, and injects other functionality via upload handlers and hooks. staticDir will be disregarded as it is only used when disableLocalStorage is false or undefined. All normal default local file storage functionality is left untouched if outside of Payload Cloud.

plugin-cloud-storage is competely separate from this plugin. Though, it has a lot of similar functionality.

I hope this clears things up. I will keep this open until this is documented in the README 👍

[jamesvclements]

@denolfe got it. Does that mean adding PAYLOAD_CLOUD=true to my local .env is all that's needed to get an upload collection working? For example, I added that to my .env and commented out my media collection like this:

import path from 'path';
import { CollectionConfig } from 'payload/types';

export const Media: CollectionConfig = {
    slug: 'media',
    upload: {
        // staticURL: '/media',
        // staticDir: path.resolve(__dirname, '../../media'),
        // disableLocalStorage: true,
        // adminThumbnail: 'thumbnail',
        // imageSizes: [
        //     {
        //         height: 256,
        //         width: 256,
        //         crop: 'center',
        //         name: 'thumbnail',
        //     },
        // ],
    },
    fields: [
        {
            name: 'alt',
            type: 'text',
            required: true,
        },
    ],
};

export default Media;

It works, but thumbnails are broken and I can't quite tell if the files are being stored in the cloud or attempting to store locally and missing (hence missing thumbnails).

[jamesvclements]

@denolfe I'm realizing that I expected when using Payload Cloud, your local environment would still read and write from the remote database, not switch to local. But I just cloned a new website project from the Payload site and cloned it locally and realized because PAYLOAD_CLOUD=true is not in the .env.example, it switches to local mode.

When adding PAYLOAD_CLOUD=true to my local .env, the thumbnails break.

How do you use Payload Cloud locally? I think this would be the common use case, where you want to fill in the content for your client as you go (sending it to the final database), and then they can change or add new things once you deploy.

Rather than needing to re-populate things you did locally once you push.

[denolfe]

@jamesvclements So to clarify, you're wanting to develop from local against Payload Cloud's image store and database?

I can see how this would be useful for some of your clients. This is possible, it just involves populating a few more environment variables from your Payload Cloud project. This should also be added to the documentation.

These are the values that will need to be filled out in order to develop against your Payload Cloud resources from local: https://github.com/payloadcms/plugin-cloud/blob/main/dev/.env.example#L6-L14

PAYLOAD_CLOUD=true
PAYLOAD_CLOUD_BUCKET=
PAYLOAD_CLOUD_COGNITO_IDENTITY_POOL_ID=
PAYLOAD_CLOUD_COGNITO_USER_POOL_CLIENT_ID=
PAYLOAD_CLOUD_COGNITO_USER_POOL_ID=
PAYLOAD_CLOUD_ENVIRONMENT=
PAYLOAD_CLOUD_PROJECT_ID=
PAYLOAD_CLOUD_COGNITO_PASSWORD=
PAYLOAD_CLOUD_BUCKET_REGION=

These values can be seen on your project's File Storage tab. You'll have to match up the values appropriately. We plan on adding the ability to easily copy these values in the near future.

PAYLOAD_CLOUD_PROJECT_ID can be seen on Settings -> Billing. PAYLOAD_CLOUD_ENVIRONMENT will be prod

I've thrown a lot out there, please let me know if you have other questions or run into issues.

[jamesvclements]

@denolfe it works! Thank you so much.

Is there then a way to combine these env variables and my staticDir argument to get absolute URLs for my hosted images? Something like ${process.env.WHEREVER_CLOUD_ASSETS_ARE}/${staticDir}/${filename}?

For anyone else stumbling here, this is the full .env I'm using to run my local payload against my Payload Cloud instance:

PORT=
MONGODB_URI=
PAYLOAD_SECRET=
PAYLOAD_CLOUD=
PAYLOAD_CLOUD_BUCKET=
PAYLOAD_CLOUD_COGNITO_IDENTITY_POOL_ID=
PAYLOAD_CLOUD_COGNITO_USER_POOL_CLIENT_ID=
PAYLOAD_CLOUD_COGNITO_USER_POOL_ID=
PAYLOAD_CLOUD_ENVIRONMENT=
PAYLOAD_CLOUD_PROJECT_ID=
PAYLOAD_CLOUD_COGNITO_PASSWORD=
PAYLOAD_CLOUD_BUCKET_REGION=

[denolfe]

@jamesvclements This is not a capability as of now, but there is something similar in done in plugin-cloud-storage to generate the URL that we may be able to look at implementing.

Can you give an example of a current URL vs. what is desired?

[denolfe]

Still on our list to make this more understandable in the UI and README. Moving this package to the monorepo.