Alchemy is a powerful, flexible and user centric Rails CMS.
Ruby CSS HTML CoffeeScript Other
Latest commit 1bd4be4 Jul 21, 2016 @tvdeyen tvdeyen committed on GitHub Merge pull request #1086 from AlchemyCMS/first-published-at
Introduce new first_published_at page attribute
Failed to load latest commit information.
app Merge pull request #1086 from AlchemyCMS/first-published-at Jul 21, 2016
bin Make more understandable the help description on bin/alchemy May 6, 2016
config Fixes translations of es locale Jun 29, 2016
db/migrate Record the time when a page gets locked Jun 21, 2016
lib Add Bourbon - Package up sass support load handling in Jul 6, 2016
spec Don't change public_on when republishing pages Jul 19, 2016
vendor/assets Replace page public checkbox with date fields May 23, 2016
.codeclimate.yml Adds a codeclimate conf Apr 2, 2016
.editorconfig Adds hound and rubocop config files. Feb 26, 2015
.gitignore Add a klingon locale file Apr 11, 2016
.hound.yml Fail pull requests on hound violations Feb 8, 2016
.rspec Fixes rails version dependence and removes fuubar rspec format Apr 24, 2012
.rubocop.yml Disable Style/CollectionMethods cop Feb 5, 2016
.teatro.yml Fix assets usage on teatro [ci skip] Feb 18, 2015
.travis.yml Only build on travis for pushes to master Mar 31, 2016
.yardopts Fixed .yardopts to not parse the generators' ERB views. Nov 19, 2012
CHANGELOG.md Don't change public_on when republishing pages Jul 19, 2016
CODE_OF_CONDUCT.md Create CODE_OF_CONDUCT.md Jun 18, 2015
CONTRIBUTING.md Update CONTRIBUTING.md Jun 18, 2015
Gemfile Add Bourbon - Move sassc-rails into global gem group in Gemfile. Jul 6, 2016
LICENSE Fixes year in license file May 18, 2016
README.md Fixes note about latest stable version in README Jun 7, 2016
Rakefile Run rubocop auto-correct on source files Feb 5, 2016
alchemy_cms.gemspec Add Bourbon - Package up sass support load handling in Jul 6, 2016

README.md

Gem Version Build Status Code Climate Test Coverage Slack Status

CAUTION: This master branch is a development branch that can contain bugs. For productive environments you should use the current Ruby gem version, or the latest stable branch (3.3-stable).

About

Alchemy CMS

Alchemy is a powerful, flexible and user centric Rails CMS.

Read more about Alchemy on the website and in the guidelines.

Features

  • Highly flexible templating that completely separates content from markup
  • End-User centric graphical user interface
  • Multi language and multi domain
  • SEO friendly urls
  • User Access Control
  • Build in contact form mailer
  • Attachments and downloads
  • Powerful image rendering
  • Extendable via Rails engines
  • Integrates into existing Rails Apps
  • Flexible caching
  • Hostable on any Server that supports Ruby on Rails, a SQL Database and ImageMagick

Rails Version

This version of Alchemy CMS runs with Rails 4.2

Ruby Version

Alchemy runs with Ruby >= 2.0.0.

For a Ruby 1.9.3 compatible version use the 3.1-stable branch.

For a Ruby 1.8.7 compatible version use the 2.3-stable branch.

Installation

Install as a standalone project

Use the installer:

$ gem install alchemy_cms --pre
$ alchemy new my_magicpage

and follow the instructions to finish the installation.

The installer has some options (like choosing the database). See them with:

$ alchemy --help

Install into an existing Rails project

1. Add the Alchemy gem:

Put this into your Gemfile:

gem 'alchemy_cms', github: 'AlchemyCMS/alchemy_cms', branch: 'master'

NOTE: You normally want to use a stable branch, like 3.3-stable.

If you want to use Russian translation and have better i18n support, you should put:

gem 'russian', '~> 0.6.0'

or gem with similar functionality into your Gemfile.

2. Update your bundle:

$ bundle install

3. Set the authentication user

Now you have to decide, if you want to use your own user model or if you want to use the Devise based user model that Alchemy provides and was extracted into its own gem.

Use Alchemy user

If you don't have your own user class, you can use the Alchemy user model. Just add the following gem into your Gemfile:

gem 'alchemy-devise', github: 'AlchemyCMS/alchemy-devise', branch: 'master'

NOTE: You normally want to use a stable branch, like 3.3-stable.

