DOCSEARCHbyAlgolia
Submit Docs

AlchemyCMS Documentation

repository·main·Indexed 21 days ago

https://github.com/alchemycms/alchemy_cms

An open-source content management system engine for Ruby on Rails featuring a flexible templating system, RESTful API, and admin interface for managing content, users, and assets. Includes guides on installation via Rails templates or gems, custom user authentication, admin routing, automated upgrades, and deployment using Capistrano.

Tokens
4.9K
Snippets
22
Records
27
Agent score
74%

What's inside AlchemyCMS

  1. Manually install AlchemyCMS into an existing Rails app

    main

    To add AlchemyCMS to an existing Rails project, follow these steps:

    1. Add the gem: Run bundle add alchemy_cms.
    2. Configure Authentication: Choose between using the provided Devise-based user model or your own custom user model (see Configure custom user authentication).
    3. Install Alchemy: Once authentication is configured, run the installation task:
    $ bin/rails alchemy:install

    After installation, the Alchemy Dashboard will be available at http://localhost:3000/admin (unless you have changed the default path).

    $ bundle add alchemy_cms
$ bin/rails alchemy:install

  2. Install AlchemyCMS as a standalone project

    main

    If you want to start a new project with AlchemyCMS pre-configured, use the official Rails template. Ensure you have Rails installed first, then run the following command to create a new project using the Alchemy template:

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

    Follow the on-screen instructions to complete the setup.

  3. Start the dummy app for manual testing

    main

    To manually test changes, you can start the dummy application.

    Using Docker (Full Stack): Starts the Rails server, Sass watcher, and JS bundle watcher.

    bin/start

    If you change dependencies (Gemfile or package.json), rebuild the image and refresh node_modules with:

    bin/start --refresh

    Local Setup (Without Docker):

    bin/dev
    bin/start
# or
bin/start --refresh
# or
bin/dev

  4. Release a new version of Alchemy

    main

    Automated Release (Recommended)

    Use the Rake task to release a new patch level:

    bundle exec rake alchemy:release

    To release a specific minor or major version, set the VERSION environment variable:

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

    Manual Release

    If the automated task fails, follow these steps:

    1. Bump version: Update the version number in lib/alchemy/version.rb.
    2. Update changelog:
      export GITHUB_ACCESS_TOKEN=...
PREVIOUS_VERSION=4.1.0 bundle exec rake alchemy:changelog:update
    3. Commit: git commit -am "Bump version to vX.Y.Z"
    4. Publish: Run the release task to publish the ruby gem and tag the commit:
      bundle exec rake release

  5. Configure custom user authentication

    main

    To use your own existing User model, you must configure Alchemy in an initializer. The model must implement an alchemy_roles method that returns an Array (or ActiveRecord::Relation) containing at least one of these roles: member, author, editor, or admin.

    1. Configure the initializer:

    # config/initializers/alchemy.rb
Alchemy.configure do |config|
  config.user_class          = 'YourUserClass'
  config.current_user_method = 'current_admin_user'
  config.signup_path         = '/your/signup/path'
  config.login_path          = '/your/login/path'
  config.logout_path         = '/your/logout/path'
  config.logout_method       = 'http_verb_for_logout'
  config.unauthorized_path   = '/some/public/page'
end

    2. Implement alchemy_roles in your model:

    # app/models/user.rb
class User < ApplicationRecord
  def alchemy_roles
    if admin?
      %w(admin)
    else
      %w(member)
    end
  end
end

  6. Set up the development environment for testing

    main

    To prepare a local development environment for contributing to Alchemy, follow these steps:

    Using Docker (Recommended):

    docker compose build
docker compose up

    This starts the Rails dev server (at http://localhost:3000), Sass watcher, and JS bundle watcher.

    Local Setup:

    bin/setup

    Prepare the test database: Before running tests, you must run the preparation task to set up the database:

    bundle exec rake alchemy:spec:prepare

  7. Run tests in AlchemyCMS

    main

    You can run the test suite using RSpec or the default Rake task.

    Using RSpec:

    bin/rspec

    Using Rake:

    bundle exec rake

    Note: The default Rake task executes database preparations and runs all defined test cases.

    bin/rspec
# or
bundle exec rake

  9. Upgrade AlchemyCMS

    main

    Alchemy provides an automated upgrade task to ensure smooth transitions between versions.

    Standard Upgrade Procedure:

    1. Update the gem: bundle update alchemy_cms.
    2. Run the upgrader: bin/rake alchemy:upgrade.

    Advanced/Manual Upgrade: If the automated task fails or you need to repair data between steps, you can run the individual tasks in this specific order:

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

    Running specific version upgrades: You can list all available upgrade tasks with bin/rake -T alchemy:upgrade and run a specific version upgrade (e.g., 4.1) using: bin/rake alchemy:upgrade:4.1.

    $ bundle update alchemy_cms
$ bin/rake alchemy:upgrade

  10. Customize Alchemy controllers and admin routing

    main

    Custom Controllers

    To access Alchemy content or use helpers like render_menu or render_elements in your own controllers, you should either:

    • Inherit from Alchemy::BaseController.
    • (Recommended) Include Alchemy::ControllerActions in your controller.

    Custom Admin Interface Routing

    You can change the default admin path (/admin) and constraints by updating the Alchemy configuration:

    # config/initializers/alchemy.rb
Alchemy.admin_path = 'backend'
Alchemy.admin_constraints = {subdomain: 'hidden'}

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

  11. Use the Alchemy-provided Devise user model

    main

    If you do not have a user model yet, you can use the Devise-based model provided by Alchemy. Add the alchemy-devise gem to your Gemfile and run the installer:

    $ bundle add alchemy-devise
$ bin/rails g alchemy:devise:install

  12. Configure Page Preview URL and Sources

    main

    Alchemy uses a preview renderer in the Admin UI. By default, it uses an internal renderer, but you can point it to an external URL or define custom preview sources.

    External Preview URL

    Configure the preview object to set a host and authentication (Basic Auth is supported).

    Custom Preview Sources

    A preview source is a Ruby class inheriting from Alchemy::Admin::PreviewUrl that returns a URL for the preview frame. You must register these classes in preview_sources.

    # lib/acme/preview_source.rb
class Acme::PreviewSource < Alchemy::Admin::PreviewUrl
  def url_for(page)
    if page.site.name == "Next"
      "https://user:#{ENV['PREVIEW_HTTP_PASS']}@next.acme.com"
    else
      "https://www.acme.com"
    end
  end
end

# config/initializers/alchemy.rb
require "acme/preview_source"
Alchemy.config.preview_sources << "Acme::PreviewSource"
    # config/initializers/alchemy.rb
Alchemy.config.preview.host = "https://www.my-static-site.com"
Alchemy.config.preview.auth = {
  username: ENV["BASIC_AUTH_USERNAME"],
  password: ENV["BASIC_AUTH_PASSWORD"]
}