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
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.)
Insoshi will also work with ImageMagick/RMagick, which are very powerful harder to install:
You also need one of following databases
- SQLite - a self-contained, serverless, zero-configuration, transactional SQL database engine
- MySQL - the popular open source database
Installation instructions can be found on their sites or via a Google search.
Required Gems
Insoshi requires the following gems
- rails
- ferret - for search capability
- image_science - if you're using FreeImage
- rmagick - if you're using RMagick
- sqlite3-ruby - if you're using SQLite as your database engine
- mysql - if you're using MySQL as your database engine
You can install these gems via
gem install <gem>
Configuring Your Insoshi Installation
You will need to set up your database configuration. If you're using SQLite, you can just copy the example file:
cp config/database.example config/database.yml
If you're using MySQL, you'll need to create and configure the database.yml manually. The easiest way is to copy and modify one from an existing Rails application or from a new Rails project that explicitly uses MySQL (rails -d mysql <mysql project>).
Run the following custom rake task
rake install
The install rake task runs 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 the configuration files.
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 and the image_science gem are installed.
Loading Sample Data and Starting the Server
You can load sample data to make development easier:
rake db:sample_data:reload
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 %>