> This is version 2 of SemanticJournal, now shortened to the easier-to-type "Semjo".

Contents of this README file
============================

1. Overview
  1.1 Main Features
  1.2 What's new?
  1.3 Coming soon
  1.4 Example blogs
2. Installing
  2.1 Pre-requisites
  2.2 Getting Started
3. Storing Assets
4. Configuration
5. Deployment
6. Tests
7. Caching
8. Setting the Domain(s) for a blog
9. How the data is organized
  9.1 The semanticjournal database
  9.2 The individual blog databases
10. Themes
11. Feeds

1. Overview
===========

SemanticJournal (or "semjo" for short) is a simple Rails-based blog-engine which uses CouchDB for storage.  It includes some Semantic Web features, such as helpers to aid with marking up elements on public-facing pages with RDFa (such as the date, author, title of articles etc).

1.1. Main Features
------------------
* CouchDB Storage. Each blog has its own CouchDB database.
* Helpers for marking up elements with RDFa
* Host multiple blogs using the same rails app
* Write articles and pages with Textile markup
* Design the theme used for each blog's articles and pages, using HTML and ERB
* Simple but effective caching, using Rack/Cache
* Just provides the blog engine only but...
* Easy to extend with 3rd party plugins (e.g. Disqus for comments, ShareThis for social bookmarking, Google for search etc, Gists for Code/Syntax highlighting, S3 for storing other assets used on your blog).

1.2 What's new
--------------
New features in version 2:
* Rails 3 support
* Now uses latest couchrest_model (http://github.com/couchrest/couchrest_model), taking advantage of some of the great new features (e.g. database proxying).
* 'Pages' feature: create content that isn't blog articles - e.g. for an 'about' page, or your CV, etc.
* Now defaults to memcached for rack-cache store.
* Support for symlinking the blog themes in from another repo.

1.3 TODOs/Coming soon
---------------------
* Tagging/Categories for articles.
* Choice of template for pages.

1.4 Examples of blogs running semjo
-----------------------------------
These blogs are currently running on semjo:
http://ricroberts.com
http://blog.swirrl.com
http://learnlinkeddata.com
http://webofdatablog.com


2. Installing
=============

2.1 Pre-requisites
-------------------
* CouchDB > 0.10
* Rails ~> 3.2
* all the gems in the Gemfile
* (optional) memcached for rack-cache storage in production

2.2 Getting Started
-------------------
1. Clone the repo from github.

2. Run the create_semjo_db rake task to create the main "semanticjournal" CouchDB.
e.g. rake semjo:create_semjo_db

3. Run the create_new_blog rake task to make the CouchDB for your blog. (Each blog needs its own database). The BLOG_HOST parameter is the domain under which you want to appear, and BLOG_NAME is just an internal identifier for the blog (see "How the data is organized" section below for more details). If you don't specify a BLOG_HOST, the blog will be available at #{BLOG_NAME}.semanticjournal.com. Note: don't add http:// to the BLOG_HOST.
e.g. rake semjo:create_new_blog BLOG_NAME='jamestkirk' BLOG_HOST='jimkirksblog.com' COUCH_SERVER='http://127.0.0.1:5984'

4. Run the create_new_user rake task to create a user for the blog. If an account already exists with the ACCOUNT_NAME specified, it will use that one.  The PERSONAL_URI should be an identifier for the person on the web (that ideally, returns rdf).
e.g. rake semjo:create_user ACCOUNT_NAME=jim DISPLAY_NAME='jim kirk' PERSONAL_URI='http://jimkirksblog.com/me.rdf#me' PASSWORD='pwd1' EMAIL='jamestkirk@starshipenterprise.org' BLOG_NAME='jamestkirk' COUCH_SERVER='http://127.0.0.1:5984'

4. Set up an apache virtual host for your blog's domain.  For running in development mode, you'll also need to set up an apache alias and /etc/hosts entry.  (The simplest way to do this is with the "ghost" gem, and the Passenger Pref pane for OS X).

5. Make a new folder in the views/themes folder of the project (at the same level as the ricroberts folder).  Inside that folder, create 2 folders: articles and pages. In articles, create 2 ERB templates: index.erb and show.erb, for your index of articles and for individual posts, respectively. Inside pages, make a template for show.erb, for showing individual pages. (You can use partials to help organise the code).

* In articles/index.html.erb, an instance variable called @articles is available which contains a page's worth of articles. At the moment, the @page_size defaults to 8, but you can change it in ArticlesController#home.  There's a helper called "pagination_links" for providing prev/next page links.
* In articles/show.html.erb, an instance variable called @article is available, which is article being shown.
* In pages/show.html.erb, an instance variable called @page is available, which is the page being shown.

7. In your web browser, navigate to the host you specified in step 2. By default, semjo will redirect you to articles#index (unless you specify a different path in the blogs' home_path property). To log in go to /admin, and enter the email and password you specified in step 3. From there you can create articles or pages.

Happy blogging.


3. Storing Assets
=================

Right now, semjo doesn't provide a means for uploading and storing assets for your blog (such as images, CSS, javascript files etc).  I plan to add a user interface for uploading files to S3 soon, but for the moment, you can just manually stick them on S3 (or your preferred file store), and reference those files from your ERB templates.

Note: Tempting as it may be, I recommend that you DON'T just put these kinds of things in the public folder.  This is because if you're hosting several blogs on your semjo instance, users (including bots) be able to access these public files from any of your blog's urls, leading to confusion (and possibly embarrassment, depending on the different blogs' topics).  You might not want cross-pollination of blog content.


