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
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
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
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
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
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: 'firstname.lastname@example.org' domain: 'example.com' developer: email: 'email@example.com'
To see what other options may be changed, have a look at
3. Setting up
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
base/scripts/create-folders.sh base/scripts/set-permissions.sh [<cache-owner (default `whoami`)> [<cache-group (default www)>]]
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
If you used the sample content, your should already see a working site. Click on
Translation missing: login to log in using the credentials
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
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
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.