Apostrophe 2 Documentation

# Setting Up Your Environment

First you need to get your environment set up. You may already have some of the tools described below installed and configured, but make sure that you read carefully to make sure that you don't miss anything.

TIP

macOS is the most popular platform for Apostrophe CMS development, but there are plenty of developers using Linux or Windows. For macOS 10.9 or newer, continue with the instructions below. Windows users can use this lovely HOWTO for Windows contributed by Michael Brown to get everything set up, and Linux users can get going by installing the same operating system packages required by our deployment HOWTO.

Here's what you need to install:

  • XCode (required for all compilation on Macs)
  • Homebrew (for easy installing)
  • Git
  • Node (version 14.x) & npm
  • MongoDB
  • Optional: Imagemagick (for fast image manipulation with animated GIF support)

# Install XCode and Command Line Tools

First, you need to install the Xcode Command Line Tools.

  1. Open XCode (Download it from the App Store if you don't currently have it installed.)

  2. Go to Xcode → Preferences → Locations and set the version for the Command Line Tools Option.

TIP

Starting with XCode 6.1 the Command Line tools are automatically installed, and just need to be configured. For older versions of XCode, go to the Downloads tab under Preferences. From there you can select Install for the Command Line Tools options.

  1. Next, install the apostrophe-cli tool, which has several commands to make building a new project quick and easy. To install the Apostrophe CLI tool, run the following command:
# Install the apostrophe-cli module
npm install apostrophe-cli -g

It is completely possible to build Apostrophe projects without the CLI tool. This documentation will use it in various places because it does speed up development.

# Install Homebrew

Next, you need to install Homebrew (opens new window), a convenient software manager that makes it easier to manage and update your software packages.

NOTE

Throughout the tutorials, anything formatted like this is meant to be run at the terminal prompt. Basic familiarity with the terminal is very helpful for node and Apostrophe development.

  1. Launch the "Terminal" app.

  2. Copy and Paste this one-line command to the terminal to install Homebrew:

    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

# Install Node

Now that you have Homebrew installed it only takes one command to install Node:

brew install node

# Adjust your PATH

The terminal prompt finds commands in folders listed in an environment variable called PATH. We'll need to add node's directory to our $PATH in order for it to work its magic.

  1. Create a plaintext file called .profile in your home directory if you don't already have one. You can use the touch command from the command line to create a new file:

    touch ~/.profile

  2. Open it with your favorite text editor, or use the following command to open it with the default editor:

    open ~/.profile

  3. Add these two lines to the file and save it:

# ~/.profile
export NODE_PATH="/usr/local/lib/node"
export PATH="/usr/local/share/npm/bin:$PATH"

Verify that this worked by opening a new Terminal tab and running:

echo $PATH

If it worked, it will echo the current PATH setting as a set of colon-separated values, beginning with your additions.

# Install npm (Node Package Manager)

npm (opens new window) should have been installed with Node. Try:

npm

If you get a "not found" error, run this:

curl -L https://npmjs.org/install.sh | sh

# Install git

You'll need git to manage your source code. Macs come with it, but we suggest you get the latest via Homebrew. From the command line:

brew install git

# Install MongoDB

Apostrophe uses MongoDB as its database. You can install it with Homebrew. In addition, you can configure brew services to launch it automatically for you, so you don't have to fuss with restarting it manually.

  1. First you need to install the "tap" for Mongo DB:

    brew tap mongodb/brew

  2. Next install MongoDB:

    brew install mongodb-community

  3. After it is installed, start the MongoDB service:

    brew services start mongodb/brew/mongodb-community

  4. Now open a new terminal window and try:

    mongo

An interactive mongo prompt will start. Press control+c to exit.

TIP

"Hey, I got a connection failed error!" Make sure you ran brew services start mongodb-community.

# Install ImageMagick

Like most of what you've done so far, installing ImageMagick is just a matter of one command:

brew install imagemagick

This provides the convert and identify command line tools, which Apostrophe uses to scale and crop images quickly, with animated GIF support. If you skip this step, Apostrophe can still handle image uploads more slowly, thanks to Jimp (opens new window).

# Build a website!

Now your environment is configured you're ready to create your first Apostrophe project.

← Creating your first project →