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:
- The Ruby programming language
- At least one of these databases: MySQL, PostgreSQL or SQLite
- The image processor ImageMagick
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:
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
MyApp::Application.routes.draw do mount Alchemy::Engine => '/' end
You can mount Alchemy on every route you want.
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.
Then run the install task.
bundle exec rake alchemy:install
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'
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.
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: