Welcome to Contao!
This gem will help you to quickly develop a website using Contao CMS which has pre-built support for Sass, Compass, CoffeeScript, Jasmine and Capistrano.
It also feature hashed assets served by the Contao Assets extension, which allows you to have an md5 appended to each of your assets URL on the production site.
<link rel="stylesheet" type="text/css" href="/resources/application-c6e2457d9ccce0f344c50e5bcc12fcdc.css" />
<script type="text/javascript" src="/resources/application-327af3660470fb1c3f8e6593670cfc1e.js"></script>All the images references by the CSS file, are also hashed, so when you deploy a new version of your image and/or your CSS, you are absolutely sure that your visitors do not get a cached copy of your old asset.
div
+background(image-url('body.jpg') no-repeat top center)Would generate:
div {
background: url(/resources/body-fc4a0f5f0b0f9ceec32bde5d15928467.jpg) no-repeat top center;
}Compass gives great power over your CSS, one most-wanted feature is the sprites, so having one PNG file for all your backgrounds is just awesome, the generate CSS looks like this
div
+background(sprite($background, body))Would generate:
div {
background: url(/resources/background-sbd69a8307b-a00c8f7a8536397c6279726316eae16f.png) 0 -3089px;
}Check Compass Sprites Documentation
Finally, the integration with Capistrano allows you to quickly deploy, copy assets, import database and even upload media such as images and PDFs all from the command line using Capistrano.
Before installing the gem, you need to make you are running on a Ruby version 1.9.2 or greater as this Gem and most of it's dependencies do not support Ruby 1.8, to check the version you are running, using the following command:
ruby --versionIf you're running a ruby version below 1.9, please install a 1.9 version by following the guide at the Rbenv Installer project.
Contao depends on Qt (for headless javascript testing using jasmine and jasmine-headless-webkit, to install it, refer to Capybara Webkit Installation
And Finally, you need Git as the whole template has been built for it, you can also work with a different SCM, but you need to get the template file yourself, initialize it and track it with your favorite SCM, something I strongly vote against.
Install contao with the following command
gem install contaoDon't forget to run rbenv rehash if you are using
rbenv as this gem provides
an executable.
Locally, the database name is the same as the application name, so if you named your project is named my_project, the database name will be named my_project.
On the server, Capistrano will append the environment on which the deployment occured (check the deployment section below for more information) to the application name, so if your project is named my_project and you are deployment to the staging environment, the database name would default to my_project_staging
To start using contao, you need to generate a config file, issue the command
contao generate configand follow the on-screen instructions.
Generating a new project is very easy, just use the following command:
contao new /path/to/my_projectThis command will generate an application called my_project in the
folder /path/to, the application name is very important as it defaults
to the name of your database, check the Database name
section below for more information.
Once the project generator has completed, cd into the newsly created project and bootstrap contao by running
bundle exec rake contao:bootstrapNow visit /contao/install.php or just visit the website and you should
be redirected to the Installation script, from here on it is the usual
Contao installation procedure, please check Contao's user
guide for
detailed information
To be able to develop with this version of Contao, you first need to understand how it actually works, take a look at the project structure for more information on how files are organised
Contao is integrated with Rails, actually only the asset pipeline functionality is being used, Compass is also integrated with the project so you can develop your CSS using Compass functions and mixins as well as sprites.
To start working on the project, you need to run the rails server by running
bundle exec foreman startThis will start a rails process on port 9876 and serve the assets from their, The Contao Assets Extension automatically detect that you are running in development and will use assets from the rails server directly.
Before deploying the project, you need to edit Capistrano config files
located at config/deploy.rb and config/deploy/development.rb.
For a standard project tracked by Git, you do not
need to edit the file config/deploy.rb but you do need to edit
config/deploy/development.rb which is auto-documented.
Capistrano comes with support for multiple stages, you could have
development, staging, production or any other stage, all you need
to have is the stage name mentioned in config/deploy.rb
set :stages, ['development', 'staging', 'production']and a config file by the same name of the stage located at
config/deploy/, the Template is pre-configured for development,
staging and production but comes with only one config file
for development, to configure another stage just duplicate the
development file to the desired stage.
To deploy your project, you need to first configure the server, if you are deploying to a server managed by yourself and using Nginx (Apache templates will be added later), you can generate a config file for your new site, add a user to the database and create the database using the following command:
bundle exec cap development deploy:server:setupThe above step is optional and only useful if you manage your own server, but if you are using a shared server (Hosting), running that command would not be possible as you don't have root access.
NOTE: This command must be used only once per stage per project.
Before deploying you need to setup the project structure, generate the localconfig.php, and the .htaccess, to do that just run
bundle exec cap development deploy:setupNOTE: This command must be used only once per stage per project.
To deploy the project simply run
bundle exec cap development deployAs you may have noticed, all the above commands had the development stage as the first argument (first argument to cap), to deploy to any other stage just use that stage's name instead.
The contao template comes pre-configured with development as the default stage
set :default_stage, :developmentSo if you omit the stage (the first argument) when calling cap
bundle exec cap deployThe stage would be set to whatever default_stage is set to, in this
case development
You do not need to use SSH or phpMyAdmin to export or import a database dump, in fact capistrano already knows the credentials to access the database, so We added a few tasks to help ease this process.
To import a database dump, which is very useful for deploying a website
that was in development on your localhost, you can use the task
db:import (Remember that all the following commands can
optionally take the stage as the first argument, when omited the stage
is set to the default_stage). To import /path/to/project.sql for
example, you only have to use the command
bundle exec cap db:import /path/to/project.sqlThe above command will first backup your database on the server (check
/backups relative to your project directory of course), and then
import the project.sql into it, however it's up to you to make sure your
SQL dump file has DROP TABLE IF EXISTS statements to overwrite the
tables.
To export a database dump, which is very useful to import changes from the server to your local development machine
bundle exec cap db:exportThis file will download the SQL dump file to a random file in /tmp but
you can optionally give it an argument which would be used as a
filename. This command will also backup the database on the server.
TODO: Write this section.
TODO: Write this section.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Added some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
Or
For bugs and feature request, please use Github issues, for other requests, you may use:
- Email: [email protected]
Don't forget to follow me on Github and Twitter for news and updates.
I'd like to give a special thanks to the guys at Agence Durable for supporting and testing this project, Leo Feyer for creating an awesome and easy to use CMS, and of course all Contao contributors, and Finally The Rails Core Team and the entire Ruby community which are simply awesome.
- The
contaofolder is a mess and can become a lot messier pretty quickly so we need to extract each extension into it's folder (make it modularized) - Add Capistrano tasks for Starting/Stopping/Reloading Nginx
- Add Capistrano support for Apache
- The install password should be different for each website and the
developer should be able to modify it, Basically the install password
in
~/.contao/config.ymlshould be stored in clear-text (or encrypted but decryptable), and once we generate a new project we should generate a new salt, store it in an initializer, generate the install password and store it in an initializer as well - A new rake task should be created to help the user easly modify the install password
- The encryption_key should be generated for each project and not
stored in the
~/.contao/config.yml - The assets takes a considerably amount of time to be uploaded, specially if you have many images, we should compress the entire folder, upload it and then extract it on the server, as it would be much faster to upload one file.
contao_template
├── Capfile
├── Gemfile
├── Procfile
├── Rakefile
├── app
│ └── assets
│ ├── images
│ ├── javascripts
│ │ └── application.js
│ └── stylesheets
│ ├── application.css.sass
│ ├── definitions
│ │ ├── _all.sass
│ │ ├── _mixins.sass
│ │ ├── _sprites.sass
│ │ └── _variables.sass
│ └── thirdparty
│ └── _pie.sass
├── config
│ ├── application.rb
│ ├── boot.rb
│ ├── compass.rb
│ ├── deploy
│ │ ├── development.rb
│ │ └── production.rb
│ ├── deploy.rb
│ ├── environment.rb
│ ├── environments
│ │ ├── development.rb
│ │ ├── production.rb
│ │ └── test.rb
│ ├── examples
│ │ └── localconfig.php.erb
│ ├── initializers
│ │ ├── secret_token.rb
│ │ └── session_store.rb
│ └── routes.rb
├── config.ru
├── contao
│ ├── plugins
│ ├── system
│ │ ├── drivers
│ │ ├── libraries
│ │ │ ├── Spyc.php -> ../../../lib/contao/libraries/spyc/spyc.php
│ │ └── modules
│ │ ├── BackupDB
│ │ ├── assets
│ │ ├── efg
│ │ ├── favicon
│ │ ├── googleanalytics
│ │ ├── listing
│ │ ├── parentslist
│ │ ├── subcolumns
│ │ ├── template-override
│ │ ├── videobox
│ │ └── videobox_vimeo
├── lib
│ ├── assets
│ │ └── javascripts
│ │ ├── form_default_values
│ │ │ ├── autoload.js.coffee
│ │ │ └── main.js.coffee
│ │ ├── form_default_values.js
│ │ └── slider.js.coffee
│ ├── contao
│ │ └── libraries
│ │ └── spyc
│ └── tasks
├── public
├── script
│ └── rails
├── spec
│ └── javascripts
│ ├── fixtures
│ │ └── slider.html
│ ├── helpers
│ │ └── spec_helper.js.coffee
│ ├── slider_spec.coffee
│ └── support
│ └── jasmine.yml
└── vendor
└── assets
├── javascripts
└── stylesheetsCopyright (c) 2011 TechnoGate <[email protected]>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.