Installation

Thomas Gressly edited this page Jun 1, 2015 · 17 revisions

Simple installation

1. Getting a copy

1.1 Step 1: Cloning

Your best bet at installing rapila is to clone the cms-full repository:

git clone git://github.com/rapila/cms-full.git my-site
cd my-site
git checkout 1.0.0
git submodule update --init --recursive

Instead of the release 1.0.0 tag, you might also checkout other versions or the unstable master branch. Note, however, that unstable versions of cms-base might not always have a corresponding version of the cms-full distribution, so you might need to run the migrate-model.sh script manually and do some other manual changes. Your safest bet is therefore to checkout a stable cms-full distribution and with it a stable release of the base cms (all release tags in cms-base should be mirrored in cms-full), which will give you an up-to-date sample config.yml file and example.sql dump.

1.2 Step 2: Cleanup

If you use git to manage your projects, you may just remove the origin remote and use my-site as your new repo:

git remote rm origin

If you’re not that into git, just remove the .git folders from my-site and all its submodules. Note, however, that this will make upgrading your base folder (the CMS itself) a bit harder.

Note: If you checked out the master branch of the cms-full distribution in the previous step, its base submodule might not always be at the latest base CMS version. To correct this, use:

cd base
git checkout master
cd ..

Instead of the unstable master branch, you may also use the name of another tag (like 1.0.0) or branch (like release-1.0).

2. Configuring to your needs

Note that the cms-full distribution comes with a sample site folder. Also, most configuration options are set to a sensible default. All settings are stored in YAML files inside the config directory in either the base, site or one of the plugin folders (for more information on the directory structure, see Directory Structure). To begin, create a new MySQL user and database (other RDBMS are supported in theory, but remain largely untested; for more information, see Other Databases). Then, configure your database settings:

cp site/config/db_config.yml.default site/config/db_config.yml

Use your favourite editor on the file site/config/db_config.yml. Change the entries for myusername, mypassword and the dsn to match your configuration. To actually create the required tables on the database, use either the (empty) schema.sql file from base/data/sql or insert the provided sample data using site/data/sql/example.sql.

There are also some configuration settings you should change. Open site/config/config.yml and set the following:

domain_holder:
  name: 'My Example Site'
  email: 'your-email@example.com'
  domain: 'example.com'
developer:
  email: 'webmaster@example.com'

To see what other options may be changed, have a look at base/config/config.yml.

3. Setting up

Make sure my-site is somehow accessible on a PHP-enabled web server (a .htaccess file is included for Apache; you will need to configure the necessary rewrites yourself for other servers, see Nginx Configuration) for testing.

To ensure the CMS has the correct permissions set up, use the following scripts (make sure your $PWD is the my-site folder):

base/scripts/create-folders.sh
base/scripts/set-permissions.sh [<cache-owner (default `whoami`)> [<cache-group (default www)>]]

That cache-group needs to be a group that contains the user your PHP is running under.

The latter script might complain about some non-existant folders that we don’t care about right now but that’s ok.

You’re now ready to take a first look at the rapila CMS. Open your browser and go to http://localhost/path/to/my-site/.

If you used the sample content, your should already see a working site. Click on Translation missing: login to log in using the credentials admin/admin.

If you used the empty schema, you will be redirected to a login prompt. Enter any name/password combination you wish to create your administrator. Click the second-to-leftmost button in the menu bar to go to the pages administration and have rapila create a root page for you.

To change your user data, click on the button left of the logout knob.

Installation with an empty site folder

tbd.

Deployment

The deployment process is actually quite similar to the development installation. The environment variable RAPILA_ENVIRONMENT controls whether settings should be optimized for development, deployment, staging/testing, etc. It defaults to auto if unset, which resolves to production in most cases (for further details on how this is resolved, check out ErrorHandler.php).

For production environments, it is still recommended to set the environment explicitly, if only for the slight performance benefit. When using mod_php in Apache, use the SetEnv directive as demonstrated by the included sample .htaccess file. If you’re using php via CGI, modify your CGI php-wrapper script to contain the line export RAPILA_ENVIRONMENT=production.

Most likely, you’ll have a different database configuration in your production environment. Since all rapila config files can be overridden on a per-environment basis, this is trivial to set up: create a new folder site/config/production (if it doesn’t already exist) and throw your production-specific db_config.yml file in there.

Troubleshooting

tbd.