README.md
# Pageflow
[](http://badge.fury.io/rb/pageflow)
[](https://github.com/codevise/pageflow/actions)
[](https://codeclimate.com/github/codevise/pageflow)
[](https://houndci.com)
Multimedia storytelling for the web. Built in cooperation with [WDR](https://wdr.de).
For a high level introduction and example Pageflow stories see
[pageflow.io](https://pageflow.io).
* [Getting Started](https://github.com/codevise/pageflow/wiki/Getting-Started)
* [Guides](https://github.com/codevise/pageflow/blob/master/doc/index.md)
* [JavaScript API Reference of `pageflow` package](http://codevise.github.io/pageflow-docs/js/master/index.html)
* [List of Plugins](https://github.com/codevise/pageflow/wiki/List-of-Plugins)
## Updating
For instructions on how to update from a prior version of the gem see
the
[Updating Pageflow](https://github.com/codevise/pageflow/wiki/Updating-Pageflow)
wiki page.
## Ingredients
Pageflow is a Rails engine which roughly consists of the following
components:
* A full MVC stack to manage and display Pageflow stories
* User and permission management with support for isolated accounts
and user collaboration
* A client side application for live preview editing of stories
* Background jobs to process and encode images, audios and videos
* Generators to quickly bootstrap a new Rails application
Pageflow assumes the following choice of libraries:
* [Devise](https://github.com/plataformatec/devise) for authentication
* [CanCanCan](https://github.com/CanCanCommunity/cancancan) for authorization
* [ActiveAdmin](http://activeadmin.info/) for administration
* [Resque](https://github.com/resque/resque) for as default for background jobs
* [FriendlyId](https://github.com/norman/friendly_id) for pretty URLs
* [Paperclip](https://github.com/thoughtbot/paperclip) for attachment handling
* [Backbone](http://backbonejs.org/) [Marionette](http://marionettejs.com/) for the editor
* [React](https://facebook.github.io/react/)/[Redux](http://redux.js.org/) for the frontend
## Requirements
Pageflow runs in environments with:
* Ruby >= 3.2
* Node >= 18
* Rails 7.1
* Redis server (for Resque)
* A database server supported by Active Record (tested with MySQL)
* ImageMagick
* [libvips](https://github.com/libvips/ruby-vips)
* [Audio Waveform Image Generator](https://github.com/bbc/audiowaveform#installation)
Accounts of the following cloud services have to be registered:
* [Amazon Web Services](http://aws.amazon.com) for S3 file storage and
(optionally) Cloudfront content delivery
* [Zencoder](http://zencoder.com) for video/audio encoding
## Installation
Generate a new Rails application using the MySQL database adapter:
$ rails new my_pageflow --database=mysql
$ cd my_pageflow
Do not name your application `"pageflow"` since it will cause conflicts
which constant names created by Pageflow itself.
### Database Setup
Enter valid MySQL credentials inside `config/database.yml` and create
the database:
$ rake db:create
### Gem Dependencies
Add these lines to your application's Gemfile, replacing `X.Y.Z` with
the current Pageflow version number. It is recommended to depend on a
specific minor version using the pessimistic version constraint
operator. See Pageflow's
[versioning policy](https://github.com/codevise/pageflow/blob/master/doc/versioning_policy.md)
for details.
# Gemfile
gem 'pageflow', '~> X.Y.Z'
# The install generator sets up Resque as Active Job backend
gem 'resque', '~> 1.25'
gem 'resque-scheduler', '~> 4.10'
gem 'ar_after_transaction', '~> 0.8.0'
gem 'redis', '~> 3.0'
gem 'redis-namespace', '~> 1.5'
Run bundler to install dependencies:
$ bundle install
### Running the Generator
Now you can run the generator to setup Pageflow and its dependencies:
$ rails generate pageflow:install
The generator will invoke Active Admin and Devise generators in turn
and apply some configuration changes. When asked to overwrite the
`db/seeds.rb` file, choose yes.
To better understand Pageflow's configuration choices, you can run the
single steps of the `install` generator one by one. See the wiki page
[The Install Generator in Detail](https://github.com/codevise/pageflow/wiki/The-Install-Generator-in-Detail)
for more. If you'd rather not look behind the scenes for now, you can
safely read on.
### Database Migration
Now you can migrate the database.
$ rake db:migrate
Finally, you can populate the database with some example data, so
things do not look too blank in development mode.
$ rake db:seed
## Configuration
Pageflow stores files in S3 buckets also in development
mode. Otherwise there's no way to have Zencoder encode them. See
[setting up external services](./doc/setting_up_external_services.md).
The host application can utilize environment variables to configure the API keys for S3 and Zencoder. The variables can be found in the generated Pageflow initializer.
For available configuration options and examples see the inline docs
in `config/initializers/pageflow.rb` in your generated rails app.
Ensure you have defined default url options in your environments
files. Here is an example of `default_url_options` appropriate for a
development environment in `config/environments/development.rb`:
config.action_mailer.default_url_options = {host: 'localhost:3000'}
In production, `:host` should be set to the actual host of your
application.
## Running Pageflow
In addition to the Rails server, you need to start two Rake tasks for
the background job processing. These tasks are listed in `Procfile` which
is generated in the project root folder by the Pageflow installer.
Consider using the [foreman gem](https://github.com/ddollar/foreman) to start all of
these processes (including the Rails server) with a single command in your
development environment.
The built-in Resque web server is mounted at `/background_jobs`. Use it to
inspect the state of background jobs, and restart failed jobs. This functionality
is only available for admins.
## Troubleshooting
If you run into problems during the installation of Pageflow, please refer to the [Troubleshooting](doc/troubleshooting.md) docs. If that doesn't help, consider [filing an issue](https://github.com/codevise/pageflow/issues?state=open).
## Security Policy
See [`SECURITY.md`](https://github.com/codevise/pageflow/blob/master/SECURITY.md).
## Contributing
Pull requests are welcome on GitHub at
https://github.com/codevise/pageflow. Everyone interacting in the
project's codebases, issue trackers and mailing lists is expected to
follow the
[code of conduct](https://github.com/codevise/pageflow/blob/master/CODE_OF_CONDUCT.md).
See the
[Contributing section](https://github.com/codevise/pageflow/blob/master/doc/index.md#contributing)
in the guides list for instructions on how to setup your development
environment. The
[GitHub wiki](https://github.com/codevise/pageflow/wiki#contributing-to-pageflow)
contains high level guides on common development workflows.
## License
The gem is available as open source under the terms of the
[MIT License](https://github.com/codevise/pageflow/blob/master/MIT-LICENSE).
## Special Thanks
Built in cooperation with:
[](https://wdr.de)
We would like to express our special thanks to the following services
for supporting Pageflow through free open source plans:
[](https://browserstack.com)