.. snf-cloudcms documentation master file, created by sphinx-quickstart on Wed Feb 22 18:07:30 2012. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to snf-cloudcms's documentation! ======================================== Introduction ============ snf-cloudcms is a cms application based on `django`_ and `feincms`_. The project created to power websites that provide information about the `cloud services`_ deployed by `GRNET`_. At the current state the application provides the following features: * Basic cms funcionality (adding/removing/editing hierarchical pages) * Blog application * FAQ application * Resources application (for presentations, technical papers etc.) * User guide application .. _django: http://www.djangoproject.com .. _feincms: http://feinheit.ch/media/labs/feincms/ .. _cloud services: http://docs.dev.grnet.gr/ .. _GRNET: http://www.grnet.gr/ Installation ============ Using debian packages --------------------- Although not required it is recommended to use `snf-webproject`_ to deploy the cms application. If you want to deploy using your custom django project take a look on ``cloudcms/synnefo_settings.py`` where `snf-webproject` hooks are defined to find which django settings are required for cms to work. .. _snf-webproject: http://docs.dev.grnet.gr/snf-webproject .. note:: Synnefo components and additional required packages can be obtained from ``apt.dev.grnet.gr`` debian repository. To enable the repository add the following lines in ``/etc/apt/sources.list.d/apt.dev.grnet.list``:: deb http://apt.dev.grnet.gr squeeze main deb-src http://apt.dev.grnet.gr squeeze main Install required packages:: apt-get install snf-common snf-webproject apt-get install python-django-feincms python-django-pagination python-django then, install ``snf-cloudcms`` package:: apt-get install snf-cloudcms Change settings in ``/etc/synnefo/20-snf-cloudcms-*.conf`` to match your deployment needs. Deployment ========== For information on how to configure and initialize database and serve ``snf-cloudcms`` static files please refer to `snf-webproject`_ documentation. .. note:: ``snf-cloudcms`` won't work with ``snf-webproject < 0.9.0`` ``snf-cloudcms`` uses the django sites framework so that multiple cms sites can be deployed from the same django project and share common content. For each service site you want to deploy you should set the appropriate ``CLOUDCMS_SITE_ID`` environmental variable to match the site id added in your cms databse. A quick way to initialize the sites you want to deploy is to create a simple fixtures file ``mysites.json`` containing the following:: [ { "pk": 1, "model": "sites.site", "fields": { "domain": "okeanos.grnet.gr", "name": "okeanos.grnet.gr" } } ] and load the fixtures in your db using:: snf-manage loaddata ./mysites.json After that you can deploy each of the sites you included in the above fixtures file using your prefered deployment method (fcgi, gunicorn etc.). e.g. using django internal http server:: export CLOUDCMS_SITE_ID=1 snf-manage runserver If you skipped superuser creation as prompted on your database initialization step, you should create one now:: snf-manage createsuperuser Now you will be able to login using the superuser credentials you provided on the above command on ``http:///cmsmanage/`` url and start editing the content of your cms. Static files ------------ snf-cloudcms requires the following static files to be served by your django project: * feincms static files for the admin interface * django.contrib.admin static files * snf-cloudcms static files If you are using `snf-webproject`_ to deploy your cms all static file handlers should be taken care for you and no additional steps required in the deployment process. This automatic behaviour can be enabled/disabled from the ``WEBPROJECT_SERVE_STATIC`` setting. If you want to disable serving static files from your django project, set ``WEBPROJECT_SERVE_STATIC`` to False in your settings and configure your web server to serve static files of the following locations to the specific urls which can be altered in your settings files: * /feincms/static/ -> FEINCMS_ADMIN_MEDIA (default:/static/feincms/) * /django/contrib/admin/media/ -> ADMIN_MEDIA_PREFIX (default:/static/djangoadminmedia/) * /cloudcms/static/ -> MEDIA_URL (default:/static/) CMS uploads ----------- snf-cloudcms uses feincms medialibrary application to store and display files in cms pages. The location of those files is based on MEDIA_ROOT setting and is calculated using the following expression:: MEDIA_ROOT + '/medialibrary/' if you deploy using `snf-webproject`_ this defaults to ``/usr/share/synnefo/static/medialibrary`` which you should create and grant appropriate permissions for web app to be able to access it. e.g. if you deploy using nginx/gunicorn and your gunicorn workers run with www-data user permissions:: mkdir /usr/share/synnefo/static/medialibrary chown www-data:www-data /usr/share/synnefo/static/medialibrary chmod o+rw /usr/share/synnefo/sattic/medialibrary Admin guide =========== Bind blog application to a cms page ----------------------------------- 1. Create a page on the cms tree using the ``Blog template`` template. 2. On the region you want the blog content to appear (list of posts, and post details), add an ``Application content`` content type and choose ``Cloud blog`` from the drop down list. 3. On navigation extension settings of the page, choose ``blog categories``. Bind FAQs application to a cms page ----------------------------------- 1. Create a page on the cms tree using the ``FAQ's template`` template. 2. On the top region add an ``Application content`` content type and choose ``Cloud FAQ`` from the drop down list. 3. *Optional:* On navigation extension settings of the page, choose ``faq categories``. Bind resources application to a cms page ---------------------------------------- 1. Create a page on the cms tree. 2. On the region you want the resources to appear append a ``Resources list`` content type. Bind Userguide application to a cms page ----------------------------------------- 1. Create a page on the cms tree using the ``Userguide template`` template. 2. On the top region add an ``Application content`` content type and choose ``Cloud user guide`` from the drop down list. Importing FAQ's and Userguide entries from rst files ---------------------------------------------------- Cloudcms provides a way to import content for faq and userguide applications from rst files. This allows you to keep the guide and faq content tracked in rst markup format seperately from the cms database (e.g. in a git repository maintained by your documentation team), and update the cms content on demand. .. warning:: Notice that you can still edit the FAQ's and Userguide entries using the corresponding section in the cms admin interface, but beware that mixing both methods is not recommended since it's ineffective and prone to data loss. To access the import form, login to the admin site and open the following url:: https://cms.com/cmsmange/rstimport/ The required file should be a zip archive containing files of the following structure (similar to common sphinx project structure):: ├── README.rst └── source ├── conf.py ├── faq │   ├── cyclades.rst │   ├── index.rst │   ├── okeanos.rst │   └── pithos.rst ├── images │   ├── cyclades │   │   ├── image10.png │   │   └── image9.png │   ├── faq │   │   └── faq_image1.png │   ├── intro_img_cyclades.png │   └── pithos_guide │   └── image2.png ├── index.rst └── userguide ├── cyclades.rst ├── index.rst ├── pithos.rst └── quick-intro.rst .. warning:: Notice that directory names ``faq``, ``userguide`` are mandatory. By submiting the form the application will act as follows - Clean existing data if ``clean data`` was checked. This includes **all** FAQ/Userguide entries, FAQ categories and media files linked to them. - Will search for files named after the ``CMS_RST_IMPORT_SERVICE_FILE_MAP`` setting both in ``faq`` and ``userguide`` directories, to identify which service the contents of the file are referred to. The default setting value is (maps files to service slugs):: DEFAULT_SERVICE_MAP = { 'cyclades': 'cyclades', 'okeanos': 'okeanos', 'pithos': 'pithos' } - For the FAQ entries which are structured by service/category, the importer will parse secondary headings as FAQ categories and tertiary headings as FAQ entries. - For the Userguide entries which only require the service to be linked to, the secondary headings and their content are parsed as Userguide entries - For both FAQ and Userguide entries the linked images will be uploaded in the media files application and the html anchors will get updated containing a valid cms link. .. warning:: Import helper uses python ``docutils`` to parse .rst files contents. This means that additional sphinx directives like ``:ref:`` or ``.. code-block`` won't be parsed as excpected. This behaviour might get improved in future versions. Until then try to compromise your content to `basic rst format`_. .. _basic rst format: http://docutils.sourceforge.net/docs/user/rst/quickstart.html .. include:: ../../Changelog Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`