# Setting up

# System requirements

Software Minimum Version
Node.js 12.x+
MongoDB 3.6+
ImageMagick (optional) Any

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.
which convert && which identify
# This will display the location of the ImageMagick utilities, if installed.


ImageMagick is optional, but recommended. It provides the convert and identify command line tools, which Apostrophe uses to scale and crop images quickly. If you do not install it Apostrophe can still handle image uploads, though more slowly, using Jimp.

# Creating a project

The easiest way to get started with Apostrophe is to use the starter boilerplate project. On the command line, clone the boilerplate:

git clone https://github.com/apostrophecms/a3-boilerplate apos-app

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


There is a CLI tool for Apostrophe 2 with commands to create projects, among other tasks. That will support Apostrophe 3 closer to the 3.0 stable release.

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
  shortName: 'apos-app', // 👈
  modules: {
  // ...

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

// app.js
  shortName: 'apos-app',
  modules: {
    '@apostrophecms/express': {
      options: {
        session: {
          // ⚠️ If this still says `undefined`, set a real secret (a random
          // string)!
          secret: undefined
    // ...

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

npm install
# Or `yarn install`, if you prefer. We'll stick to npm commands.

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.

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.


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 essentials guide to learn about essential features or read more about Apostrophe's inner workings in the technical overview.