*) 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:

Localization

Alchemy ships with one default English translation for the admin interface. If you want to use the admin interface in other languages please have a look at the alchemy_i18n project.

Upgrading

We, the Alchemy team, take upgrades very seriously and we try to make them as smooth as possible.
Therefore we have build an upgrade task, that tries to automate the upgrade procedure as much as possible.

That's why after the Alchemy gem has been updated, with explicit call to:

$ bundle update alchemy_cms

you should always run the upgrader:

$ 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.

Customize the upgrade preparation

The Alchemy upgrader comes prepared with several rake tasks in a specific order.
This is sometimes not what you want or could even break upgrades.
In order to customize the upgrade preparation process you can instead run each of the tasks on their own.

WARNING: This is only recommended, if you have problems with the default rake alchemy:upgrade task and need to
repair your data in between. The upgrader depends on these upgrade tasks running in this specific order, otherwise
we can't ensure smooth upgrades for you.

Run an individual upgrade

You can also run an individual upgrade on its own:

$ bin/rake -T alchemy:upgrade

provides you with a list of each upgrade you can run individually.

Example

$ bin/rake alchemy:upgrade:3.2

runs only the Alchemy 3.2 upgrade

Deployment

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

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.