Then run:

$ bundle install
$ bin/rake alchemy_devise:install:migrations
Use your User model

In order to use your own user model you need to tell Alchemy about it.

The best practice is to use an initializer:

# config/initializers/alchemy.rb
Alchemy.user_class_name     = 'YourUserClass'       # Defaults to 'User'
Alchemy.current_user_method = 'current_admin_user'  # Defaults to 'current_user'
Alchemy.signup_path         = '/your/signup/path'   # Defaults to '/signup'
Alchemy.login_path          = '/your/login/path'    # Defaults to '/login'
Alchemy.logout_path         = '/your/logout/path'   # Defaults to '/logout'

The only thing Alchemy needs to know from your user class is the alchemy_roles method.

This method has to return an Array (or ActiveRecord::Relation) with at least one of the following roles: member, author, editor, admin.

Example
# app/models/user.rb

def alchemy_roles
  if admin?
    %w(admin)
  end
end

Please follow this guide for further instructions on how to customize your user class even more.

4. Install Alchemy into your app:

After you set the user model you need to run the Alchemy install task:

$ bin/rake alchemy:install

Now everything should be set up and you should be able to visit the Alchemy Dashboard at:

http://localhost:3000/admin

*) Use your custom path if you mounted Alchemy at something else then '/'

Customizing

Alchemy has very flexible ways to organize and manage content. Please be sure to read the introduction guide in order to understand the basic idea of how Alchemy works.

Custom Controllers

Beginning with Alchemy 3.1 we do not patch the ApplicationController anymore. If you have controllers that loads Alchemy content or uses Alchemy helpers in the views (i.e. render_navigation or render_elements) you can either inherit from Alchemy::BaseController or you include Alchemy::ControllerActions in your controller (that's the recommended way).

Custom admin interface routing

By default, Alchemy Dashboard is accessible at http://example.com/admin. You can change this by setting Alchemy.admin_path and Alchemy.admin_constraints. For example, these settings:

# config/initializers/alchemy.rb

Alchemy.admin_path = '/backend'
Alchemy.admin_constraints = {subdomain: 'hidden'}

will move the dashboard to http://hidden.example.com/backend.

Upgrading

The Alchemy team takes upgrades very seriously and tries to make them as smooth as we can. Therefore we have build in upgrade tasks, that try to automate as much as possible.

That's why after updating the Alchemy gem you should always run the upgrader:

$ bundle update alchemy_cms
$ bin/rake alchemy:upgrade

Alchemy will print out useful information after running the automated tasks that help a smooth upgrade path. So please take your time and read them.

Always be sure to keep an eye on the config/alchemy/config.yml.defaults file and update your config/alchemy/config.yml accordingly.

Also, git diff is your friend. You are using git to track changes of your projects, right?

Deployment

Alchemy has an official Capistrano extension which takes care of everything you need to deploy an Alchemy site.

Please use https://github.com/AlchemyCMS/capistrano-alchemy, if you want to deploy with Capistrano.

Without Capistrano

If you don't use Capistrano you have to make sure that the uploads, tmp/cache/assets, public/assets and public/pictures folders get shared between deployments, otherwise you will loose data. No, not really, but you know, just keep them in sync.

Testing

If you want to contribute to Alchemy (and we encourage you to do so) we have a strong test suite that helps you to not break anything.

Preparation

First of all you need to clone your fork to your local development machine. Then you need to install the dependencies with bundler.

$ bundle install

To prepare the tests of your Alchemy fork please make sure to run the preparation task:

$ bundle exec rake alchemy:spec:prepare

to set up the database for testing.

Run your tests with:

$ bundle exec rspec

Alternatively you can just run*:

$ bundle exec rake

*) This default task executes the database preparations and runs all defined test cases.

Start the dummy app

You can even start the dummy app and use it to manually test your changes with:

$ cd spec/dummy
$ bin/rake db:setup
$ bin/rails s

A note about RSpec version:

Alchemy specs are written in RSpec 3. Please do not use deprecated RSpec 2.x syntax. Thanks

Getting Help

PLEASE don't use the Github issues for feature requests. If you want to contribute to Alchemy please read the contribution guidelines before doing so.

Resources

Authors

License

Spread the love

If you like Alchemy, please help us to spread the word about Alchemy and star this repo on GitHub, upvote it on The Ruby Toolbox, mention us on Twitter and vote for it on Bitnami.

That will help us to keep Alchemy awesome.

Thank you <3!