This template builds a Strapi backend for Platform.sh, which can be used to quickly create an API that can be served by itself or as a Headless CMS data source for another frontend application in the same project. This repository does not include a frontend application, but you can add one of your choice and access Strapi by defining it in a relationship in your frontend's .platform.app.yaml
file.
Strapi is a Headless CMS framework written in Node.js.
Note: This template is set up for a production Strapi site, you cannot create new collection types at runtime. Please clone, branch, develop, and push to create new collections.
- Node.js 12
- PostgreSQL 12
- MongoDB 3
- Oracle MySQL 8
- Automatic TLS certificates
- yarn-based build
- OpenAPI spec generation
- Automatic public API documentation
- The first time the site is deployed, Strapi will direct you to visit the
/admin
path to register an administrative user. You will need to register an admin user before any API endpoints can be created. Once you have registered the admin user, you will have access to the Admin Panel. - After you have created and
admin
user, you will not be able to create Content Types onmaster
, since themaster
environment will be running in production, where Content Types are not editable. Create a new development branch, and log back in with youradmin
credentials. - Now you can begin adding Content Types to build out the API. By default, no Content Types have been included in the installation and any Content Types you add will have secured API endpoints that will make them publicly inaccessible by default. You will need to update the permissions for each Content Type from the Users & Permissions section of the Admin Panel after you have created them. If you are unfamiliar with how to create Content Types or modify permissions with Strapi, visit the Quick Start Guide for detailed instructions.
- This template provides only the API for a full project, but you can modify the repository into a multi-app project where Strapi acts as a separate backend application for the front end of your choice. You can view our Gatsby with Strapi template as an example.
The following changes have been made relative to the quickstart Strapi project to run on Platform.sh. If using this project as a reference for your own existing project, replicate the changes below to your project.
- The
.platform.app.yaml
,.platform/services.yaml
, and.platform/routes.yaml
files have been added. These provide Platform.sh-specific configuration and are present in all projects on Platform.sh. You may customize them as you see fit. - The
.platform.app.yaml
file has been configured to run your production Strapi server on themaster
environment, and development servers on all other environments. While you will be able to add content to an existing Content Type onmaster
, you will only be able to create new Content Types on development environments. - There are a few modules that have been added to support Strapi:
config-reader-nodejs
: Provides convenience wrappers for accessing the Platform.sh environment variables.pg
: supports connection with PostgreSQL.graphql
: supports GraphQL queries.documentation
: generates an OpenAPI specification and Swagger documentation from your models. You can view the documentation at/docs
, and the final spec at/docs/spec
.
- A
config/database.js
file has been modified. It usesconfig-reader-nodejs
to retrieve PostgreSQL credentials and connect when Strapi is started. - A
config/server.js
file configures basic server settings, admin JWT authorization using the Platform.sh environment variablePLATFORM_PROJECT_ENTROPY
, and GraphQL settings. - A
extensions/documentation/config/settings.json
file overrides the default front matter information in the generated pubic API documentation.
The config/database.js
file is set up to detect whether Strapi is running on Platform.sh or not using config-reader-nodejs
. If Platform.sh is not detected, Strapi will default to a local SQLite database in.tmp
.
You can add additional plugins for Strapi locally by adding them as dependencies using Yarn. In most cases, official Strapi modules can be added with yarn strapi install <plugin-name>
.
Customizing modules will differ slightly for each plugin. The strapi-plugin-documentation
plugin for example generates an OpenAPI specification from your API and public Swagger documentation at <your-domain>/docs
. Overrides are applied to that process using the extensions/documentation/config/settings.json
file in this repository. In other cases, there will be a specific overrides
subdirectory within extensions/<plugin-name>
you will need to use, so check that plugin's documentation for details. Be aware of whether the plugin needs write access at runtime, and be sure to define matching mounts in your .platform.app.yaml
file if necessary.
This template can be used with other databases that is supported by strapi. Incase you do not to want to use the default PostgreSQL database, the other available database options are:
MongoDB
If you decide to use MongoDB as your preferred database, you can use it by following these steps.-
Install the strapi mongoose connector
yarn add strapi-connector-mongoose
-
Replace the
dbposgres
in the services.yaml file with the following:dbmongo: type: mongodb:3.6 disk: 512
Note that the minimum disk size for MongoDB is 512MB.
-
Locate your
.platform.app.yaml
file and replace the relationship name to match the mysql database you have addedrelationships: mongodatabase: "dbmongo:mongodb"
-
Go to the config folder, locate the
database.js
file in theconfig
folder and replace the content with the followingconst config = require("platformsh-config").config(); let dbRelationshipMongo = "mongodatabase"; // Strapi default sqlite settings. let settings = { client: "sqlite", filename: process.env.DATABASE_FILENAME || ".tmp/data.db", }; let options = { useNullAsDefault: true, }; if (config.isValidPlatform() && !config.inBuild()) { // Platform.sh database configuration. const credentials = config.credentials(dbRelationshipMongo); console.log( `Using Platform.sh configuration with relationship ${dbRelationshipMongo}.` ); settings = { client: "mongo", host: credentials.host, port: credentials.port, database: credentials.path, username: credentials.username, password: credentials.password, }; options = { ssl: false, authenticationDatabase: "main", }; } else { if (config.isValidPlatform()) { // Build hook configuration message. console.log( "Using default configuration during Platform.sh build hook until relationships are available." ); } else { // Strapi default local configuration. console.log( "Not in a Platform.sh Environment. Using default local sqlite configuration." ); } } module.exports = { defaultConnection: "default", connections: { default: { connector: "mongoose", settings: settings, options: options, }, }, };
MySQL
If you decide to use MySQL as your preferred database, you can use it by following these steps.
-
Install the Node.js mysql driver
yarn add mysql
-
Replace the
dbposgres
in the services.yaml file with the following:dbmysql: type: oracle-mysql:8.0 disk: 256
Note that the minimum disk size for mysql/oracle-mysql is 256MB.
-
Locate your
.platform.app.yaml
file and replace the relationship name to match the mysql database service you added in theservices.yaml
filerelationships: mysqldatabase: "dbmysql:mysql"
-
Go to the config folder, locate the
database.js
file in theconfig
folder and replace the contents with the followingconst config = require("platformsh-config").config(); let dbRelationshipMySql = "dbmysql"; // Strapi default sqlite settings. let settings = { client: "sqlite", filename: process.env.DATABASE_FILENAME || ".tmp/data.db", }; let options = { useNullAsDefault: true, }; if (config.isValidPlatform() && !config.inBuild()) { // Platform.sh database configuration. const credentials = config.credentials(dbRelationshipMySql); console.log( `Using Platform.sh configuration with relationship ${dbRelationshipMySql}.` ); settings = { client: "mysql", host: credentials.host, port: credentials.port, database: credentials.path, username: credentials.username, password: credentials.password, }; options = { ssl: false, debug: false, acquireConnectionTimeout: 100000, pool: { min: 0, max: 10, createTimeoutMillis: 30000, acquireTimeoutMillis: 600000, idleTimeoutMillis: 20000, reapIntervalMillis: 20000, createRetryIntervalMillis: 200, }, }; } else { if (config.isValidPlatform()) { // Build hook configuration message. console.log( "Using default configuration during Platform.sh build hook until relationships are available." ); } else { // Strapi default local configuration. console.log( "Not in a Platform.sh Environment. Using default local sqlite configuration." ); } } module.exports = { defaultConnection: "default", connections: { default: { connector: "bookshelf", settings: settings, options: options, }, }, };