4. Configuration
================

The only configuration you might need to worry about is the location of the CouchDB for your production environment (e.g. if this is on a different server to your web server). This can be set in config/config.yml


5. Deployment
=============

Note: I'm assuming you're running Rails on Passenger.  semjo is not tested on other systems (e.g. Webrick, Mongrel etc).

There's an example capistrano deploy.rb in the config folder which should get you started.


6. Tests
========

The default rake task runs all the unit and funcitonal tests, as you'd expect for a Rails project.  (i.e. just run rake).

The tests will create 2 databases: semjo_test_central and semjo_test_blog.  If these bother you, you can delete them (they will be re-created the next time the tests run).

A couple of the functional tests rely on the semjo_test_blog theme existing, but you can delete it in production if you like.


7. Caching
==========

Semjo uses Rack/Cache. By default this is set up to use memcached.  If you're changing code, and things aren't changing in your browser, try restarting memcached or turning off caching!

The home page is considered to be stale if the most recently updated article has changed since the last request.

An article is considered to be stale if it has been updated since the last request. Likewise for an individual page.



8. Setting the Domain(s) for a blog
===================================

The hosts property of the Blog documents in the semanticjournal CouchDB is an array of all the hosts that correspond to a blog.

If semjo receives a request at one of these hosts it will render the blog in whose array it appears.  If that host is not the first item in that blog's hosts array, it will redirect to the first host in the array.  This is that blog's "canonical url".


9. How the data is organized
============================

As I mentioned in the "Getting Started" Section above, each blog in Semantic Journal has its own CouchDB, and there's also a central/master database called "semanticjournal".

9.1 The semanticjournal database
--------------------------------
The semanticjournal database stores 2 types of document:

* All blogs running on your instance, and their hosts/domains (the "Blog" couchrest document type). See the section above for how to set up domains.

* Accounts in the system (the "Account" document type). An account is a user/person in the system. Accounts can be given log-in access to one or more blogs running on the system.

9.2 The individual blog databases
---------------------------------
* All the articles for an individual blog are stored in a database with the name of the blog (Article documents).

* This database also stores information about which accounts have access to that blog (BlogUsers).  The BlogUser documents will store the role for that account on this blog (when I get around to coding it - at the moment there's only one role, which can do everything).


10. Themes
==========

Semjo will look for themes in the apps/views/themes folder (and also in themes/symlinked folder). Make a folder with the same name as your blog and add templates for:

* 404.html.erb
* articles/show.html.erb
* articles/index.html.erb
* pages/show.html.erb

10.1 Semantic Helpers
---------------------
In your theme, you can use the helper methods in app/helpers/articles_helper, to add semantic markup to your blog post.  Check out the comments in the code and see my blog theme for examples of use.

* rdfa_article_tag
* rdfa_title_tag
* rdfa_author_tag
* rdfa_date_tag


11. RSS Feed
============

semjo generates a feed of the most recently updated 10 articles at /feed.rss.


12. Licence
===========

Semjo is distributed under an MIT licence.

Copyright (C) 2011 by Swirrl IT Limited

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.


13. Contact
===========

We'd love to hear from you if you're using Semjo. hello@swirrl.com