Install from Scratch
From Wontology
Contents |
Introduction
This page provides detailed instructions for installing WontoMedia on your system, so that the system (server) you install it on will provide a wontology (glossary entry) for you or others to use. If you have any problems, please let us know on our forum or email list.
Supported Platforms
The platform on which WontoMedia depends (the Ruby programming language and the Ruby-on-Rails web application framework) are available on and support a wide variety of platforms, operating systems, web servers, and database packages. However, currently our testing of WontoMedia is limited to a single system configuration. It is likely that you can successfully install and run WontoMedia on configurations other than what we've used to test, and we will try to support you in this, but at this point we cannot make any guarantees. If you do install WontoMedia on a different system configuration, please let us know on our forum or email list, whether you have problems or success.
Note that the mechanism we use to support installation-specific customization of WontoMedia's operation and appearance depends on symbolic links in the file system. Do not attempt WontoMedia development except on an operating system and within a file system that supports symbolic links. It is also strongly recommended that you do not install and run WontoMedia in an environment that doesn't support symbolic links (although it might be possible with sufficient investment of manual labor upon each WontoMedia install and upgrade).
WontoMedia Testing Platform
WontoMedia has been developed and tested on the following system configuration:
- the Ubuntu distribution of the GNU/Linux/Debian operating system, 9.04 Jaunty Jackalope release (from here). (Although it is likely to run on any Linux, Windows, or Mac OS system that supports Ruby 1.8, provided a version of Windows supporting symbolic links to files is used.)
- Ruby-on-Rails version 2.3.5.
- MySQL version 5.0, specifically the 5.051a-3ubuntu5.4 package
WontoMedia on Commercial Hosting Providers
WontoMedia has been installed and tested on shared servers at A2 Hosting. Installing on A2 Hosting provides details of the steps involved.
Installation Steps
This section is divided up into sets of steps for each major subsystem on which WontoMedia depends. If you're confident that your system already provides a dependency, you can skip the steps in that section. On a Linux system, most of the commands have to be executed "as root". This is accomplished by the sudo prefix shown on those commands which must be executed as root.
Ruby Language Interpreter
WontoMedia is written in the Ruby programming language. For it to run on your system, the interpreter for Ruby must be installed.
If you are using a Debian-based Linux system, the command for installing the Ruby packages is:
sudo apt-get install ruby rdoc ri
If Ruby is already installed, this command will not do any harm. Or, you can use whatever package-management tool you normally use on your system.
If you are using another platform, or the above doesn't work for you, the Ruby language download page contains the definitive instructions for installing Ruby on other versions of Linux, Windows, and Mac OS X.
RubyGems Package Manager
Most Ruby-language software, including WontoMedia, is distributed in packages called "gems." In order to install gems, the package-management software must be installed first. Start by downloading the most recent version of RubyGems. If you download the .tgz version of the file, the commands for installing RubyGems locally on your system are:
cd [a directory where you want to unpack the temporary RubyGems files] tar -xzf [path to the rubygems file you downloaded] cd rubygems-[version number] sudo ruby setup.rb
After which you can remove the directory created by tar.
Note that there are Debian packages for rubygems and several other pieces of Ruby software. The versions for these tend to lag behind the most recent available as gems, and it can be quite difficult to manage dependencies with some packages installed via apt and others via RubyGems. We will eventually support installation of WontoMedia from a tarball via setup.rb (allowing a Debian-compliant WontoMedia .deb package to be created), but until then, we recommend installing WontoMedia and all of its dependencies as gems, and not through the Debian packager.
Ruby-on-Rails
Given the dependencies above are in place, the commands
sudo apt-get install libopenssl-ruby sudo gem1.8 install rake rails
will install the rails framework that WontoMedia uses, and its dependency. libopenssl-ruby is used by Rails for encryption services and secure network connections. (RubyGems no longer creates a revisionless alias command gem; the "1.8" references the Ruby version it uses.)
System Database
WontoMedia uses Rails' built-in data management, which in turn requires a SQL database system. According to Rails' documentation, the MySQL, PostgreSQL, SQLite, DB2, MS SQL Server, Oracle, and Sybase databases are supported by Ruby on Rails. WontoMedia has been developed to be independent of the particular database used, but to date it has been deployed and tested only with MySQL. The following instructions are specific to MySQL.
Installing a Database
For MySQL, if you are using a Debian-based Linux system, the command for installing MySQL is:
sudo apt-get install mysql-server mysql-client libmysqlclient15-dev ruby1.8-dev sudo gem1.8 install mysql
Depending on your system settings, you may be asked for configuration information during this command. If MySQL is already installed, these commands will not do any harm. Or, you can use whatever package-management tool you normally use on your system.
For MySQL on another platform, or if the above doesn't work for you, the MySQL download pages contain instructions for installing MySQL on other versions of Linux, Windows, and Mac OS X. Note that, to date, WontoMedia has been tested with MySQL 5.0 only.
For a database other than MySQL, you should install using your system's package manager or according to the package's website. Rails may be capable of direct connection to the database you've chosen, or you may need an additional gem for interfacing, like the mysql gem above. If there is a missing gem, it should become clear when you attempt to start WontoMedia, below.
Configuring Your Database
Whether you had to install MySQL or it was already present, a database must be configured for WontoMedia to use. You must create a new logical database under the server's control, and may wish to create a new database "user" for WontoMedia to use. To accomplish this (on Linux for MySQL), the following commands may be used. The first command will be given at the Linux command prompt, and the rest to the interactive mysql tool itself. Also, this assumes that you have assigned a password to the database's root user. If not, omit the -p option from the mysql command and it won't prompt for a password.
mysql -u root -p mysql> CREATE DATABASE [db-name-for-wontomedia]; mysql> GRANT ALL PRIVILEGES ON [db-name-for-wontomedia].* TO [new-user-name]@localhost IDENTIFIED BY [users-password]; mysql> quit;
If you are using a different operating system, the initial mysql command could be different. If a different database, then the SQL statements (the middle two lines) might work for you, but you should verify with the documentation for you database.
WontoMedia Itself
WontoMedia gem
Install WontoMedia as a gem. Execute the command
sudo gem1.8 install wontomedia
which will install WontoMedia to your local gem install directory. If you don't know where this is located on your system, you can find out by executing the command sudo gem1.8 environment. The directory will be shown on the line labeled INSTALLATION DIRECTORY.
WontoMedia Database Configuration
Like any other Ruby-on-Rails web application, in order to run WontoMedia, it has to be configured to access your local database. This is accomplished by creating the file
config/database.yml
within the gem directory. WontoMedia includes the sample file
config/database-mysql.yml
which contains the correct content for installing with a MySQL database, except for the database name, database user, and the database user's password. The content of the sample file are:
production: adapter: mysql encoding: utf8 database: wontomedia_production pool: 5 username: wontomedia-user password: replace-bad-passwd socket: /var/run/mysqld/mysqld.sock
In the config directory, copy the file database-mysql.yml to database.yml. Then edit database.yml to change the place-holders wontomedia_production, wontomedia-user, and replace-bad-passwd to the correct values for your database. (You may need to be logged in as root in order to copy and/or edit the files.)
Once database.yml is in place, the database must be initialized with the correct tables for WontoMedia. This is accomplished by executing the commands:
cd [your gem installation dir]/gems/wontomedia-[version] sudo RAILS_ENV=production rake db:reseed
WontoMedia Application Configuration
WontoMedia is designed to be installed for a wide variety of purposes, and includes several provisions for you to customize its appearance and operation. There are two mechanisms for this: First, a Ruby source file with key constants located in the directory config/initializers called wontomedia.rb. Second, a number of the files that make up the WontoMedia application itself are actually integrated into the application via symbolic links. The standard WontoMedia gem includes default versions of all of these files, in the directory default-custom which you can either use as-is or as the basis for creating versions of your own.
Creating Your wontomedia.rb File
The WontoMedia distribution gem contains a sample file,
assets/wontomedia-sample.rb
which contains a set of Ruby configuration structure definitions like:
require "ostruct"
WontoMedia = OpenStruct.new({
:site_title => "", # last element in page <title>
:site_tagline => "", # top of home page
:ads => OpenStruct.new({
# :amazon => OpenStruct.new({
# :associate_id => "your-amazon-id-here"
# }),
# :google => OpenStruct.new({
# :publisher_id => "your-google-id-here",
# # "data page" is used in the partial common/_google_ads,
# # which is used in [items or connections]/[index or show] pages
# :data_page_slot => "your-google-slot-number-here"
# # create additional _slot variables for different Google ad units
# })
}),
:analytics => OpenStruct.new({
# :google => OpenStruct.new({
# :profile_id => "your-UA-number-here"
# })
})
})
The lines which are commented out are optional, and should be included only if you have values for them particular to your installation. The remaining lines are required, and you should fill in between the empty quotation-mark pairs, "", for your installation. You may use the file exactly as it is if you want a minimal WontoMedia setup.
For your first installation, start by copying the sample file to
config/initializers/wontomedia.rb
and make your local modifications there. For occasions where you are upgrading WontoMedia, you should copy your local version of wontomedia.rb from your old gem directory (installation directory) to your new one before you remove the old. Or, you may use the customization mechanism below to keep a permanent, local version of wontomedia.rb in a location outside of your gem directory, and establish a symbolic link that makes it appear to be in the correct directory/under the correct file name.
Customizing Your Installation
Unlike the wontomedia.rb file, which you should create uniquely for your WontoMedia installation, the distribution WontoMedia gem includes all of the customization files you need, in a state that you can use without modification. These files are located under the directory default-custom, in a directory tree that mirrors the standard Ruby-on-Rails application structure (containing app, public, etc.).
To run, WontoMedia must have access to some version of each file named/contained in the default-custom directory. A WontoMedia installation is configured by making symbolic links from within the main Rails directories (those contained at the top level of the WontoMedia gem's install directory) to your desired version of each customization file. For your initial installation of WontoMedia, you should start by using all of the customization files exactly as they are included in default-custom, in order to ensure that you can get a basic setup running before starting to experiment with customization. To accomplish this, execute the command:
rake customize[default-custom]
Depending on how you installed the WontoMedia gem and your systems local permission settings, you may need to execute the command with "root" permissions by using it with "sudo":
sudo rake customize[default-custom]
The customize rake task can be used to combine together the standard version of the various customization files with local versions you create stored in any number of different (but all parallel) directory trees. The documentation for the WontoMedia customization mechanism, including pointers to instructions on using this particular rake task in more complicated settings, can be found in your WontoMedia install directory at:
doc/customization.markdown
with the latest version of customization.markdown available from GitHub.
Finally, WontoMedia uses the asset_packager Rails plug-in to manage the JavaScript (.js) and Cascading Style-Sheet (.css) files that are included in the pages it serves. To build the packages to be served from the files included in the WontoMedia gem, you must run:
rake asset:packager:build_all
Note that you should not run the asset_packager task before the customize task, because some of the files included by the packager are customizable. And, therefore, any time you chanage your customizations or re-run the customize task, you should re-run the asset_packager command to be safe.
Running WontoMedia
There are many way to serve a Rails application to web browsers, either directly from Ruby or through a more traditional web server. If you already have an environment for serving Rails web applications, you should be able to use that configuration with WontoMedia at this point.
To serve WontoMedia directly, or to test your installation prior to integrating it with a more complicated Rails service mechanism, use the commands:
cd [your gem installation dir]/gems/wontomedia-[version] script/server -e production
At this point, WontoMedia is running on the server you installed on. You should now be able to access your new WontoMedia instance by typing the address:
http://[your server name]:3000/
into your web browser. If you are running your browser on the same system running WontoMedia, you can use the name localhost as your server name if it is more convenient.
