Search this site

Recent site activity

Installation

Insoshi is written in Ruby on Rails, so installing Insoshi means downloading the source code and running it on your local computer.  There are several methods to do this, which we list in order of increasing involvement in the Insoshi project.

Option #1: Source only (easy to download but no updates and hard to contribute)

If all you want is the source code, you can download the most recent release of Insoshi here.  Keep in mind that Insoshi is still evolving rapidly, though, so if you want to get easy updates or contribute you should read on about using Git.

Option #2: Cloning with Git (fairly easy to download, hard to contribute)

The source code to Insoshi is managed via Git, a version control system developed by Linus Torvalds to host the Linux kernel development.  What this means is that you can easily download the Insoshi source, get updates, contribute and manage your own local work.  (For information on installing Git, check out our guide for Installing Git.)

If you're already familiar with Git, you can clone our public Git repository on GitHub via the command
  git clone git://github.com/insoshi/insoshi.git
You should also create a local development branch in your Git repository:
 git checkout -b <firstname_lastname>
where you should replace <firstname_lastname> with the your name (without the angle brackets!).

For more information on configuring your local clone of our repository, check out our Git Guides which also includes a scripted Quick Local Repository Setup (see next).

Option #3 (recommended): Forking at GitHub (still easy to download, easy to contribute)

The best way to get started with Insoshi if you want updates and might want to contribute is to follow the steps on our Quick Local Repository Setup.  This involves going to GitHub and forking our repository, to which you can then make changes.  By issuing a pull request at GitHub, you can let us know about your changes and start the process of incorporating them into Insoshi.  See our extensive Git Guides for more information.

Completing the installation

[This document includes and expands upon the README.rdoc included with the Insoshi code.  Check the README for any changes, especially if you're using the edge branch.]

Once you've gotten the source code using one of the above methods, you should install the libraries and gems needed by Insoshi.

Rails

If you don't already have Rails on your computer, you should download and install Rails now.

Required Libraries

Insoshi recommends using FreeImage and ImageScience for image manipulation:
  • FreeImage - an open source library project that supports standard graphics image formats (PNG, JPEG, etc.)
(If you're installing FreeImage on Windows, take a look at this blog post to avoid some possible headaches and issues.)

Insoshi will also work with ImageMagick/RMagick (more powerful but harder to install):
  • ImageMagick
  • RMagick - installed as a gem but site has details for getting ImageMagick installed/built
You also need one of following databases
  • SQLite - a self-contained, serverless, zero-configuration, transactional SQL database engine (see note for Sphinx below!)
  • MySQL - the popular open source database
  • PostgreSQL - another good choice for an open source database
Insoshi uses Sphinx/Ultrasphinx for search
  • Sphinx
  • Ultrasphinx - Ruby on Rails Sphinx client (included with the Insoshi source under vendor/plugins)
Search using Sphinx is not supported with SQLite.  You'll have to use either MySQL or PostreSQL as your database or disable the search functionality.

When running Insoshi in a production environment, you should also set up a cron job to rotate the search index as described in the Ultrasphinx deployment notes.

Installation instructions can be found on their sites or via a Google search.

Required Gems

Insoshi requires the following gems
  • rails
  • mysql - if you're using MySQL as your database engine
  • chronic - required for Ultrasphinx
  • image_science - if you're using FreeImage
  • rmagick - if you're using RMagick
You can install these gems via 
  gem install <gem>

Optional Gems

If you want Markdown formatting support you can install one of the following gems
  • rdiscount - fast but platform-dependent
  • BlueCloth - slower but pure Ruby

Configuring Your Insoshi Installation

You will need to set up your database configuration.  If you're using MySQL, you can just copy the example file:
  cp config/database.example config/database.yml
Then open up database.yml and set up the passwords to match your system. 

Run the following custom install script
  script/install
The install script will run the database migration and performs some additional setup tasks (generate an encryption keypair for password management,  creating an admin account, etc.)

If the install step fails, you may not have properly set up your database configuration.

Then prepare the test database and run the tests (which are actually RSpec examples in the spec/ directory):
  rake db:test:prepare
  rake spec
If the tests fail in the Photos controller test, double check that FreeImage/image_science or ImageMagick/rmagick are installed.

At this point, you'll need to configure and start the Ultrasphinx daemon for the test runtime
  rake ultrasphinx:configure RAILS_ENV=test
  rake ultrasphinx:index RAILS_ENV=test
  rake ultrasphinx:daemon:start RAILS_ENV=test
and re-run the tests
  rake spec
The search specs detect whether the search daemon is running and weren't performed during the first test run.  An initial test run is needed in order to populate the test database for indexing (search specs would fail on an empty database).

To shut down stop the Ultrasphinx daemon for test
  rake ultrasphinx:daemon:stop RAILS_ENV=test

Loading Sample Data and Starting the Server

You can load sample data to make development easier: 
  rake db:sample_data:reload
configure and start the Ultrasphinx daemon for the development runtime
  rake ultrasphinx:configure
  rake ultrasphinx:index
  rake ultrasphinx:daemon:start
and start the server 
  script/server
Go to http://localhost:3000

All the sample users have the email logins <name>@example.com with the password foobar

So, to log in as michael, use the following

email: michael@example.com
password: foobar

Admin User

To sign in as the pre-configured admin user, use

email: admin@example.com
password: admin

You should update the email address and password.  Insoshi will display warning messages to remind you to do that.

Start Hacking

Now you can open up your favorite editor and start hacking away at the Insoshi source code.

Check out our Git Guides for information on how to manage your local development and how you can contribute your updates back to us.

Stat Tracker

Note that there is a minimalist stat tracker in Insoshi that lets us keep track of how many different installs of Insoshi are out there.  We don't collect any personal information, but if you don't want to be tracked, just open application.html.erb and comment out the line after this one

<%# A tracker to tell us about the activity of Insoshi installs %>