Installing Payload on a VPS for production : Deployment documentation feels unclear
Hello,
I am trying to use Payload in a production server and instructions are unclear. I am simply trying to run the CMS.
# Building
Reading the documentation about the steps to accomplish it:
In order for Payload to run, it requires both the server code and the built admin panel. These will be thedistandbuilddirectories by default. If you've usedcreate-payload-appto create your project, executing thebuildnpm script will build both and output these directories.
Where?
- On my local machine and commit it? The
distand
buildfolders are
.gitignore'd
- Directly on prod server? Then fine it builds.
# How do I use Payload now?
## After the build
I guess that now, I should ask Nginx to serve a folder. Which one?
build?
dist?
How can use nginx now? Should I rewrite URLs? serve them as is?
## Should I run
npm run serve?
I tried this too, on a server with Let's Encrypt and a MongoDB Atlas. But then is an SSL error:
ERROR (payload): Error: cannot connect to MongoDB. Details: C047A3D8F17F0000:error:0A000438:SSL routines:ssl3_read_bytes:tlsv1 alert internal error:../deps/openssl/openssl/ssl/record/rec_layer_s3.c:1586:SSL alert number 80I googled about it. It feels unwise to change Certbot's permissions. Running
npm run devfeels unwise too.
---
There are DigitalOcean's tutorials and I am aware of them, I used them but they just tell to how install needed software to use Payload. But afterwards, I don't see explicit explanation on how to link stuff together.
Also I'd like to add that about deploying to a VPS does not always mean to a DigitalOcean droplet, and have a section directly mentionning DO won't tell people that's it's about doing it on a VPS
Have you whitelisted the ip inside mongo atlas?
also, I think docker is prefered for production, it is pretty easy.
Hi!
Can't quite answer your question about the MongoDB / LetsEncrypt issue you're having but I can try to answer your question on the build part :).
Building payload consumes quite a lot of memory and might crash your server when it runs out of memory. And yes! I don't think you'd want to commit your dist folder to your repoistory. What I would recommend to do is: Use a Github action to build Payload and finally deploy your
distcode to your server and run it.
Yes, depending on your familiarity with Docker, it's probably the best way to deploy your Payload server 🙂
You can use Render.com which handles docker, gitops and other stuff for you
I wasn't aware we should do that actually. it's written nowhere 😭
Ah yes! that might make it really easy if you want to Render.com ofcourse 🙂
It is expensive though, but I use it for development
so free tier is enough for me
So far I pulled the repo into the prod server because it's the way i know
But again, is it about a VPS server or deployment in Vercel and stuff ?
I can migrate to Docker overtime, but even there, it could lack explanation on how to proceed :
https://payloadcms.com/docs/production/deployment#docker-composeYeah, I agree. The docs assume you already know your way around Docker. So it's like "Here is a Dockerfile, goodluck!"
yes
I can only think ;
:AMThumbsUp:
What I wrote was about deploying it on a VPS yeah, deploying it on Vercel would also be possible, but comes with pretty slow cold boot responses. If you need help with the Github action and/or setting it up with Docker, I can provide an example / try to explain how if you want? 🙂
it's about Github Actions and and deploy it on a VPS
it could be an article on Payload's blog
Well, according to the Payload team, the easiest way (and probably is) to host Payload, is through Payload cloud :p
But that'd cost you 35$ a month
It costs money and i can't afford that :p
Yeah, for small size projects and/or just getting started, 35$ is quite the money
There is almost no difference between deploying payload and any other expressjs app with mongodb database.
True, but you can't expect users to know how to do something like that right? :p
I can deploy PHP Apps, not that much when it comes to nodejs
Oh, and perhaps something to try @Aliqq'ae fly.io. Pretty easy to setup for Payload as well!
Pretty much comes down to running a couple of commands.
flyctl launch-> follow the setup
flyctl secrets import < .env-> Imports your .env variables to your fly.io instance
flyctl deployWhen it comes to pricing, I have 2 servers with 512mb ram running there, for 0$ a month 😆
i thought about it too
but the idea is to stay on my registrar's servers
They sort you out with Docker and all that
If you have a Dockerfile in the root of your project, it recognizes that and uses it
oh yes
Meaning Digitalocean? Or just some other VPS?
some other VPS
an OpenStack VPS
Alright, in that case it's a bit more work
I found that I should use PM2 to run dist/server.js
and daemonize it
Yeah, pm2 is a pretty neat tool to do that!
can't you just use docker?
You already have docker compose file. Shouldn't
docker-compose up -ddo the trick?
The default docker-compose.yml is for development, runs Payload in dev mode.
ah it is yeah
I can. But I don't wan't to yet, because it has to be PROD ready
HOWEVER
I only have a nginx issue
If you insist on using Docker, you can pretty easily setup a github action where it builds the container and publishes it on your Repository it's container registry 🙂
From there you can pull the container on your VPS and run it.
Or even beter, extend the github action pipeline and make it do that for you 😛
that's for later
:noted:
now the problem is :
502 bad gateway
on nginx
How are you setting up nginx for Payload?
location / { proxy_pass https://127.0.0.1:3333/admin; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; }so far
no ?
I mean
I use let's encrypt
Payload is just there, in its lil' folder
How have you setup lets encrypt?
- https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-22-04
i used that tutorial
good refresher
Do you need nginx?
I'd rather have nginx yes
because I want other apps on that server
The 502 bad gateway you have that already works with ssl and all enabled? @Aliqq'ae
yes
the website is https
it's a subdomain of mine
Nice!
on a vps of mine
But, I think you shouldn't proxy pass using https://
i may be wrong in some config that does not make a bug
you're right, i removed it
Still a 502?
still a 502
probs not an nginx problem actually
Why's that?
Payload not running?
PM2 says Payload is running
when I curl
localhost:3333it says "Connection refused"
knowing that I updated Payload's port
good news: no more 502
bad news: white page
good news: no more white page
bad news: perpetual loading
I am tired and frustrated. I will try the Vercel way with building in GH Actions
and while it's up that way, I'll build a prod ready docker-compose
that issue is blocking my website new version to prod and then, a refactor to React
If you are using a single VPS, you might want to use something like Dokku or coolLabs so that you're not managing your own nginx + LE
Most of the things listed in the post are really
devopsconcerns. None of the things listed in the second section are specific to Payload. They are applicable to deploying any ole node.js app.
It would be a huge ask for us to document every possible way to deploy Payload (just a node app) on any platform. We've called out things specific to Payload in the docs while also pointing to other resources to deploying node apps.
Open for discussion how we can improve within reason here.
I agree totally with this sentiment, but at the same time having step by step guides on deploying to various popular platforms is only gonna help with adoption
I do believe these kinds of guides have aided other open source projects like strapi in many ways including SEO (as people search how to deploy X on Y)
But I do agree its fundamentally not unique to payload...the same way DB management and backup/restore isnt, still super useful to have guidance on it
It's more about "what do to with built Payload" and how to use it on a VPS instance, removing the specifications about Digital Ocean
It's been more than a week for me to figure out what do do with the project
it also seems to be possible to push it on a Vercel instance, but it's so unclear on how to proceed knowing be have to build it first to avoind the cold boot
Agreed here that additional resources are always helpful. I believe we linked the DO deployment guides because that was what we were using at the time and the guides were helpful.
Open to writing our own, especially because half the questions appear to be how to deploy an app in general.
DO guides are helpful to have a VPS started, because well it's to run Payload on a VPS after all
Also yes, this
But after that, we still tend to don't know what to do with Payload itself
It is solved, I have payload on, serving
@denolfe @jacobsfletch I think I am starting to grasp what is going on with explanations in documentations and guides about how to use Payload. For instance, I am starting a NextJS project, and I'll use Payload with it. A whole new project. There will also be Storybook.
Previously I saw this blog article, which I kept in favourites:
https://payloadcms.com/blog/the-ultimate-guide-to-using-nextjs-with-payloadBut now that I need it, I notice that you are writing a nice story and what there is around in Next and Payload, but again, it rose questions:
- "
Do I need to do something in particular to integrate Payload IN Next? Launch the "create" inside or outside?"
- "
Is there a specific command to run?"
- "
Ispackage.jsonshared between Payload and Next or they each have their own?"
- "
Where should be Payload?"
As a refresher for context :
. ├── assets # Mine, shall be moved │ └── images ├── next.config.js ├── next-env.d.ts ├── node_modules │ └─ // ... ├── package.json ├── package-lock.json ├── public │ ├── next.svg │ └── vercel.svg ├── README.md ├── src │ ├── app │ └── stories └── tsconfig.jsonLike, where would stand Payload in Next's project?
And as I mentioned, i will use Storybook to learn to use it and this kind of guide is just what I needed. Storybook team wrote that and it's all clear:
https://storybook.js.org/recipes/next/Sometimes, Junior devs and newcomers wouldn't need anything more than that
@Aliqq'ae You can look at how this is done in our templates. Here is the website template that configures payload and next:
https://github.com/payloadcms/payload/tree/main/templates/websiteYes
But do you know that it is not easy to comprehend for some ? :/
Your question is how to structure your code?
it's also how to install it, and which commands to run
and where
just what Storybook did
https://storybook.js.org/recipes/next/This
The template shows how this can be done, you just want a walkthrough from scratch?
Yes, a simple guide
that does not make people dive into the code
it's not easy to comprehend for everyone
I hear you I suppose on walkthroughs.
Unfortunately, being a developer-first tool, there is some expectation for exploration and drive to implement different tools together. The template with it already done for you feels like a good middle ground, people just need to be curious and poke around the code.
"Unfortunately, being a developer-first tool, there is some expectation for exploration and drive to implement different tools together. The template with it already done for you feels like a good middle ground, people just need to be curious and poke around the code."
yes but also no
having to poke around just to have a product able to run ASAP is not always what would help adopting Payload
We know the Front-End and Back-End can be separated and how to do so
but in an "The Ultimate Guide To Using Next.js with Payload > Combined serverless", we would expect a little walkthrought
Some commands
Now having to poke around and read code
Code is not documentation
That makes the required entry level to Payload frankly steep in contrast to use it, which is actually a breeze
And can make its adoption so much slower
Also, that makes me think of an old mentor that also think that way. We never clicked together and is now seen as elitist
In a perfect world, we'd have a guide and walkthrough for everything - not viable currently. Thank you for all of this feedback. I will bring it to the team 👍
👍🏼
Just being explicit on how to install it in a way that won't make issues later on into a front-end, and a mode extensive explanation with what to do with
build/and
dist/is a good start
I completely agree RE guides
We have docs, templates, our blog, and videos, but no real text-based "guides"
:AMLoveSlap:
Somewhat related to this, im gonna experiment into turning video guides into blog post tutorials with AI
I have low expectations of AI generated docs and guides, tbh
Just feels like a human should be on the other end, who can do a better job
same BUT if you base it off the transcript from youtube, i thought it might have enough info?
yea in theory
otherwise yes, the AI is idiot
you spend more time fixing the prompt than you wouldve writing it yourself
I'm not opposed to it but quality is way more important than anything
Yeah well, I can contribute in this, even translate that in French if needed
Star
Discord
online
Get help straight from the Payload team with an Enterprise License.