[v4.0] Getting Started

The purpose of this guide is help new developers get up and running with BrowserCMS. It covers how to:

• Install the BrowserCMS gem
• Create a demo project to explore BrowserCMS
• Create a blank project for building a website from scratch

This guide is valid as of BrowserCMS v4.0.x. (Currently in beta)

This Guide Assumes

Before you can create a project using BrowserCMS, you will need to have the following installed.

1. The Ruby Language (Version 1.9.3+ or later required, as per Rails requirements. Ruby Version 2.1.x preferred.)
2. The Rails framework (use “gem install” instruction below)
3. A working installation of SQLite or MySQL as well as the gems for your database of choice.
4. A working copy of ImageMagick (for processing file uploads). See ImageMagick for general install instructions. We recommend using Homebrew for Mac users to install it.

Starting a demo project

This section of the guide will cover creating a sample website with BrowserCMS, using a demo website layout and content. The goal is to give you some content and templates to play with to explore the CMS. Later sections of this guide will cover the more common cases where you are creating a new website from scratch and want only the bare minimums.

Installing BrowserCMS

BrowserCMS is packaged as a gem which can be included in any Rails project. To install the gem, do the following: (the --pre is needed while 4.0 is in beta)

$ gem install browsercms --pre

Note: Installing BrowserCMS in this manner automatically installs Rails 4.0.×.

Editing the Database.yml file

Creating a new demo or “real” site with the bcms command below creates a new user on the database. For most backing databases, including MySQL, you will need to edit the root password in database.yml for this to succeed. This step is not required for SQLite3.

To do so, update the config/database.yml with correct username/password before your run rake db:install. This is covered in detail in the rails guides.

Creating a Demo Website

Currently, in 4.0.0 beta, sites created with the demo module throw errors. This is documented in Github issue #717.

Run the following from your terminal window.

$ bcms demo project_name

Then edit the config/database.yml file as above, if your database requires it, then:

$ cd project_name
$ rake db:install
$ rails server

If you are seeing an error containing “Could not find table ‘users’”, run

rake cms:install:migrations

before rake db:install.

If you are running 3.5.x there is a temporary work around for an existing issue, AFTER running rake db:install, prior to starting the server run:

$ rails g cms:template default

This will create a BrowserCMS project which used SQLite as the data storage. You need to have the sqlite3-ruby gem installed for this to work.

Using your Site

Open your browser to http://localhost:3000/cms to log into the admin for the CMS. Enter the default username/password (in development mode) is username=cmsadmin, password=cmsadmin. You should be now be logged in, viewing the home page of the site. You can now edit or add new content via the admin interface.

To learn more about the types of things you can do with BrowserCMS, see the User's Manual.

Starting a ‘Real’ project

Demo sites are fine for learning the ropes, but when its time to start working on a ‘real’ project, you don’t want a lot of dummy data that needs to be cleaned out. To start a typical, ‘blank’ project, you can run the following command. Here we will specify the -d flag, which will use MySQL as the database, but other well known databases like postgresql, sqlite3 and oracle are supported as well.

Run the following:

$ bcms new project_name -d mysql

Then edit the config/database.yml file as above, if your database requires it, then:

$ cd project_name
$ rake db:install
$ rails server

If you are seeing an error containing “Could not find table ‘users’”, run

rake cms:install:migrations

before rake db:install.

If you are running 3.5.x there is a temporary work around for an existing issue, prior to starting the server run:

$ rails g cms:template default

You need to have the mysql gem installed for this to work. This is going to create the development and testing copies of the database, migrate the db, populate it with the bare minimum content it needs, and copy all of the necessary files from the gem into the rails project. Open your browser to http://localhost:3000/cms to log in, using cmsadmin/cmsadmin as the username/password.

Getting Command line Help

You can get assistance from the commandline tool by running the bcms command with no arguments, like so:

$ bcms

This will show common usages, as well as all the help options available. The browsercms command piggybacks on top of the rails command, so many of the options available are the same as rails, including -f or —force.

Troubleshooting

This section covers some potential problems you might run into when trying to create a BrowserCMS project.

Creation fails to create MySQL Database

BrowserCMS will attempt to create and populate the database when you invoke rake db:install. When running against mysql, Rails will assume you have a username called root with an empty password. The database create/migrations will fail if you don’t have that username/password set. If this occurs, you can update the config/database.yml with correct username/password before your run rake db:install

Deploying to Production

Once you get ready to start deploying your application into production environments, be sure to review the Deployment Guide. There are several ‘gotchas’ to be aware of that may differ from deploying other Rails applications.