-
Notifications
You must be signed in to change notification settings - Fork 8
Deployment Guide
This application has been successfully deployed using the following environment:
- RedHat Enterprise Linux 5.2 (CentOS 5.x was used for development and QA environments)
- PostgreSQL 8.4
- Apache 2.2.x
This guide assumes you are using a functionally similar setup.
You have installed:
- RHEL5/CentOS 5 or later with the standard "Server" packages.
- the EPEL yum repository.
- Postfix (or equivalent MTA), or else have an SMTP server that will accept connections from this server.
Disable selinux, unless you are willing to add all the policy allow rules for the application. The list of rules is not covered here. Use a tool like audit2allow to obtain this once you have set up the application.
The firewall should allow incoming traffic to http (80) and https (443) ports.
You should have TLS certificates and have installed them on the server.
Create a user for the application to run as, e.g.
root@host $ useradd acdata
You will need to give this user sudo access to cp, mkdir, chown, chmod and /sbin/service. E.g. use visudo to add the following to the sudoers file:
acdata ALL = /bin/mkdir, /bin/cp, /bin/chmod, /bin/chown, /bin/mkdir, /sbin/service
(You'll obviously need to set a password for the acdata user).
Also enable yourself to ssh into the server as this user by adding your public key to this user's .ssh/authorized_keys file.
Install the following RPMs:
yum install gcc gcc-c++ patch readline readline-devel zlib zlib-devel libyaml-devel libffi-devel gd\ openssl openssl-devel make bzip2 autoconf automake libtool bison httpd httpd-devel apr-devel apr-util-devel \ mod_ssl mod_xsendfile ntp postgresql84 postgresql84-libs postgresql84-server postgresql84-devel \ curl curl-devel openssl openssl-devel tzdata libxml2 libxml2-devel libxslt libxslt-devel sqlite-devel git
Note: We ideally want PostgreSQL >= 8.4. On earlier versions of CentOS you need to specify postgresql84 (obtained from the EPEL library). On later versions of RHEL/CentOS the standard postgresql RPMs are version 8.4 or later. Adjust the above list of packages as needed.
If your system doesn't have a cron daemon installed by default, you'll need one. Try vixie-cron for CentOS 5 or less, and cronie for CentOS 6 or greater.
Initialise the PostgreSQL server if it hasn't been done previously, i.e.
root@host $ service postgresql initdb
While not necessary, we highly recommend you install the Ruby Version Manager (rvm). It enables you to install specific versions of Ruby and Rubygems without affecting the system version of Ruby.
As the user you created (e.g. acdata, not root), install rvm:
acdata@host $ curl -L get.rvm.io | bash -s stable acdata@host $ source ~/.rvm/scripts/rvm
Install Ruby. The web application was built against 1.9.3-p194. While it will probably will work with later versions, you would need to regression test it to be certain. Even minor version number changes in Ruby can break some compatibility.
acdata@host $ rvm install ruby-1.9.3-p194 acdata@host $ rvm use ruby-1.9.3-p194
Create a gemset, and then install bundler and passenger
acdata@host $ rvm use @acdata --create acdata@host $ gem install bundler -v 1.0.20 acdata@host $ gem install passenger acdata@host $ passenger-install-apache2-module
Take note of the Apache configuration directives issued by Passenger. E.g.
LoadModule passenger_module /home/acdata/.rvm/gems/ruby-1.9.3-p194@acdata/gems/passenger-3.0.12/ext/apache2/mod_passenger.so PassengerRoot /home/acdata/.rvm/gems/ruby-1.9.3-p194@acdata/gems/passenger-3.0.12 PassengerRuby /home/acdata/.rvm/wrappers/ruby-1.9.3-p194@acdata/ruby
Don't cut and paste the above.
The paths to passenger in particular will be used when updating the Apache configuration for the web application.
Create the directories that you will use to store the data files (you'll put these path into your configuration file in later steps).
You'll need a place that the user you created (e.g. acdata) can write files to. For example if the volume that /home is mounted on has sufficient space, you can create these under /home/acdata/data
You need a directory for project data, rda (RIF-CS) records, and MemRE exports. E.g.
acdata@host $ pwd /home/acdata acdata@host $ mkdir -p data/projects data/rda data/memre
Take note of these paths as you will need to put them in a configuration file later.
Start the database and ensure it starts automatically on server (re)start.
root@host $ service postgresql start root@host $ chkconfig --level 345 postgresql on
Create a role to be used to access the database. You'll need to be the postgres user. The default role in the web application's configuration file is "acdata".
root@host $ su - postgres postgres@host $ createuser -U postgres -P acdata Enter password for new role: [password] Enter it again: [password] Shall the new role be a superuser? (y/n) n Shall the new role be allowed to create databases? (y/n) y Shall the new role be allowed to create more new roles? (y/n) n
Configure PostgreSQL to allow local connections via password.
Edit /var/lib/pgsql/data/pg_hba.conf changing the local and host authentication from "trust" (or "ident") to "password" as below:
# "local" is for Unix domain socket connections only local all all password # IPv4 local connections: host all all 127.0.0.1/32 password
Then restart PostgreSQL
root@host $ service postgresql restart
Unless you are installing this on the exact same host, you will need to change some of the configuration. Create a fork of this repository that you can make and commit your changes in.
You will need a Unix-like (e.g. Linux or Mac OS X) environment to clone your fork of this application to. Follow the Developer Guide to prepare your environment. Make sure that you clone your fork.
You will need to edit a number of files before you can deploy. You will then need to commit those changes and push them to your fork of the repository.
You will be editing
- Rails application configuration - data paths and email addresses
- User management emails (Devise)
- Deployment configuration (Capistrano)
- Database configuration
- Apache configuration
- Authentication System Configuration (LDAP)
- Initial users
Edit config/acdata_config.yml and set the following:
- account_request_user_status_email_sender
- account_request_admin_notification_sender
- ands_publishable_moderator_notification_sender
- slide_scanning_request_notification_sender
- slide_scanning_request_admin_email
- files_root
- rda_files_root
- memre_files_root
- deploy_config_root
files_root, rda_files_root and memre_files_root are the full paths of the directories you created in the Create Required Directories step earlier.
deploy_config_root is the directory where a template configuration file will be installed (and later referenced) that holds sensitive configuration items (like username/password values for external systems that ACData integrates with). This configuration file is detailed in the Post Installation section below. The value of this item should probably be the home directory of the user you created (e.g. /home/acdata).
Edit config/environments/production.rb to set the base URL used in links in email sent:
config.action_mailer.default_url_options = { :host => 'HOSTNAME' }
If you're using development, staging and qa environments, then you can edit those files as well.
In config/initializers/devise.rb edit the line for the sender email address:
config.mailer_sender = "changeme@HOSTNAME"
Edit config/deploy.rb to set the URL of your fork of the acdata repository:
set :repository, 'https://github.com/[YOUR GITHUB ACCOUNT]/acdata.git'
Edit config/deploy/production.rb to set the user, base deployment directory, base data directory, and the hostnames of web server, application server (which would be the same as the web server), and the database server (which is often the same as the web server).
set(:user) { 'acdata' }
set :deploy_base, '/home/acdata'
set :data_dir, '/home/acdata/data'
set(:deploy_to) { "#{deploy_base}/acdata-web" }
# Your HTTP server, Apache/etc
role :web, 'www.researchdata.unsw.edu.au'
# This may be the same as your Web server
role :app, 'www.researchdata.unsw.edu.au'
# This is where Rails migrations will run
role :db, 'www.researchdata.unsw.edu.au', :primary => true
Also edit config/deploy/staging.rb and config/deploy/staging.rb if you wish to deploy to multiple environments (see Capistrano Multistage Extension for more details).
In config/database.yml edit the database configuration. Set the password for the non-production sections and if needed change the username, host or other settings:
production: adapter: postgresql host: localhost database: acdata username: acdata password: '******' pool: 5 timeout: 5000
You can leave the password as '******' as you'll be prompted to give the actual password when running the deploy script.
You will need to alter the Apache configuration file to reflect the version of Passenger you installed, the IP address of the server, the paths to the TLS certificates (if any), and other settings as needed.
Under config/httpd/ are Apache configuration files for production, staging and qa servers. The appropriate one is deployed into /etc/httpd/conf.d/rails_acdata.conf.
Use the lines output from running passenger-install-apache2-module that you should have noted earlier to replace the 3 passenger configuration lines in the production_rails_acdata.conf configuration file.
Of all the configuration, only the following is absolutely essential for rails to run:
LoadModule passenger_module /home/intersect/.rvm/gems/ruby-1.9.3-p194@acdata/gems/passenger-3.0.11/ext/apache2/mod_passenger.so
PassengerRoot /home/intersect/.rvm/gems/ruby-1.9.3-p194@acdata/gems/passenger-3.0.11
PassengerRuby /home/acdata/acdata-web/current/script/production_ruby_with_env
RailsEnv production
<Directory /home/acdata/acdata-web/current/public>
AllowOverride all
Options -MultiViews
</Directory>
You'll almost certainly want to have some form of https virtualhost configuration though, to at least keep your passwords from being intercepted when you login.
Authentication is via LDAP. The UNSW instance of ACData uses the UNSW ActiveDirectory instance for authentication (which is only accessible to certain hosts on the UNSW network).
If you are using another directory for authentication then change the configuration in config/ldap.yml appropriately.
In config/initial_users.yml is a list of users (which should be present in the UNSW ActiveDirectory system) which will be added to the ACData application as pre-approved (i.e. ready to login) users. Edit this file to add/remove the users you want. The password field is irrelevant to the production system and is ignored.
On your local machine review the files you've changed:
user@local $ git status # On branch master # Changed but not updated: # (use "git add ..." to update what will be committed) # (use "git checkout -- ..." to discard changes in working directory) # # modified: config/acdata_config.yml # modified: config/environments/production.rb # modified: config/httpd/production_rails_acdata.conf # modified: config/initializers/devise.rb # no changes added to commit (use "git add" and/or "git commit -a")
user@local $ git add . user@local $ git status # On branch master # Changes to be committed: # (use "git reset HEAD ..." to unstage) # # modified: config/acdata_config.yml # modified: config/environments/production.rb # modified: config/httpd/production_rails_acdata.conf # modified: config/initializers/devise.rb #
user@local $ git commit -m "Configuration changes for new deployment" . [master 8096f2a] Configuration changes for new deployment 4 files changed, 37 insertions(+), 68 deletions(-) rewrite config/httpd/production_rails_acdata.conf (90%)
user@local $ git push Counting objects: 19, done. Delta compression using up to 2 threads. Compressing objects: 100% (10/10), done. Writing objects: 100% (10/10), 1.03 KiB, done. Total 10 (delta 9), reused 0 (delta 0) To git@github.com:seandmccarthy/acdata.git 0ff4e53..8096f2a master -> master
First time, from your development environment:
$ cap production deploy:setup $ cap production deploy:update
The deploy:update task will prompt you for the database user password. This is the password you assigned to the acdata database role in the Database Setup section previously.
Then execute the following to create the database and populate it.
$ cap production deploy:db_create $ cap production deploy:schema_load $ cap production deploy:seed
Ensure that the Apache user can read the web application files. Assuming the user you created has their own group, and the group has read permission to the web application files (e.g. /home/acdata/acdata-web), then you could add the Apache user to the group.
Subsequent deployments will generally only need:
$ cap production deploy:update
To perform a full redeploy run:
$ cap production deploy:full_redeploy #To redeploy with migrations being performed automatically run $ cap production deploy:safe
You will have a bare deployment configuration file called acdata_deploy_config.yml deployed into the deploy_config_root directory you configured in the config/acdata_config.yml file (e.g. into /home/acdata/data).
You need to configure this with the URLs, UIDs, passwords etc. for integration with the following systems:
- NMR
- MemRE
- Aperio
Fill in the (currently empty) values for each of the attributes.
With the installation and configuration complete, you can start the web server:
root@host $ service httpd start
Check that you can successfully visit the site at the hostname or IP you configured.
If you have problems you can check both the Apache logs and also web application logs in the logs directory under the acdata directory (e.g. under /home/acdata/acdata-web/shared/log).