148 lines
6.8 KiB
Plaintext
148 lines
6.8 KiB
Plaintext
---
|
|
title: Installation
|
|
label: Installation
|
|
order: 30
|
|
desc: To quickly get started with Payload, simply run npx create-payload-app or install from scratch.
|
|
keywords: documentation, getting started, guide, Content Management System, cms, headless, javascript, node, react, express
|
|
---
|
|
|
|
#### Software Requirements
|
|
|
|
Payload requires the following software:
|
|
|
|
- Yarn or NPM
|
|
- Node.js version 14+
|
|
- A MongoDB Database
|
|
|
|
<Banner type="warning">
|
|
Before proceeding any further, please ensure that you have the above
|
|
requirements met.
|
|
</Banner>
|
|
|
|
## Quickstart with create-payload-app
|
|
|
|
To quickly scaffold a new Payload app in the fastest way possible, you can use [create-payload-app](https://npmjs.com/package/create-payload-app). To do so, run the following command:
|
|
|
|
```
|
|
npx create-payload-app
|
|
```
|
|
|
|
Then just follow the prompts! You'll get set up with a new folder and a functioning Payload app inside.
|
|
|
|
## Adding to an existing app
|
|
|
|
Adding Payload to either a new or existing TypeScript + Express app is super straightforward. To add to an existing app, just run `npm install --save --legacy-peer-deps payload`.
|
|
|
|
From there, the first step is writing a baseline config. Create a new `payload.config.ts` in your project's `/src` directory (or whatever your root TS dir is). The simplest config contains the following:
|
|
|
|
```js
|
|
import { buildConfig } from "payload/config";
|
|
|
|
export default buildConfig({
|
|
// By default, Payload will boot up normally
|
|
// and you will be provided with a base `User` collection.
|
|
// But, here is where you define how you'd like Payload to work!
|
|
});
|
|
```
|
|
|
|
Write the above code into your newly created config file. This baseline config will automatically provide you with a default `User` collection. For more information about users and authentication, including how to provide your own user config, jump to the [Authentication](/docs/authentication/config) section.
|
|
|
|
Although this is just the bare minimum config, there are _many_ more options that you can control here. To reference the full config and all of its options, [click here](/docs/configuration/overview).
|
|
|
|
### Server
|
|
|
|
Now that you've got a baseline Payload config, it's time to initialize Payload. It requires an Express server that you provide, so if you're not familiar with how to set up a baseline Express server, please read up on exactly what Express is and why to use it. Express' own [Documentation](https://expressjs.com/en/starter/hello-world.html) is a good place to start. Otherwise, follow along below for how to build your own Express server to use with Payload.
|
|
|
|
1. Run `npm install --save --legacy-peer-deps express` if you have not done so already
|
|
1. Create a new `server.ts` file in the root directory of your app
|
|
1. Add the following code to `server.ts`:
|
|
|
|
```ts
|
|
import express from "express";
|
|
|
|
const app = express();
|
|
|
|
app.listen(3000, async () => {
|
|
console.log(
|
|
"Express is now listening for incoming connections on port 3000."
|
|
);
|
|
});
|
|
```
|
|
|
|
This server doesn't do anything just yet. But, after you have this in place, we can initialize Payload via its asynchronous `init()` method, which accepts a small set of arguments to tell it how to operate.
|
|
|
|
To initialize Payload, update your `server.ts` file to reflect the following code:
|
|
|
|
```ts
|
|
import express from "express";
|
|
import payload from "payload";
|
|
|
|
const app = express();
|
|
|
|
const start = async () => {
|
|
await payload.init({
|
|
secret: "SECRET_KEY",
|
|
mongoURL: "mongodb://localhost/payload",
|
|
express: app,
|
|
});
|
|
|
|
app.listen(3000, async () => {
|
|
console.log(
|
|
"Express is now listening for incoming connections on port 3000."
|
|
);
|
|
});
|
|
};
|
|
|
|
start();
|
|
```
|
|
|
|
Here is a list of all properties available to pass through `payload.init`:
|
|
|
|
##### `express`
|
|
|
|
**Required**. This is your Express app as shown above. Payload will tie into your existing `app` and scope all of its functionalities to sub-routers. By default, Payload will add an `/admin` router and an `/api` router, but you can customize these paths.
|
|
|
|
##### `secret`
|
|
|
|
**Required**. This is a secure string that will be used to authenticate with Payload. It can be random but should be at least 14 characters and be very difficult to guess. Often, it's smart to store this value in an `env` and set different values for each of your environments (local, stage, prod, etc). The `dotenv` package is very handy and works well alongside of Payload.
|
|
|
|
Payload uses this secret key to generate secure user tokens (JWT). Behind the scenes, we do not use your secret key to encrypt directly - instead, we first take the secret key and create an encrypted string using the SHA-256 hash function. Then, we reduce the encrypted string to its first 32 characters. This final value is what Payload uses for encryption.
|
|
|
|
##### `mongoURL`
|
|
|
|
**Required**. This is a fully qualified MongoDB connection string that points to your MongoDB database. If you don't have MongoDB installed locally, you can [follow these steps for Mac OSX](https://docs.mongodb.com/manual/tutorial/install-mongodb-on-os-x/) and [these steps](https://docs.mongodb.com/manual/tutorial/install-mongodb-on-windows/) for Windows 10. If you want to use a local database and you know you have MongoDB installed locally, a typical connection string will look like this:
|
|
|
|
`mongodb://localhost/payload`
|
|
|
|
In contrast to running MongoDB locally, a popular option is to sign up for a free [MongoDB Atlas account](https://www.mongodb.com/cloud/atlas), which is a fully hosted and cloud-based installation of MongoDB that you don't need to ever worry about.
|
|
|
|
##### `mongoOptions`
|
|
|
|
Customize MongoDB connection options. Payload will connect to your MongoDB database using default options which you can override and extend to include all the [options](https://mongoosejs.com/docs/connections.html#options) available to mongoose.
|
|
|
|
##### `email`
|
|
|
|
An object used to configure SMTP. [Read more](/docs/email/overview).
|
|
|
|
##### `local`
|
|
|
|
A boolean that when set to `true` tells Payload to start in local-only mode which will bypass setting up API routes. When set to `true`, `express` is not required. This is useful when running scripts that need to use Payload's [local-api](/docs/local-api/overview).
|
|
|
|
##### `loggerOptions`
|
|
|
|
Specify options for the built-in Pino logger that Payload uses for internal logging. See [Pino Docs](https://getpino.io/#/docs/api?id=options) for more info on what is available.
|
|
|
|
##### `onInit`
|
|
|
|
A function that is called immediately following startup that receives the Payload instance as it's only argument.
|
|
|
|
### Test it out
|
|
|
|
After you've gotten this far, it's time to boot up Payload. Start your project in your application's folder to get going.
|
|
|
|
After it starts, you can go to `http://localhost:3000/admin` to create your first Payload user!
|
|
|
|
### Docker
|
|
|
|
Looking to deploy Payload with Docker? New projects with `create-payload-app` come with a Dockerfile and docker-compose.yml file ready to go. Examples of these files can be seen in our [Deployment docs](/docs/production/deployment#docker).
|