How to Deploy a Payload and Astro Monorepo
Deploy an Astro and Payload CMS monorepo to an always-on Node server on Cloudways Velocity, with a Postgres database and persistent storage for uploads on the same server.
This post contains affiliate links. If you click on a link and make a purchase, I may receive a commission at no extra cost to you.
What's up, everyone? A while back, I worked on connecting Astro and Payload. A few of the comments and messages I got on that video suggested that I show how to deploy such a project. In order to do that, I decided to use Cloudways to deploy Astro and Payload as a monorepo. That's what I'll be showing you here today.
I wanted to give a quick shout out to Cloudways by DigitalOcean for sponsoring this post and for providing resources for me to show off this awesome platform.
Why Velocity for Astro and Payload
In today's post, I'll be using Cloudways Velocity to deploy an Astro frontend that I adapted for my Next.js Payload Essentials starter repo.
If you don't know what Cloudways is, it's a managed hosting platform that allows you to quickly deploy Node.js apps. This is a perfect home for an Astro project that's using the Node adapter. Cloudways comes with everything you'd want in a managed Node provider, with predictable pricing, automated backups, and easy team management with no per-seat cost. The automated backups are opt-out, so your database is enrolled in backups from the very instant it's created.
For all that, you pay a monthly price for a server. The server I'm demonstrating is on the least expensive tier at $20 per month, which gets you 2 GB of RAM and 2 vCPUs. You can, of course, upgrade to higher plans if you need more resources. Regardless, you don't have to do calculus to figure out what you're going to spend each month for a server, like you might have to do for a serverless platform or a completely metered option. There are no cold starts or massive bills.
You can try it out for free or get started by using my referral link. You can also add team members with full access to whatever servers and applications you'd like, without an additional per-seat cost. So you can host several client sites all within the same server, but keep all the information locked down and only shared with people who need to see it.
Create a server and connect GitHub
To create a server, you first need a Cloudways account, so if you haven't yet, get signed up. If you read my last post walking through a setup of a Payload project on Cloudways, this next part is review. I was already set up, so this part follows an older walkthrough of the same steps.
Once you're signed up and logged in, select Velocity from the sidebar. You can start a free trial or get full access right away. I'll click Start free trial. Even for a more complex project, I'm good to be on the starter plan, so I'll leave that selected and scroll down to check my local disk space. I'll leave this at 25 GB, then click Continue.
Select the region that makes the most sense for you and your users, and name your server. I'll name mine PayloadEssentials. You can then select your Git provider and get authorized. Once connected, I can see all of my repositories.
The monorepo, storage, and the CDN
The monorepo I'm using is payload-essentials-astro. If you want to follow along with this next part using that repo, be sure to clone the repo to your computer and push it to your Git provider before moving forward.
1git clone https://github.com/nick-vogel/payload-essentials-astro.git
This project is an adaptation of my Payload Essentials course repo. Instead of only being a Next.js project, this is a Payload and Astro project. Payload, on Next.js, lives in apps/cms, and the Astro frontend lives in apps/web. I created the repo as a monorepo for simplicity and so I could still use Payload's Local API. But you can use two separate projects together over the REST API. The repo is simply the starter project that you build in my course using Next.js and Payload, just with the frontend changed to Astro.
Much like the Payload starter I created for my last post on this topic, this repo uses Postgres and local storage. Cloudways provides a Postgres database as part of their platform cost, and we'll set that up later. I also signed up for 25 GB of persistent storage, so that's where our images will be stored. As always, if you prefer to use S3-like storage or another cloud storage provider, feel free. You'll need to set that up yourself, though.
I chose this project to show off next because I mentioned in my last post covering Cloudways that it hosts way more than just Next.js out of the box. This project is both Next.js and Astro, and as you'll see, Cloudways Velocity handles it with no problem. Outside of Next.js and Astro, you can also deploy Remix, plain React, TanStack, Nuxt, Angular, and more. If it builds to SSR or a static bundle and starts with Node, Velocity can run it.
Now, we're using local storage provided by Cloudways, but storage can add up quickly. You may want to consider using an external storage provider, especially if you want to use a CDN other than Cloudflare. Cloudways provides a Cloudflare Enterprise CDN with up to 250 GB of bandwidth on the starter plan. Anything above that 250 GB bandwidth allowance results in a charge of 2 cents per GB.
You're opted into the CDN by default if you use the provided Cloudways domains. If you want to use their CDN with a custom domain, follow the instructions in the Cloudflare section of the platform to get started. All you need to do is point your domain at their servers from your DNS provider. We'll carry on with the rest of this post using local storage, with the Cloudways Velocity CDN configured as it is.
Deploy the Payload CMS
To deploy the Payload CMS, we'll search for the payload-essentials-astro repo and select it from the list. We'll then make sure that the root directory points to apps/cms.
We'll set the build command to pnpm payload migrate && pnpm payload run src/seed/run.ts && pnpm build. The middle section there is a seed script that puts in some data for us to look at after we build our project.
Just as it happened in my last post, we know that our application is going to fail without a database. So after it fails, we'll set up our Postgres database by going to Access Details in our application. I'll select Connect under Postgres and then proceed.
If you read my last post, you'll notice that the required environment variables are not what I want. I only want the database URL. We'll construct that from the database name, username, and password. Keep these values and your Payload secret private.
To construct our database URL, we'll need all these values and the host, which is 127.0.0.1, and the port, which is 5432.
1name: database_name2username: user3password: pass4host: 127.0.0.15port: 5432
Back over in our environment variables, we'll click Add Variable and paste this value in as DATABASE_URL.
1DATABASE_URL=postgres://user:[email protected]:5432/database_name
Again, this is sensitive, so I'll mark it as such.
If you're following along with the Astro starter repo, we'll need a seed user and password. Set SEED_ADMIN_EMAIL and SEED_ADMIN_PASSWORD to values you'd like. You'll use these to seed the database and log in until you create another user.
Now I can click Save. Once that's done, I'll go to Deploy Management and click Redeploy. With any luck, this should succeed the second time.
Now that this has succeeded, I'll open the CMS link in a new tab. I'll enter my seed credentials and log in. You'll see your seed user, some media, and a couple of pages, posts, and categories. While we're here, let's grab the CMS URL.
Before we move on, we can adjust our build command to remove the seed script, because it will fail now that there is data in the database. With that removed, I'll click Save and redeploy. That's the Payload half done.
Deploy the Astro frontend
Now let's get our Astro frontend spun up. I'll create a new application by clicking on Quick Actions and then Add Application. I'll select the payload-essentials-astro repo again, on the main branch. We'll edit the root directory and select apps/web. We can leave the build command as it is. You'll notice that an entry file is set for us. This is correct for this repo, so I'll leave that as it is.
I'll click Add next to environment variables. Here, I'll set HOST to 0.0.0.0. We'll set PAYLOAD_URL to our CMS URL without the /admin and the trailing slash. Then we'll include the same PAYLOAD_SECRET and DATABASE_URL from the CMS side. Then we'll hit Save and click Deploy Now.
Once this deploys, we can click Go to Application Listing, then click on the Astro application, and open it in a new tab. Once that loads up, we should see the starter application. We can click around and see everything working properly.
Wrap-up
And that's all it takes to deploy an Astro and Payload project on Cloudways by DigitalOcean. In one server, we now have a dedicated Postgres database with automated backups for our Payload Essentials application built on Astro. With it, we have an always-on Node.js server to serve our application. As part of our plan, we also have 25 GB of persistent storage, so we can store all of our objects on the server as well. Optionally, you have access to an enterprise-grade CDN through Cloudflare when you set up your own domain within the platform.
Thank you again to Cloudways by DigitalOcean for sponsoring this post. You can sign up for your own Cloudways Velocity account using my referral link.