AlchemyCMS

Alchemy is an open source CMS engine written in Ruby on Rails.

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

[!CAUTION] This main 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 (8.0-stable).**

🏆 Main sponsor

✅ Features

• Flexible templating that separates content from markup
• A rich RESTful API
• Intuitive admin interface with live preview
• Multi language and multi domain
• Page versioning
• SEO friendly urls
• User Access Control
• Build in contact form mailer
• Attachments and downloads
• On-the-fly image cropping and resizing
• Extendable via Rails engines
• Integrates into existing Rails Apps
• Resourceful Rails admin
• Flexible caching
• Hostable on any Server that supports Ruby on Rails, a SQL Database and ImageMagick

🎮 Demo

Visit the existing demo at https://demo.alchemy-cms.com/

• Login: demo
• Password: demo123

🚂 Rails Version

This version of AlchemyCMS runs with >= Rails 7.2

• For a Rails 7.1 compatible version use the 8.0-stable branch.
• For a Rails 7.0 compatible version use the 7.4-stable branch.
• For a Rails 6.1 compatible version use the 7.0-stable branch.
• For a Rails 6.0 compatible version use the 6.1-stable branch.
• For a Rails 5.2 compatible version use the 5.3-stable branch.
• For a Rails 5.0 or 5.1 compatible version use the 4.5-stable branch.
• For a Rails 4.2 compatible version use the 3.6-stable branch.
• For a Rails 4.0/4.1 compatible version use the 3.1-stable branch.
• For a Rails 3.2 compatible version use the 2.8-stable branch.
• For a Rails 3.1 compatible version use the 2.1-stable branch.
• For a Rails 3.0 compatible version use the 2.0-stable branch.
• For a Rails 2.3 compatible version use the 1.6-stable branch.

[!NOTE] For Rails >= 8, use Alchemy version >= 8.0.0a which comes with propshaft support. If you are on Rails >= 8 with an older Alchemy version, you will need to temporarily comment out the propshaft gem.

💎 Ruby Version

Alchemy runs with Ruby >= 3.1.0 including 4.0.

For a Ruby 3.0 compatible version use the 7.2-stable branch.

For a Ruby 2.4 compatible version use the 5.2-stable branch.

For a Ruby 2.2 compatible version use the 4.1-stable branch.

For a Ruby 2.1 compatible version use the 3.6-stable branch.

For a Ruby 2.0.0 compatible version use the 3.2-stable branch.

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

Stand Alone Installation

If you do not have a Rails project yet or just want to check out Alchemy, then use this Rails template.

Make sure you have Rails installed first:

$ gem install rails

Then create a new Rails project with:

$ rails new -m https://raw.githubusercontent.com/AlchemyCMS/rails-templates/master/all.rb <MY-PROJECT-NAME>

and follow the on screen instructions.

Manual Installation

If you want to manually install Alchemy into your Rails project follow these steps.

Add the Alchemy gem:

Put Alchemy into your Gemfile with:

$ bundle add alchemy_cms

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:

$ bundle add alchemy-devise

Then run the alchemy-devise installer:

$ bin/rails g alchemy:devise:install

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.configure do |config|
  config.user_class          = 'YourUserClass'          # This has to be configured
  config.current_user_method = 'current_admin_user'     # Defaults to 'current_user'
  config.signup_path         = '/your/signup/path'      # Defaults to '/signup'
  config.login_path          = '/your/login/path'       # Defaults to '/login'
  config.logout_path         = '/your/logout/path'      # Defaults to '/logout'
  config.logout_method       = 'http_verb_for_logout'   # Defaults to 'delete'
  config.unauthorized_path   = '/some/public/page'      # Defaults to '/'
end

Alchemy needs a alchemy_roles column in your database for the RBAC to work.

Alchemy provides a migration generator that adds these tables to your users table.

$ bin/rails g alchemy:user_columns_migration --table-name=my-users-table

Then include this module in your model.

class User
  include Alchemy::UserMethods
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/rails 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 '/'

🏗 Customization

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

Picture caching

Alchemy uses the Dragonfly gem to render pictures on-the-fly.

To make this as performant as possible the rendered picture gets stored into public/pictures so the web server can pick up the file and serve it without hitting the Rails process at all.

This may or may not what you want. Especially for multi server setups you eventually want to use something like S3.

Please follow the guidelines about picture caching on the Dragonfly homepage for further instructions:

http://markevans.github.io/dragonfly/cache

We also provide an extension for Cloudinary

🌍 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 output of your Rails app when starting. There will probably be useful information about deprecations.

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.

$ bin/rake alchemy:install:migrations
$ bin/rake db:migrate
$ bin/rake alchemy:db:seed
$ bin/rake alchemy:upgrade:config
$ bin/rake alchemy:upgrade:run

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:4.1

