payloadcms/templates/with-vercel-postgres

Payload Blank Starter

This template comes configured with the bare minimum to get started on anything you need.

Quick start

Click the 'Deploy' button above to spin up this template directly into Vercel hosting. It will first prompt you save this template into your own Github repo so that you own the code and can make any changes you want to it.

Set up the following services and secrets and then once the app has been built and deployed you will be able to visit your site at the generated URL. From this point on you can access your admin panel at /admin of your app URL, create an admin user and then click the 'Seed the database' button in the dashboard to add content into your app.

Services

This project uses the following services integrated into Vercel which you will need to click "Add" and "Connect" for:

Neon Database - Postgres-based cloud database used to host your data

Vercel Blob Storage - object storage used to host your files such as images and videos

The connection variables will automatically be setup for you on Vercel when these services are connected.

Secrets

You will be prompted to add the following secret values to your project. These should be long unguessable strong passwords, you can also use a password manager to generate one for these.

PAYLOAD_SECRET - used by Payload to sign secrets like JWT tokens

Quick Start - local setup

To spin up this template locally, follow these steps:

Clone

After you click the Deploy button above, you'll want to have standalone copy of this repo on your machine. If you've already cloned this repo, skip to Development.

Development

1. First clone the repo if you have not done so already

2. cd my-project && cp .env.example .env to copy the example environment variables. You'll need to add the POSTGRES_URL and BLOB_READ_WRITE_TOKEN from your Vercel project to your .env if you want to use Vercel Blob and the Neon database that was created for you.

   NOTE: If the connection string value includes localhost or 127.0.0.1, the code will automatically use a normal postgres adapter instead of Vercel.. You can override this functionality by setting forceUseVercelPostgres: true if desired.

3. pnpm install && pnpm dev to install dependencies and start the dev server

4. open http://localhost:3000 to open the app in your browser

That's it! Changes made in ./src will be reflected in your app. Follow the on-screen instructions to login and create your first admin user. Then check out Production once you're ready to build and serve your app, and Deployment when you're ready to go live.

Docker (Optional)

If you prefer to use Docker for local development instead of a local Postgres instance, the provided docker-compose.yml file can be used.

To do so, follow these steps:

• Modify the POSTGRES_URL in your .env file to postgres://postgres@localhost:54320/<dbname>
• Modify the docker-compose.yml file's POSTGRES_DB to match the above <dbname>
• Run docker-compose up to start the database, optionally pass -d to run in the background.

How it works

The Payload config is tailored specifically to the needs of most websites. It is pre-configured in the following ways:

Collections

See the Collections docs for details on how to extend this functionality.

• Users (Authentication)

  Users are auth-enabled collections that have access to the admin panel.

  For additional help, see the official Auth Example or the Authentication docs.

• Media

  This is the uploads enabled collection. It features pre-configured sizes, focal point and manual resizing to help you manage your pictures.

Working with Postgres

Postgres and other SQL-based databases follow a strict schema for managing your data. In comparison to our MongoDB adapter, this means that there's a few extra steps to working with Postgres.

Note that often times when making big schema changes you can run the risk of losing data if you're not manually migrating it.

Local development

Ideally we recommend running a local copy of your database so that schema updates are as fast as possible. By default the Postgres adapter has push: true for development environments. This will let you add, modify and remove fields and collections without needing to run any data migrations.

If your database is pointed to production you will want to set push: false otherwise you will risk losing data or having your migrations out of sync.

Migrations

Migrations are essentially SQL code versions that keeps track of your schema. When deploy with Postgres you will need to make sure you create and then run your migrations.

Locally create a migration

pnpm payload migrate:create

This creates the migration files you will need to push alongside with your new configuration.

On the server after building and before running pnpm start you will want to run your migrations

pnpm payload migrate

This command will check for any migrations that have not yet been run and try to run them and it will keep a record of migrations that have been run in the database.

Docker

Alternatively, you can use Docker to spin up this template locally. To do so, follow these steps:

1. Follow steps 1 and 2 from above, the docker-compose file will automatically use the .env file in your project root
2. Next run docker-compose up
3. Follow steps 4 and 5 from above to login and create your first admin user

That's it! The Docker instance will help you get up and running quickly while also standardizing the development environment across your teams.

Questions

If you have any issues or questions, reach out to us on Discord or start a GitHub discussion.