-
Notifications
You must be signed in to change notification settings - Fork 8
Local Deployment Guide
This application has been successfully deployed using the following environment:
- RedHat Enterprise Linux 5.2 (CentOS 6.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 6 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 unzip \ openssl openssl-devel make bzip2 autoconf automake libtool bison httpd httpd-devel apr-devel apr-util-devel \ mod_ssl mod_xsendfile ntp postgresql postgresql-libs postgresql-server postgresql-devel
yum install curl curl-devel openssl openssl-devel tzdata libxml2 libxml2-devel libxslt libxslt-devel sqlite-devel git
If your system doesn't have a cron daemon installed by default, you'll need one. Try 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 code_base tmp
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 # IPv6 local connections: host all all ::1/128 password
Then restart PostgreSQL
root@host $ service postgresql restart
acdata@host $ cd acdata@host $ cd code_base acdata@host code_base $ wget https://github.com/IntersectAustralia/acdata/archive/master.zip -O master.zip acdata@host code_base $ unzip master.zip
Copy of the code is now in : code_base/acdata-master
acdata@host $ cd acdata@host $ cd code_base/acdata-master acdata@host $ bundle install
You will need to edit a number of files before you can deploy.
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/production_local.rb to set the user, base deployment directory, base data directory, code base directory. You may need to change:
set(:user) { 'acdata' }
set :deploy_base, '/home/acdata'
set :data_dir, '/home/acdata/data'
set(:deploy_to) { "#{deploy_base}/acdata-web" }
set :deploy_via, :copy
set :scm, :none
set :repository, "/home/acdata/code_base/acdata-master/"
set :use_sudo, true
set :copy_dir, "/home/#{user}/tmp/"
set :remote_copy_dir, "/tmp"
- user is your unix user name
- deploy_base, data_dir are the full paths of the directories you created in the Create Required Directories step earlier
- repository is full path to the directory where you downloaded code
In config/database.yml edit the database configuration. Set the password for the 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.
If you do not want to enable SSL then please remove the lines in the file that refer to SSL. Please ensure you enter the correct Virtual Host and Server name. Also ensure the directories in that file reference the home directory of the acdata user you created.
Authentication is via LDAP. CREATE a new config/ldap.yml with following contents:
## Authorizations
# Uncomment out the merging for each environment that you'd like to include.
# You can also just copy and paste the tree (do not include the "authorizations") to each
# environment if you need something different per environment.
authorizations: &AUTHORIZATIONS
## Requires config.ldap_check_attributes in devise.rb to be true
## Can have multiple attributes and values, must match all to be authorized
require_attribute:
objectClass: inetOrgPerson
## Environments
production:
host: HOSTNAME
port: 389
attribute: cn
base: BASE_DN
admin_user: ADMIN_USER_DN
admin_password: ADMIN_USER_PASSWORD
ssl: false
Replace HOSTNAME/BASE_DN/ADMIN_USER_DN/ADMIN_USER_PASSWORD with your settings. Usually your system administrator should know all the details of these settings.
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.
Please note each of this commands will prompt for password (first prompt after run) this is you unix username password. First time, from place where you have the code:
$ cap production_local deploy:setup $ cap production_local 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_local deploy:db_create $ cap production_local deploy:schema_load $ cap production_local 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.
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).
##Subsequent deployments
When you just want to update the code leaving all setting and database untouched here is the simplest way.
- Get latest version of the code and put it in the same place where you put during initial deployment. Make sure you remove previous version
acdata@host $ cd acdata@host $ cd code_base acdata@host $ rm master.zip acdata@host $ rm -Rf acdata-master acdata@host code_base $ wget https://github.com/IntersectAustralia/acdata/archive/master.zip -O master.zip acdata@host code_base $ unzip master.zip acdata@host code_base $ cd acdata-master
- Get a copy of yours previously changed config files
acdata@host acdata-master $./restore_config.sh
You need to specify deploy_base_folder. That is folder that you originally specified in production_local.rb file as :deploy_base during installation. In this example that would be:
acdata@host acdata-master $./restore_config.sh /home/acdata
- Update the code
acdata@host acdata-master $ cap production_local deploy:update_code