runs only the Alchemy 4.1 upgrade

🚀 Deployment

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

Please use 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.

🗃 Writing Migrations

On SQLite, a migration that rebuilds a table silently deletes data from other tables.

SQLite has no real ALTER TABLE, so Rails implements the operations below by recreating the table: it copies the rows aside, runs DROP TABLE, and copies them back.

• change_column
• change_column_null
• change_column_default
• rename_column
• remove_column and remove_columns
• add_timestamps
• add_column with null: false and no default:

With foreign keys enforced, SQLite's DROP TABLE performs an implicit DELETE, which fires ON DELETE CASCADE. The rebuilt table keeps its rows, because they come back from the copy, but every cascading descendant is deleted permanently. Since Alchemy cascades from pages down to ingredients, rebuilding alchemy_pages empties alchemy_page_versions, alchemy_elements and alchemy_ingredients.

Rails tries to prevent this by disabling foreign keys for the rebuild, but that only works outside a transaction, and migrations run inside one by default. The safeguard is therefore silently ineffective.

So when a migration touches a table that has cascading children:

1. Avoid the rebuild if you can. add_column with both null: false and a default: is a plain ALTER TABLE ADD COLUMN. A nullable column combined with a model level default behaves the same on every adapter, and is the only option for MySQL text columns, which cannot carry a literal default.
2. If a rebuild is unavoidable, including remove_column in down, declare disable_ddl_transaction! in the migration. Because it no longer rolls back as a single unit, make sure the migration is safe to run again after a partial failure.
3. Test against a populated database and check that child records survive. An empty database hides the problem completely.

You can check the migrations in this repository with:

ruby bin/check-destructive-migrations

This also runs in CI, and fails when a migration rebuilds a table without disable_ddl_transaction!.

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

Using Docker (recommended):

$ docker compose build
$ docker compose up

This starts the Rails dev server, Sass watcher, and JS bundle watcher. The dev server is available at http://localhost:3000.

Local setup:

$ bin/setup

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:

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

To run the whole stack in Docker (builds the images and starts the Rails server, Sass watcher, and JS bundle watcher):

$ bin/start

After changing dependencies (Gemfile or package.json), rebuild the image and refresh the baked node_modules in one step:

$ bin/start --refresh

Or, to run the dummy app locally without Docker:

$ bin/dev

📦 Releasing

🤖 Automated (recommended)

There is a Rake task that helps you to release a new version of Alchemy.

$ bundle exec rake alchemy:release

[!NOTE] This will release a new patch level

If you want to release a new minor or major version you can do so by setting the VERSION environment variable accordingly.

$ bundle exec rake alchemy:release VERSION=X.Y.Z

👷🏽‍♀️ Manual

If something goes wrong with the automated release task you can still release a new version manually.

1. Bump version

Bump the version number in lib/alchemy/version.rb.

2. Update the changelog

$ export GITHUB_ACCESS_TOKEN=...
$ PREVIOUS_VERSION=4.1.0 bundle exec rake alchemy:changelog:update

3. Commit version bump

$ git commit -am "Bump version to vX.Y.Z"

4. Release a new version

This task will publish the ruby gem. It also tags the latest commit.

$ bundle exec rake release

❓Getting Help

• Read the guidelines: https://guides.alchemy-cms.com.
• Read the documentation: https://www.rubydoc.info/github/AlchemyCMS/alchemy_cms
• If you think you found a bug please use the issue tracker on Github.
• For questions about general usage please use Stack Overflow or the Slack.
• New features should be discussed on our Trello Board.

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

• Homepage: https://alchemy-cms.com
• Live-Demo: https://demo.alchemy-cms.com (user: demo, password: demo123)
• API Documentation: https://www.rubydoc.info/github/AlchemyCMS/alchemy_cms
• Issue-Tracker: https://github.com/AlchemyCMS/alchemy_cms/issues
• Sourcecode: https://github.com/AlchemyCMS/alchemy_cms
• Slack: https://alchemy-cms.slack.com
• Mastodon: https://ruby.social/@alchemy_cms

✍️ Authors

• Thomas von Deyen: https://github.com/tvdeyen
• Martin Meyerhoff: https://github.com/mamhoff
• Sascha Karnatz: https://github.com/sascha-karnatz
• Robin Böning: https://github.com/robinboening

Alumni

• Marc Schettke: https://github.com/masche842
• Hendrik Mans: https://github.com/hmans
• Carsten Fregin: https://github.com/cfregin

🏅 Contributors

This project exists thanks to all the people who contribute. [Contribute].

💵 Backers

Thank you to all our backers! 🙏 [Become a backer]

💰 Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

📜 License

BSD-3-Clause

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

That will help us to keep Alchemy awesome.

Thank you!

❤️