Getting Started v4

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

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

Prerequisites

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

• The Ruby programming language
• At least one of these databases: MySQL or PostgreSQL
• The image processing library ImageMagick

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.

Installing Ruby

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

• If you are on a Mac or Linux Box use RVM
• If you are on Windows use RailsInstaller

Learning Rails

It is highly recommended to familiarize yourself with Ruby on Rails before using AlchemyCMS. 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:

• Try Ruby
• Getting Started with Rails
• Rails for Zombies
• Railscasts

Installing Alchemy

Create the Rails application

The installation of AlchemyCMS is very easy. You just need to run Ruby's gem command.

gem install alchemy_cms

Alchemy is a Rails 4 engine, so at first you need to generate a fresh Rails 4 application, by running this command

rails new YOUR_APP_NAME

INFO

The rails command has lots of parameters like choosing the database you want to work with. Please follow the official Rails guides for further information.

Install Alchemy into the Rails application

In your existing Rails application, you can need to require the AlchemyCMS gem.

Just add this line to your Gemfile.

gem 'alchemy_cms'

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

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

TIP

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.

NOTE

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.

bin/rake alchemy:install

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'

bundle install

and run the installer

bin/rails g alchemy:devise:install

Starting AlchemyCMS

Now that you have AlchemyCMS 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.

cd YOUR_APP_NAME

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.