Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@tvdeyen
tvdeyen committed Mar 29, 2019
1 parent 7bb27db commit cd70b89
Showing 1 changed file with 72 additions and 67 deletions.
139 changes: 72 additions & 67 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,27 @@
# AlchemyCMS

[![Gem Version](https://badge.fury.io/rb/alchemy_cms.svg)](http://badge.fury.io/rb/alchemy_cms)
[![Build Status](https://travis-ci.org/AlchemyCMS/alchemy_cms.svg?branch=master)](https://travis-ci.org/AlchemyCMS/alchemy_cms)
[![Maintainability](https://api.codeclimate.com/v1/badges/196c56c56568ed24a697/maintainability)](https://codeclimate.com/github/AlchemyCMS/alchemy_cms/maintainability)
[![Test Coverage](https://api.codeclimate.com/v1/badges/196c56c56568ed24a697/test_coverage)](https://codeclimate.com/github/AlchemyCMS/alchemy_cms/test_coverage)
[![Depfu](https://badges.depfu.com/badges/ebe56d2dd7b7044a8ae700cc81212a8e/overview.svg)](https://depfu.com/github/AlchemyCMS/alchemy_cms?project_id=4600)

[![Slack Status](http://slackin.alchemy-cms.com/badge.svg)](http://slackin.alchemy-cms.com)
[![Slack Status](https://slackin.alchemy-cms.com/badge.svg)](https://slackin.alchemy-cms.com)
[![Reviewed by Hound](https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg)](https://houndci.com)

[![Backers on Open Collective](https://opencollective.com/alchemy_cms/backers/badge.svg?color=blue)](#backers)
[![Sponsors on Open Collective](https://opencollective.com/alchemy_cms/sponsors/badge.svg?color=blue)](#sponsors)

**CAUTION: This master branch is a development branch that *can* contain bugs. For productive environments you should use the [current Ruby gem version](https://rubygems.org/gems/alchemy_cms), or the [latest stable branch (4.1-stable)](https://github.com/AlchemyCMS/alchemy_cms/tree/4.1-stable).**

[![Sponsors on Open Collective](https://opencollective.com/alchemy_cms/sponsors/badge.svg?color=blue)](#sponsors)

## About
<img src="./app/assets/images/alchemy/alchemy-logo.svg" width=300>

![Alchemy CMS](app/assets/images/alchemy/alchemy-logo.png)
Alchemy is an open source CMS engine written in Ruby on Rails.

Alchemy is a headless Rails CMS.
Read more about Alchemy on the [website](https://alchemy-cms.com) and in the [guidelines](https://guides.alchemy-cms.com).

Read more about Alchemy on the [website](https://alchemy-cms.com) and in the [guidelines](https://guides.alchemy-cms.com/stable/).
**CAUTION: This master branch is a development branch that *can* contain bugs. For productive environments you should use the [current Ruby gem version](https://rubygems.org/gems/alchemy_cms), or the [latest stable branch (4.1-stable)](https://github.com/AlchemyCMS/alchemy_cms/tree/4.1-stable).**


## Features
## ✅ Features

- Flexible templating that separates content from markup
- A rich RESTful API
Expand All @@ -38,7 +38,7 @@ Read more about Alchemy on the [website](https://alchemy-cms.com) and in the [gu
- Flexible caching
- Hostable on any Server that supports Ruby on Rails, a SQL Database and ImageMagick

## Demo
## 🎮 Demo

Deploy your own free demo on Heroku

Expand All @@ -49,7 +49,7 @@ or visit the existing demo at https://alchemy-demo.herokuapp.com
- Login: `demo`
- Password: `demo123`

## Rails Version
## 🚂 Rails Version

**This version of Alchemy CMS runs with Rails 5 only**

Expand All @@ -61,9 +61,11 @@ or visit the existing demo at https://alchemy-demo.herokuapp.com
* For a Rails 2.3 compatible version use the [`1.6-stable` branch](https://github.com/AlchemyCMS/alchemy_cms/tree/1.6-stable).


## Ruby Version
## 💎 Ruby Version

Alchemy runs with Ruby >= 2.3.0.

Alchemy runs with Ruby >= 2.2.2.
For a Ruby 2.2 compatible version use the [`4.1-stable` branch](https://github.com/AlchemyCMS/alchemy_cms/tree/4.1-stable).

For a Ruby 2.1 compatible version use the [`3.6-stable` branch](https://github.com/AlchemyCMS/alchemy_cms/tree/3.6-stable).

Expand All @@ -74,7 +76,7 @@ For a Ruby 1.9.3 compatible version use the [`3.1-stable` branch](https://github
For a Ruby 1.8.7 compatible version use the [`2.3-stable` branch](https://github.com/AlchemyCMS/alchemy_cms/tree/2.3-stable).


## Installation
## ⌨️ Installation

#### 1. Add the Alchemy gem:

Expand All @@ -88,7 +90,7 @@ gem 'alchemy_cms', github: 'AlchemyCMS/alchemy_cms', branch: 'master'

#### 2. Update your bundle:

```shell
```bash
$ bundle install
```

Expand All @@ -109,7 +111,7 @@ gem 'alchemy-devise', github: 'AlchemyCMS/alchemy-devise', branch: 'master'

Then run:

```shell
```bash
$ bundle install
$ bin/rake alchemy_devise:install:migrations
```
Expand Down Expand Up @@ -151,7 +153,7 @@ Please follow [this guide](http://guides.alchemy-cms.com/stable/custom_authentic

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

```shell
```bash
$ bin/rake alchemy:install
```

Expand All @@ -162,9 +164,9 @@ Now everything should be set up and you should be able to visit the Alchemy Dash
*) Use your custom path if you mounted Alchemy at something else then `'/'`


## Customizing
## 🏗 Customization

Alchemy has very flexible ways to organize and manage content. Please be sure to read [the introduction guide](http://guides.alchemy-cms.com/stable/index.html) in order to understand the basic idea of how Alchemy works.
Alchemy has very flexible ways to organize and manage content. Please be sure to read [the introduction guide](https://guides.alchemy-cms.com/about.html) in order to understand the basic idea of how Alchemy works.


### Custom Controllers
Expand All @@ -174,6 +176,7 @@ Beginning with Alchemy 3.1 we do not patch the `ApplicationController` anymore.
### 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:

```ruby
Expand All @@ -189,31 +192,33 @@ will move the dashboard to <http://hidden.example.com/backend>.

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

### Localization
We also provide an [extension for Cloudinary](https://github.com/AlchemyCMS/alchemy_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](https://github.com/AlchemyCMS/alchemy_i18n).

## Upgrading
## ✨ 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.
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:
```shell

```bash
$ bundle update alchemy_cms
```

you should **always run the upgrader**:
```shell

```bash
$ bin/rake alchemy:upgrade
```

Expand All @@ -230,7 +235,7 @@ 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.

```shell
```bash
$ bin/rake alchemy:install:migrations
$ bin/rake db:migrate
$ bin/rake alchemy:db:seed
Expand All @@ -246,60 +251,60 @@ we can't ensure smooth upgrades for you.

You can also run an individual upgrade on its own:

```shell
```bash
$ bin/rake -T alchemy:upgrade
```

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

#### Example

```shell
$ bin/rake alchemy:upgrade:3.2
```bash
$ bin/rake alchemy:upgrade:4.1
```

runs only the Alchemy 3.2 upgrade
runs only the Alchemy 4.1 upgrade

## Deployment
## 🚀 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.
Please use [capistrano-alchemy](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
## 🚧 Testing

If you want to contribute to Alchemy ([and we encourage you to do so](https://github.com/AlchemyCMS/alchemy_cms/blob/master/CONTRIBUTING.md)) we have a strong test suite that helps you to not break anything.
If you want to contribute to Alchemy ([and we encourage you to do so](CONTRIBUTING.md)) 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.

```shell
```bash
$ bundle install
```

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

```shell
```bash
$ bundle exec rake alchemy:spec:prepare
```

to set up the database for testing.

### Run your tests with:

```shell
```bash
$ bundle exec rspec
```

**Alternatively** you can just run*:

```shell
```bash
$ bundle exec rake
```

Expand All @@ -309,14 +314,14 @@ $ bundle exec rake

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

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


## Releasing
## 📦 Releasing

### Update the changelog

Expand All @@ -332,31 +337,29 @@ $ bundle exec rake release
```


## Getting Help
## ❓Getting Help

* Read the guidelines: http://guides.alchemy-cms.com.
* Read the documentation: http://rubydoc.info/github/AlchemyCMS/alchemy_cms
* If you found a bug please use the [issue tracker on Github](https://github.com/AlchemyCMS/alchemy_cms/issues).
* For questions about general usage please use [Stack Overflow](http://stackoverflow.com/questions/tagged/alchemy-cms), [the User Group](http://groups.google.com/group/alchemy-cms) or the [Slack](https://slackin.alchemy-cms.com).
* 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](https://github.com/AlchemyCMS/alchemy_cms/issues).
* For questions about general usage please use [Stack Overflow](http://stackoverflow.com/questions/tagged/alchemy-cms) or the [Slack](https://slackin.alchemy-cms.com).
* New features should be discussed on our [Trello Board](https://trello.com/alchemycms).

**PLEASE** don't use the Github issues for feature requests. If you want to contribute to Alchemy please [read the contribution guidelines](https://github.com/AlchemyCMS/alchemy_cms/blob/master/CONTRIBUTING.md) before doing so.
**PLEASE** don't use the Github issues for feature requests. If you want to contribute to Alchemy please [read the contribution guidelines](CONTRIBUTING.md) before doing so.


## Resources
## 🔗 Resources

* Homepage: <http://alchemy-cms.com>
* Live-Demo: <http://demo.alchemy-cms.com> (user: demo, password: demo123)
* API Documentation: <http://rubydoc.info/github/AlchemyCMS/alchemy_cms>
* 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>
* User Group: <http://groups.google.com/group/alchemy-cms>
* Slack: <https://slackin.alchemy-cms.com>
* Discussion Board: <https://trello.com/alchemycms>
* Twitter: <https://twitter.com/alchemy_cms>


## Authors
## ✍️ Authors

* Thomas von Deyen: <https://github.com/tvdeyen>
* Robin Böning: <https://github.com/robinboening>
Expand All @@ -365,20 +368,20 @@ $ bundle exec rake release
* Carsten Fregin: <https://github.com/cfregin>


## Contributors
## 🏅 Contributors

This project exists thanks to all the people who contribute. [[Contribute](CONTRIBUTING.md)].
<a href="https://github.com/undefined/undefinedgraphs/contributors"><img src="https://opencollective.com/alchemy_cms/contributors.svg?width=890&button=false" /></a>


## Backers
## 💵 Backers

Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/alchemy_cms#backer)]

<a href="https://opencollective.com/alchemy_cms#backers" target="_blank"><img src="https://opencollective.com/alchemy_cms/backers.svg?width=890"></a>


## Sponsors
## 💰 Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/alchemy_cms#sponsor)]

Expand All @@ -395,15 +398,17 @@ Support this project by becoming a sponsor. Your logo will show up here with a l



## License
## 📜 License

* BSD: <https://raw.githubusercontent.com/AlchemyCMS/alchemy_cms/master/LICENSE>
[BSD-3-Clause](LICENSE)


## Spread the love
## 📢 Spread the love

If you like Alchemy, please help us to spread the word about Alchemy and star this repo [on GitHub](https://github.com/AlchemyCMS/alchemy_cms), upvote it [on The Ruby Toolbox](https://www.ruby-toolbox.com/projects/alchemy_cms), mention us [on Twitter](https://twitter.com/alchemy_cms) and vote for it [on Bitnami](https://bitnami.com/stack/alchemy).
If you like Alchemy, please help us to spread the word about Alchemy and star this repo [on GitHub](https://github.com/AlchemyCMS/alchemy_cms), upvote it [on The Ruby Toolbox](https://www.ruby-toolbox.com/projects/alchemy_cms), mention us [on Twitter](https://twitter.com/alchemy_cms).

That will help us to keep Alchemy awesome.

Thank you <3!
Thank you!

## ❤️

0 comments on commit cd70b89

Please sign in to comment.