denny/ShinyCMS

ShinyCMS - Getting Started
==========================

This is a quick guide to getting a new ShinyCMS site up and running.


PERL MODULES

Run 'perl Makefile.PL' to check if you have all the required modules installed.  
If any are missing, please install them from CPAN.


APACHE

There is a sample httpd.conf in the folder docs/sample-apache-conf - uncomment 
the appropriate section to suit your set-up (fastcgi/mod_perl/etc), edit it to 
use the appropriate hostname etc, and then Include the file from your main 
httpd.conf or apache.conf file.

If you want to run more than one ShinyCMS site on a single server, then you 
will need to use the external FastCGI server method of deployment... mod_perl 
will only support one ShinyCMS installation on a server.  More information on 
deploying Catalyst applications can be found via Google, or here:
http://wiki.catalystframework.org/wiki/deployment

Make sure that your root/static/cms-uploads directory tree is writeable by 
whatever user your ShinyCMS process is running as.  For external FastCGI 
servers this is probably the website owner, for mod_perl it will be whatever 
user Apache runs as - often 'www-data' or similar.

(ShinyCMS has also been successfully run via nginx.  A sample config is 
included but is not well tested - feedback welcome!)


MYSQL

There are a number of utility scripts in bin/database/ for setting up and 
accessing the database.

First, use your preferred MySQL administration tools to create a database, 
and a user with permission to create tables in it.  Then edit the Model::DB 
section of config/shinycms.conf to use these connection details.

Once this is done, you can either run bin/database/build to create a database 
containing only the data required to make the system work, or you can run 
bin/database/build-with-demo-data to build a database containing some demo 
data (blog posts with comments and tags, news items, events, etc).

If you prefer not to create a user with table-creation privileges, you can 
insert database/schema.sql as a suitably-privileged user, and then use the 
bin/database/insert-* scripts to manually insert whatever level of data you 
want.  At minimum, you will need the data from insert-required-data.

If you want to use the mysql command line to access the database at any point, 
the utility script bin/database/connect will connect you using the connection 
details in your shinycms.conf file.

(ShinyCMS has also been successfully run using Postgres, but this is not 
well tested - feedback welcome!)


EMAILS

For any of ShinyCMS's email-sending features to work, you will need access 
to a mail server (either on the same server or another one; you can configure 
it in the View::Email and View::Email::Template sections of shinycms.conf).  
For more details on what options are availabe to you here, see: 
https://metacpan.org/pod/Catalyst::View::Email#CONFIGURATION

Before using any of the email features, please check that you have set an 
appropriate site_email in shinycms.conf!

ShinyCMS can be configured to send emails from form submissions, for use in 
constructing 'contact us' forms etc.  You can configure the address these are 
sent to on a per-form basis, or it will default to the site_email setting.

When building templates for forms which will send emails, note that the 
following fields have special meaning:

 * email_from => if set, the email from ShinyCMS will appear to come from this 
   email address (it will be checked for validity during the form submission).

 * email_from_name => if this is also set, the email from ShinyCMS will also 
   appear to come from this name.

 * email_subject => if set, the email from ShinyCMS will use this subject.


RECAPTCHA

ShinyCMS uses reCaptcha for spam-blocking on comment and contact forms.  There 
is a global key included in shinycms.conf, but we recommend that you get your 
own key from the reCaptcha website (in case we have to revoke and change the 
included key): https://www.google.com/recaptcha/admin/create?app=ShinyCMS


CONFIGURATION

Besides those options already mentioned, there are various config options in 
shinycms.conf which you will probably want to change - site_name, domain, etc.

The allow_user_registration option sets whether or not users can register on 
your website (rather than only user admins being able to add users).  Set it 
to 'yes' (case insensitive) to allow user registrations - any other setting 
will disallow them.


ADMINISTRATION

Once your site is up and running, you can log into the admin interface by 
visiting http://your-site/admin

The default admin user has username 'admin' and password 'changeme'.  Please 
do change the admin password!  Or, even better, use the default account to 
create your own user account, given that full admin privileges, then log in 
as you and delete the default 'admin' account.


CONTENT / PAGES

If you build the site using the bin/database/build script then you will need 
to add at least one CMS Template, one CMS Section and one CMS Page (in that 
order) before you will have a working front-end site.

Look at the sample templates and in the demo data for examples (see the various 
bin/database/util/insert-*-demo-data scripts, or build the database with the 
demo data loaded using bin/database/build-with-demo-data).


TEMPLATES

There are a number of sample templates included with ShinyCMS to provide you 
with some examples of what sort of thing you can do on a page.  In particular, 
the homepage.tt template uses some utility methods to pull in and display the 
latest events, news and blog posts.

When you have built a template file, you need to add it to the CMS using the 
admin 'add a new template' page, then you need to add the required elements 
to that CMS template.  Once this is done, any pages created using that 
template will automatically pick up the required element set.  NB: if you 
change the element set for a template after creating a page from it, the 
element set for that page will not update automatically.


FILESERVER / RESTRICTED FILES

You can have files which will only be served to logged-in users who belong 
to a specified access group.  The way this works is that you put them into a 
folder like so - root/restricted-files/{Access Group Name}/path/to/file.png - 
then create the appropriate access group (in the user admin area), and add 
users to that new access group if you want them to be able to see that 
restricted content.

To serve these files, construct a URL like the following:
http://example.com/fileserver/auth/{Access Group Name}/path/to/file.png


DOCKER

As of version 0.9.0, ShinyCMS is available as a Docker image:
docker pull shinyideas/shinycms

You will need to emplace various folders in /home/site (or wherever you decide 
to put all your config, templates, and assets).  Look at the volume mounts in 
bin/docker/shinycms-docker-run for a suggested layout, but feel free to modify 
it to suit your needs!

You can download a starter-pack of templates etc for use with Docker, here:
http://shinycms.org/static/shinycms-docker-assets-0.9.0.tar.gz

You can configure some of the Docker settings in: bin/docker/script.config


DEVELOPMENT

If you are considering extending and improving ShinyCMS, please read the file 
docs/Developer-Notes (and take a look in docs/TODO too).


IRC

If you would like to talk to other ShinyCMS users and/or developers, please 
join #shinycms on irc.freenode.net