Getting Started

This guide covers getting up and running with Alchemy CMS. After reading it, you should be familiar with:

  • Installing and creating a new application with Alchemy CMS
  • Creating a user and logging in for the first time.

1 Prerequisites

This guide is designed for beginners who want to get started with Alchemy CMS from scratch. It does not assume that you have any prior experience with Alchemy CMS. However, to get the most out of it, you need to have some prerequisites installed:

Alchemy CMS needs at least version 6.4 of ImageMagick

1.1 Installing dependencies

It is highly recommended to use a package manager to install dependencies like ImageMagick and your database.

Common package managers are:

  • Homebrew on the Mac
  • Your Linux box already has a package manager installed and you likely are already familiar with it.

1.2 Installing Ruby

The most common ways to install Ruby on your computer nowadays are:

1.3 Learning Rails

It is highly recommended to familiarize yourself with Ruby on Rails before using Alchemy CMS. You will understand much more and see things clearer if you know about the basics of Ruby on Rails.

There are many excellent resources on the internet for learning Ruby on Rails, including:

2 Installating Alchemy

2.1 As a stand alone project

The installation of Alchemy CMS is very easy. You just need to run the gem command.

gem install alchemy_cms

The gem provides an executable file that can automagically create new rails applications with a pre-configured Alchemy CMS engine. While the installation process you will get asked about your local development environment. Just follow the instructions.

alchemy new YOUR_APP_NAME

The following parameters are available for the installer:

  • --database=sqlite3
  • --scm=git/svn

The installer creates a database, migrates the tables and also seeds them. After finishing, your application is ready to start!

2.2 Install into an existing Rails application

If you already have an existing Rails application, you can require the Alchemy CMS gem in your app.

Just add this line to your Gemfile.

gem 'alchemy_cms', '~> 3.0.0'

Since Alchemy CMS is a mountable engine, you need to define the mountpoint in your config/routes.rb file.

MyApp::Application.routes.draw do
  mount Alchemy::Engine => '/'

You can mount Alchemy on every route you want. pages, cms, what ever you want. Most of the time you go with the root route.

Please be aware that Alchemy has a very strong catch all route. It is highly recommended that you mount Alchemy at last position in your app, so your existing routes are still available.

Now you need to run bundler for installing the dependencies.

bundle install

Then run the install task.

bundle exec rake alchemy:install
2.2.1 Authentication

If you already have your own user class in your application, you have to tell Alchemy about it. Please follow this guide to learn how to achieve that.

If you don’t have a authentication solution, you can use the alchemy-devise gem.

Just add it to your apps Gemfile

# Gemfile
gem 'alchemy-devise', github: 'magiclabs/alchemy-devise', branch: '2.0-stable'

bundle install

and run the installer

bin/rake alchemy_devise:install:migrations db:migrate

3 Running Alchemy CMS!

Now that you have Alchemy CMS successfully installed, let’s move on by creating your first user with administrative privilegs.

You just need to start a local ruby server on your development machine.


bin/rails s

Open a browser window and navigate to http://localhost:3000. You will be greeted with a screen that is prompting you to create the first user.

Congratulations, you can now access the backend!

4 Next steps

As next you should to read about: