Development Setup

This article covers the first steps to get started. MacOS and Linux users can dive right in. If you have Windows, please follow our Windows development cookbook article first. For technical reliability and technical support, we require that Windows users develop using the Windows Subsystem for Linux (WSL 2) or a Linux virtual machine.

System requirements

Software	Minimum Version
Node.js	18.x+
MongoDB	4.4+

See the links above to install each. To check that these are installed in your environment, try the following commands:

node -v && npm -v
# This will display your Node.js version and npm version (installed with Node),
# if installed.
mongod --version
# This will display your MongoDB version, if installed.

NOTE

ImageMagick can be used if your system doesn't support the default npm sharp package. It provides the convert and identify command line tools, which Apostrophe uses to scale and crop images quickly. Apostrophe will automatically install sharp when you npm install your project, you do not have to add it yourself. If for any reason Apostrophe is unable to install its sharp dependency and ImageMagick has been installed on your system, Apostrophe will fall back to ImageMagick automatically.

The Apostrophe CLI tool

There is an official CLI (Command Line Interface) for quickly setting up starter code for your Apostrophe project. Once in a project it can also help add new module code with a single command so you can focus on the unique parts rather than copying or remembering boilerplate. Keep an eye out for updates once it is installed since it will continue to evolve to help with additional tasks.

Install the CLI tool:

npm install -g @apostrophecms/cli
# Or `yarn global add @apostrophecms/cli`, if you prefer. We'll stick to npm commands.

Once installed you have access to the apos command. Simply use that command, or apos --help, to see a list of additional commands anytime.

The CLI is not required to work with Apostrophe. It primarily makes developing with Apostrophe faster and takes care of the more repetitive tasks during development.

Creating a project

Before creating a project, make sure you start MongoDB locally following their instructions. MongoDB can be configured to run all the time or started as needed, but it must be up and running to provide a place for ApostropheCMS to store its information.

The easiest way to get started with Apostrophe is to use one of the official starter kit projects. If you have the CLI installed, go into your normal projects directory and use the command:

apos create apos-app

This will install the "Essentials" starter kit.

TIP

💡 To install other starter kits, pass the --starter flag, along with the short name of one of our starter kits. For example:

apos create apos-app --starter=ecommerce

The CLI will take care of installing dependencies and walk you through creating the first user. You can then skip down to the "Finishing touches" section. If you don't want to use the CLI, or if you want to see other things it does for you, continue on.

To get started quickly without the CLI, clone the starter repository:

git clone https://github.com/apostrophecms/starter-kit-essentials apos-app

If you want to change the project directory name, please do so. We will continue referring to apos-app.

Open the app.js file in the root project directory. Find the shortName setting and change it to match your project (only letters, digits, hyphens and/or underscores). This will be used as the name of your database.

// app.js
require('apostrophe')({
  shortName: 'apos-app', // 👈
  modules: {
  // ...

Excellent! Back in your terminal we'll install dependencies:

npm install

Before starting up you'll need to create an admin-level user so that you can log in. After running the following command, Apostrophe will ask you to enter a password for this user.

node app @apostrophecms/user:add my-user admin
# Replace `my-user` with the name you want for your first user.

Finishing touches

You should also update the session secret for Express.js to a unique, random string. The starter project has a placeholder for this option already. If you do not update this, you will see a warning each time the app starts up.

// modules/@apostrophecms/express/index.js
module.exports = {
  options: {
    session: {
      // If this still says `undefined`, set a real secret!
      secret: undefined
    }
  }
};

Starting up the website

Start the site with npm run dev. The app will then watch for changes in client-side code, rebuilds it, then refresh the browser when it detects any. You can log in with the username and password you created at http://localhost:3000/login.

TIP

If you are starting the site in a production environment or do not want the process to watch for changes, start the site with node app.js.

Next steps

Now that Apostrophe is installed, you're ready to start building. Check out the guide to learn about essential features with plenty of code examples. If you are looking to explore Apostrophe's inner workings peruse the reference guide.